Dodatek D Instrukcje do programów

D.1 Instrukcja użytkownika programu `paramd`

D.1.1 Wstęp

Program paramd jest serwerem HTTP, który udostępnia informacje o wartościach parametrów uzyskanych z zewnętrznego źródła, w szczególności ze sterowników przemysłowych. Jest częścią systemu ISL, umożliwiającego kontrolowanie przebiegu procesu technologicznego przez sieć Internet. Pozwala także na ustawianie wartości parametrów. Podstawową jego rolą jest rola serwera pomocniczego dla serwera przetwarzającego dokumenty xslt (np. Apache Cocoon lub ISL xsltd). Po uruchomieniu programu można podglądać wartości parametrów także w postaci HTML, za pomocą dowolnej przeglądarki internetowej.

Wszelkie zauważone błędy proszę zgłaszać do autora: pawel@praterm.com.pl.

D.1.2 Instalacja

Program był pisany i testowany na komputerze z systemem operacyjnym Mandrake Linux 8.1 i 8.2, oraz RedHat Linux 6.2, 7.2 i 7.3. Nie powinno być jednak większych problemów z jego kompilacją i uruchamianiem także w innych dystrybucjach Linuksa.

Instalacja programu polega na skompilowaniu go przez wydanie poleceń:

./configure
make

w głównym katalogu projektu ISL.

Wcześniej może być konieczne ustalenie w pliku paramd/Makefile.in prawidłowej ścieżki do katalogu ze skompilowanymi źródłami systemu SZARP.

Po udanej kompilacji w katalogu paramd powstaje plik paramd, gotowy do uruchomienia. Może być uruchamiany z dowolnego katalogu. Po wydaniu polecenia make install zostanie zainstalowany w odpowiednim katalogu, domyślnie /opt/szarp/bin.

Do kompilacji program wymaga kilku bibliotek, z których część nie musi być standardowo dostępna w systemie. Jedną z nich jest jest libSzarp -- biblioteka systemu SZARP firmy Praterm.

D.1.3 Konfiguracja

Konfiguracja programu jest trzymana w pliku /etc/szarp/szarp.cfg. Dokładny opis formatu tego pliku zawiera dodatek A.1. Parametry są standardowo czytane z sekcji o nazwie paramd. Jeśli nie zostaną w niej znalezione, to będą szukane w sekcji głównej. Są to:

port -- port TCP/IP, na którym serwer będzie przyjmować połączenia; domyślnie jest to port 8081.
PTT -- ścieżka do pliku PTT.act, zawierającego opis dostępnych w systemie parametrów. Parametr jest wymagany.
log -- plik z dziennikiem programu, do którego będą wypisywane komunikaty informacyjne i o błędach. Plik ten musi być dostępny do zapisu dla użytkownika uruchamiającego program. Domyślnie jest to plik paramd.log w aktualnym katalogu.
log_level -- poziom komunikatów rejestrownych w dzienniku, od 0 (tylko błędy), do 10. Domyślnie jest to poziom 2. Dokładniej, poziomy mają następujące znaczenie:
- 0 istotne błędy, powodujące przerwanie wykonywania programu lub jego istotnej części (np. brak pamięci), mogące też świadczyć o błędach w programie.
- 1 ostrzeżenia o niemożności wykonania istotnego fragmentu programu, świadczące zazwyczaj o błędach w konfiguracji.
- 2 podstawowe informacje o wykonanych działaniach, mogące służyć do oceny rodzaju i częstości wykonywania zadań (np. podstawowa informacja o zapytaniach obsłużonych przez serwer HTTP).
- 3 dodatkowe informacje statystyczne i wydajnościowe.
- 4 komunikaty o błędach o charakterze tymczasowym (np. niemożność połączenia się z serwerem).
- 5 komunikaty przydatne przy testowaniu nowej konfiguracji.
- 10 komunikaty pomocne przy szukaniu przyczyn błędów w działaniu programu -- odpluskwianie (ang. debugging).
timeout -- czas w sekundach, po jakim w razie braku reakcji klienta połączenie TCP/IP zostanie zamknięte. Dotyczy to zarówno sytuacji, gdy klient nie zdążył przesłać całego żądania HTTP, jak i zamknięcia nieaktywnego połączenia trwałego (persistent). Domyślnie jest to 30.
max_connections -- maksymalna liczba jednocześnie otwartych połączeń z klientami. Większa wartość umożliwi obsługę większej liczby stałych połączeń z klientami, ale zwiększa obciążenie systemu, na którym działa serwer. Jeżeli liczba otwartych połączeń zbliża się do podanej wartości, to serwer nie pozwala na nawiązywanie stałych połączeń. Liczniki połączeń dla różnych portów są oddzielne -- tak więc przy ustawieniu maksymalnie 10 połączeń możliwe jest np. 10 połączeń http na porcie 8081 i 10 połączeń https na porcie 8082. Domyślnie jest to 10.
update_freq -- częstotliwość w sekundach odświeżania informacji o wartościach parametrów. Wartości parametrów są odczytywane tylko na żądania klientów, ale nie częściej niż co podaną liczbę sekund. Domyślną wartością jest 10, co odpowiada częstotliwości odświeżania wartości próbek w systemie SZARP.
parcook_path -- ścieżka do pliku, który posłuży jako klucz do generowania identyfikatora pamięci dzielonej parametrów. Zwykle jest to ścieżka do programu parcook lub netpar systemu SZARP. Programy te do tworzenia segmentów pamięci dzielonej korzystają z parametru o takiej samej nazwie z pliku /etc/szarp/szarp.cfg, ale czytanego zawsze z sekcji głównej. Parametr jest wymagany.
html_header -- napis, który będzie wypisywany na początku każdego dokumentu HTML generowanego przez program. Powinien w szczególności zawierać poprawny nagłówek HTML, a więc znaczniki otwierające <html> i <body>. Domyślny nagłówek ma postać:
```
<html>
 <head>
  <title>
  Paramd output
  </title>
 </head>
 <body>
```
Prostym sposobem na automatyczne odświeżanie wysyłanych przez program stron HTML jest wstawienie do nagłówka html następującego tekstu:
```
<meta http-equiv="Refresh" content="10; http://hostname:8081">
```
Ponieważ serwer używa kodowania Unicode (UTF-8), więc tekst wstawiony jako zawartość tego parametru także musi być zakodowany w UTF-8.
html_footer -- tekst dołączany na koniec każdego dokumentu HTML generowanego przez program. Domyślnie zawiera tylko odpowiednie znaczniki zamykające:
```
 </body>
</html>
```
Podobnie jak w przypadku poprzedniego parametru, tekst powinien być zakodowany w UTF-8.
ssl -- czy uruchomić także serwer z autoryzacją HTTP, korzystający z szyfrowanego połączenia przez protokół https. Poza udostępnieniem bezpiecznego, szyfrowanego podglądu danych umożliwia on także ustawianie wartości parametrów. Serwer jest uruchamiany tylko wtedy, gdy wartością parametru jest napis yes.
keypass -- hasło użyte do zakodowania prywatnego klucza RSA serwera, domyślnie paramd. Zobacz też opis opcji key.
key -- ścieżka do pliku zawierającego prywatny klucz RSA serwera. Klucz ten może być wygenerowany na przykład przez wydanie polecenia make ssl w katalogu ze źródłami programu. Tworzony jest plik server.pem, kopiowany także do katalogu /opt/szarp/resources. Hasło używane do zakodowania klucza jest zapisane w pliku config.ssl (parametr output_password). Aby serwer działał, to samo hasło musi być podane jako wartość parametru keypass w konfiguracji programu. Domyślnie klucz jest czytany z pliku server.pem w katalogu głównym.
cert -- ścieżka do pliku zawierającego certyfikat serwera. Jest on generowany razem z kluczem (patrz opis poprzedniej opcji) i zapisywany w tym samym pliku -- choć użytkownik może też podać inny plik z prawidłowym certyfikatem x509. Wygenerowany certyfikat ma następujące parametry:
```
E  = pawel@praterm.com.pl
CN = [nazwa komputera]
OU = ISL
O  = PRATERM SA
L  = Warsaw
ST = Poland
C  = PL
```
Ważność wygenerowanego certyfikatu wynosi 1 rok. Domyślnie certyfikat jest czytany z pliku server.pem w katalogu głównym.
ssl_port -- port, na którym będzie nasłuchiwał serwer z autoryzacją, domyślnie jest to port 8082.
access -- ścieżka do pliku definiującego prawa do ustawiania wartości parametrów. Domyślnie jest to plik access.conf w katalogu głównym. Plik ten zawiera wiersze o następującej postaci:
```
[ścieżka do węzła]:[nazwa użytkownika]
```
Wiersze o innej postaci są ignorowane. Ścieżka opisuje parametr lub węzeł w drzewie parametrów, a nazwa użytkownika oznacza użytkownika, który ma prawo do ustawiania danego parametru lub grupy parametrów zawartej w podanym węźle. Ścieżki do węzłów i parametrów powinny być podane w kodowaniu UTF-8. Przykładowy plik może wyglądać tak:
```
/:root
/Kocioł1:palacz1
/Kocioł2/Sterownik/temperatura\zadana:palacz2
```
Do ustawienia parametru potrzebne jest także podanie hasła. Serwer sprawdza, czy użytkownik o podanej nazwie ma prawo do ustawiania danego parametru, a także czy istnieje taki użytkownik na serwerze i czy podane hasło jest prawidłowe. Korzystanie z haseł systemowych wymaga obecności w katalogu /etc/pam.d pliku paramd o następującej zawartości:
```
#%PAM-1.0
auth       required     /lib/security/pam_stack.so service=system-auth
```
Plik ten jest tworzony automatycznie także po wydaniu polecenia make ssl w katalogu ze źródłami programu.

Przykładowy plik konfiguracyjny może wyglądać tak:


PTT=/opt/szarp/leg1/config/PTT.act
parcook_path=/opt/szarp/bin/parcook

:paramd
port=8081
log_level=4
log=/var/log/paramd.log
max_connections=10
timeout=30
ssl_port=8082
keypass=paramd
access=/opt/szarp/resources/paramd_access.conf
key=/opt/szarp/resources/server.pem
cert=/opt/szarp/resources/server.pem
ssl=yes

D.1.4 Uruchamianie

Program może być uruchomiony z parametrami postaci -Dvar=value. Parametry te pozwalają na ustalenie wartości zmiennych przekazywanych do parsera pliku konfiguracyjnego, mogą więc wpływać na konfigurację programu. Dokładny opis można znaleźć w dokumentacji do biblioteki libparNT, będącej częścią systemu SZARP (dodatek A.1).

Po uruchomieniu, jeżeli nie wystąpią żadne błędy, program sam usuwa się w tło, przekazując kod powrotu 0. Jeżeli wystąpił błąd, to kod powrotu jest równy 1. Informacje o błędach i ewentualne inne (zależnie od ustawionego w pliku konfiguracyjnym poziomu komunikatów diagnostycznych), dostępne są w dzienniku programu.

Po uruchomieniu program oczekuje na przychodzące połączenia na zadanym porcie TCP/IP i w odpowiedzi na żądania przeglądarki generuje stronę HTML lub dokument XML o odpowiedniej zawartości.

D.1.5 Działanie serwera

Program implementuje niewielki, ale funkcjonalny podzbiór protokołów HTTP w wersji 1.0 i 1.1. Obsługuje połączenia stałe (nagłówek Connection: Keep-Alive), które zgodnie ze specyfikacją są domyślne przy użyciu wersji HTTP/1.1. Odpowiada wersją protokołu taką samą, w jakiej przyszło zgłoszenie klienta. Jedyną obsługiwaną metodą HTTP jest GET. W przypadku błędów, odsyła informację z kodem błędu HTTP, zgodnie z RFC 2616. Jedynym dostępnym kodowaniem wyjściowym jest UTF-8 (Unicode). Dokumenty serwowane są z nagłówkiem Expires zgodnym z częstotliwością odświeżania wartości parametrów.

Wersja serwera z autoryzacją obsługuje autoryzację Basic HTTP, a połączenia HTTP są tunelowane przez protokół SSL (w przeglądarce zwykle oznacza się to przez podanie protokołu https). Obsługiwane są protokoły SSL wersja 2 i 3 oraz TSL (przy użyciu biblioteki OpenSSL).

Serwer testowany był z następującymi przeglądarkami:

Netscape 4.78, 4.79 (Linux),
Lynx 2.8.5 (Linux),
Links 0.96 (Linux) (niepoprawnie obsługuje dowiązania wskazujące na poziom wyżej),
Mozilla 0.9.8, 0.9.9, 1.0 (Linux),
Gnome Galleon 0.12.1 (Linux),
Konqueror 2.2.1 (Linux),
Internet Explorer 5.5 i 6.0 (Windows).

Przechowywana przez program informacja o parametrach ma postać drzewa. Dostęp do niego uzyskuje się przez specyfikowanie ścieżki dostępu podobnie jak do zasobów WWW. Dokładne informacje o postaci ścieżki (lokatora -- URI) znajdują się w następnym rozdziale. Lokator musi być zakodowany w ISO-8859-2, przy czym obsługiwane jest kodowanie za pomocą sekwencji %kod. Są one obowiązkowe np. dla spacji. Alternatywnie, w lokatorze można używać zamiast polskich liter ich angielskich odpowiedników, a zamiast spacji i ukośnika występującego w nazwie parametru znaku podkreślenia (szczegóły w następnym rozdziale).

D.1.6 Dostęp do zasobów serwera

Dostęp do informacji udostępnianych przez serwer wymaga podania, np. w oknie przeglądarki internetowej, odpowiedniego adresu zasobu. Adres ten ma postać:

protokół://adres_serwera:port/ścieżka?opcje

Protokół może przyjmować wartość http dla połączeń zwykłych lub https dla szyfrowanych (o ile ich obsługa została włączona w konfiguracji serwera).

Adres serwera specyfikuje adres internetowy komputera, na którym działa program.

Port (po dwukropku) jest numerem portu, podanym w pliku konfiguracyjnym programu. Dla połączeń szyfrowanych jest to port podany jako wartość parametru ssl_port.

Ścieżka jest to ścieżka dostępu do żądanego zasobu. Może być pusta, co oznacza dostęp do korzenia drzewa parametrów. Jeśli jest niepusta, to zawiera listę kolejnych węzłów drzewa, począwszy od korzenia, oddzielonych ukośnikami. Przykład:

http://localhost:8081/Kocioł 1/Sterownik/temperatura zadana

Ścieżka w tej postaci zostanie poprawnie zinterpretowana tylko wówczas, gdy przeglądarka potrafi odpowiednio zakodować występujące w niej polskie litery i spacje. To także jednak nie wystarczy, jeżeli w nazwie węzła znajdzie się np. ukośnik. W związku z tym polskie litery można zastąpić ich angielskimi odpowiednikami (zamiast "ą" - "a", "Ą" - "A", "ń" - "n", "ż" i "ź" - "z" itp.). Zamiast spacji i ukośnika w nazwie parametru można stosować znak podkreślenia. Tak więc podana ścieżka zapisana zgodnie z tymi zasadami może wyglądać tak:

http://localhost:8081/Kociol_1/Sterownik/temperatura_zadana

Węzły takie jak np. Kocioł 1 są rodzajem katalogów, zawierają tylko inne węzły. Natomiast węzeł temperatura zadana odpowiada parametrowi. Każdy parametr posiada atrybuty, dostęp do nich jest możliwy przez dodanie na końcu ścieżki znaku @ i nazwy atrybutu. Na przykład:

http://localhost:8081/Kociol_1/Sterownik/temperatura_zadana@value

Dostępne są następujące atrybuty:

name -- nazwa parametru,
full_name -- pełna nazwa parametru, w postaci nazw węzłów oddzielonych dwukropkami (notacja używana w systemie SZARP),
short_name -- skrócona nazwa parametru,
unit -- nazwa jednostki parametru,
ipc_ind -- indeks parametru w pamięci dzielonej,
prec -- precyzja parametru - liczby do 5 włącznie oznaczają liczbę cyfr po przecinku, powyżej są to wartości specjalne; atrybut ten jest używany wewnętrznie przez serwer do interpretowania wartości parametru odczytanej z pamięci dzielonej,
value -- wartość parametru. Napis unknown oznacza brak dostępności tej informacji (np. niedziałający serwer SZARP, brak komunikacji ze sterownikami itp.).

Po znaku zapytania można podać opcje do zapytania. Opcje mają postać nazwa=wartość i są oddzielane od siebie znakiem &. Na przykład:

http://localhost:8081/Kociol_1/Sterownik?_opcja1=wart1&_opcja2=wart2

Obecnie obługiwana jest jedna opcja o nazwie output. Określa ona, co ma pojawić się na wyjściu serwera (zostać wysłane do przeglądarki). Może ona przyjmować następujące wartości:

html -- wartość domyślna, określa że ma zostać wygenerowana strona HTML. Dla parametrów strona zawiera informacje o wartościach atrybutów oraz dowiązanie do węzła nadrzędnego. Dla pozostałych węzłów zawiera listę węzłów potomnych (jeśli są to parametry, to także ich wartości i nazwę skróconą), oraz dowiązanie do węzła nadrzędnego. Elementy listy są także dowiązaniami, po ich kliknięciu następuje przejście do odpowiedniego węzła.
xml -- serwer wysyła zawartość danego węzła wraz z węzłami potomnymi w postaci XML. Zawsze serwowany jest kompletny dokument XML. Dokument ten ma ustawioną domyślną przestrzeń nazw XML (XML namespace) na identyfikator
http://www.praterm.com.pl/ISL/params.
text -- wartość przyjmowana także dla innych, nieznanych wartości opcji. Produkuje wyjście takie jak opcja xml, ale generowany jest inny nagłówek HTTP, z typem zawartości text/plain. Pozwala to na wyświetlenie dokumentu XML w postaci czystego tekstu także w przeglądarkach nie obsługujących XML.

Jeżeli podana ścieżka zawiera nazwę atrybutu, to wartość opcji output nie może być równa html -- jeśli jest różna od xml, to jest traktowana jak text. Wysyłany jest dokument XML zawierający węzeł z wartością atrybutu parametru w kodowaniu UTF-8.

Wszystkie generowane dokumenty XML zgodne są z DTD, które można znaleźć w dodatku B.1.

D.1.7 Ustawianie wartości parametrów

Ustawianie wartości parametrów jest bardzo proste -- polega na dodaniu do ścieżki wpisywanej w przeglądarce opcji put, z wartością będącą żądaną wartością parametru. Ustawianie parametrów możliwe jest tylko przy wykorzystaniu połączenia szyfrowanego. Cała ścieżka może więc mieć postać:

https://localhost:8082/Kociol_1/Sterownik/temperatura_zadana?put=92.3

Należy zwrócić uwagę, że dla różnych typów parametrów dopuszczalne są tylko pewne wartości. Dla większości będą to wartości liczbowe. Inne możliwe zestawy wartości to:

Tak, Nie,
Pochmurno, Zmiennie, Slonecznie,
Plus, Minus.

Przy próbie ustawienia wartości parametru przeglądarka poprosi o nazwę użytkownika i hasło. Podany użytkownik musi być znany na komputerze, na którym działa serwer paramd z podanym hasłem, a poza tym użytkownik musi mieć zapisane w konfiguracji serwera dostęp do podanego parametru (zobacz D.1.3). Przy kolejnym ustawieniu wartości parametru podawanie hasła nie będzie już konieczne, chyba że od ostatniego dostępu do parametru upłynęło więcej niż 5 minut. Ma to zabezpieczyć przed sytuacją, gdy ktoś z uprawnieniami ustawi wartość parametru, po czym zostawi komputer z włączoną przeglądarką.

D.2 Instrukcja użytkownika programu `xsltd`

D.2.1 Instalacja

./configure
make

w głównym katalogu projektu ISL.

Wcześniej może być konieczne ustalenie w pliku xsltd/Makefile.in prawidłowej ścieżki do katalogu ze skompilowanymi źródłami systemu SZARP.

Po udanej kompilacji w katalogu xsltd powstaje plik xsltd, gotowy do uruchomienia. Może być uruchamiany z dowolnego katalogu. Po wydaniu komendy make install zostanie zainstalowany w odpowiednim katalogu, domyślnie /opt/szarp/bin.

Do kompilacji program wymaga kilku bibliotek, z których część nie musi być standardowo dostępna w systemie. Jedną z nich jest jest libSzarp -- biblioteka systemu SZARP firmy Praterm.

D.2.2 Konfiguracja

Konfiguracja programu jest trzymana w pliku /etc/szarp/szarp.cfg. Dokładny opis formatu tego pliku zawarto w dodatku A.1. Parametry są standardowo czytane z sekcji o nazwie xsltd. Jeśli nie zostaną w niej znalezione, to będą szukane w sekcji głównej. Są to:

port -- port TCP/IP, na którym serwer będzie przyjmować połączenia, domyślnie jest to port 8083.
log -- plik z dziennikiem programu, do którego będą wypisywane komunikaty informacyjne i o błędach. Plik ten musi być dostępny do zapisu dla użytkownika uruchamiającego program. Domyślnie jest to plik xsltd.log w aktualnym katalogu.
log_level -- poziom rejestrowanych komunikatów diagonostycznych, od 0 (tylko błędy), do 10. Domyślnie jest to poziom 2. Dokładniej, poziomy mają następujące znaczenie:
- 0 istotne błędy, powodujące przerwanie wykonywania programu lub jego istotnej części (np. brak pamięci), mogące też świadczyć o błędach w programie.
- 1 ostrzeżenia o niemożności wykonania istotnego fragmentu programu, świadczące zazwyczaj o błędach w konfiguracji.
- 2 podstawowe informacje o wykonanych działaniach, mogące służyć do oceny rodzaju i częstości wykonywania zadań (np. podstawowa informacja o zapytaniach obsłużonych przez serwer HTTP).
- 3 dodatkowe informacje statystyczne i wydajnościowe.
- 4 komunikaty o błędach o charakterze tymczasowym (np. niemożność połączenia się z serwerem).
- 5 komunikaty przydatne przy testowaniu nowej konfiguracji.
- 10 komunikaty pomocne przy szukaniu przyczyn błędów w działaniu programu -- odpluskiwanie (ang. debugging).
timeout -- czas w sekundach, po jakim w razie braku reakcji klienta połączenie TCP/IP będzie zamknięte. Dotyczy to zarówno sytuacji, gdy klient nie zdążył przesłać całego żądania HTTP, jak i zamknięcia nieaktywnego połączenia trwałego (persistent). Domyślnie jest to 30.
max_connections -- maksymalna liczba jednocześnie otwartych połączeń z klientami. Większa wartość umożliwi obsługę większej liczby stałych połączeń z klientami, ale zwiększa obciążenie systemu, na którym działa serwer. Jeżeli liczba otwartych połączeń zbliża się do podanej wartości, to serwer nie pozwala na nawiązywanie stałych połączeń. Domyślnie jest to 10.
map_file -- ścieżka do pliku zawierającego opis struktury obsługiwanego serwisu, położenie plików itp. Format tego pliku jest opisany w rozdziale A.4.

D.2.3 Uruchamianie

Program może być uruchomiony z parametrami postaci -Dvar=value. Parametry te pozwalają na ustalenie wartości zmiennych przekazywanych do parsera pliku konfiguracyjnego, mogą więc wpływać na konfigurację programu. Dokładny opis można znaleźć w dokumentacji do biblioteki libparNT, będącej częścią systemu SZARP (dodatek A.1).

Po uruchomieniu, jeżeli nie wystąpią żadne błędy, program sam usuwa się w tło, przekazując kod powrotu 0. Jeżeli wystąpił błąd, to kod powrotu jest równy 1. Informacje o błędach i ewentualne inne (zależnie od ustawionego w pliku konfiguracyjnym poziomu rejestrowania komunikatów diagnostycznych), dostępne są w dzienniku programu.

Po uruchomieniu program oczekuje na przychodzące połączenia na zadanym porcie TCP/IP i w odpowiedzi na żądania przeglądarki wysyła dokumenty o odpowiedniej zawartości.