****************************************************************************
*                            UPS Monitor 3.1                               *
*                         wersja dla systemu Linux                         *
****************************************************************************
*                                                                          *
*          Program monitorujący zasilacze UPS firmy Fideltronik            *
*                                                                          *
*            autorzy: Paweł Abramczuk                                      *
*                     Leszek Tokarski upssupport@fideltronik.com           *
*                                                                          *
****************************************************************************

Kopiowanie i rozpowszechnianie tego oprogramowania jest dozwolone a wręcz
wskazane. Oprogramowanie jest dostępne darmowo na stronie firmy Fideltronik

                  http://www.fideltronik.com.pl

1. Wstęp
  UPS Monitor jest to oprogramowanie monitorujące stan zasilaczy UPS firmy
Fideltronik podłączonych do portu szeregowego komputera. Pracuje ono w oparciu
o architekturę klient-serwer w sieci komputerowej.
  W skład oprogramowania UPS Monitor wchodzą 2 główne programy. Pierwszy
z nich to serwer upsmons (program komunikujący się bezpośrednio z zasilaczem),
a drugi to upsmonc (klient) odpowiedzialny za prezentację stanu zasilacza.
  UPS Monitor Serwer odpowiada za komunikację z UPSem i przekazuje dane między
nim, a programem UPS Monitor Klient. Może on także informować poprzez sieć
inne stacje robocze i serwery pracujące np w Windows o swoim stanie. Program
może automatycznie rozpoznawać rodzaj protokołu komunikacyjnego podłączonego
zasilacza.
  Na stacjach roboczych musi pracować UPS Monitor Klient, który odbiera
komunikaty z UPS Monitor Serwer, informuje o stanie zasilacza UPS (lub kilku
zasilaczy) i w razie potrzeby zamyka bezpiecznie system. Jest możliwe
połączenie każdego klienta zainstalowanego w sieci zasilanej przez zasilacze
UPS z kilkoma serwerami odbierającymi dane z kilku UPSów. Konfiguracji
połączen dokonuje się w pliku konfiguracyjnym ups.cfg. Jest dostępnych kilka
możliwości powiadamiania: komunikaty systemowe wysyłane za pośrednictwem wall,
wysłanie emaila lub SMSa, uruchomienie dowolnego programu i zapis do loga.
Program klienta tworzy również stronę www, w której jest uwidoczniony stan
wszystkich zasilaczy.
  Oba programy powinny być uruchamiane automatycznie w czasie startu systemu.
Odbywa się to przy pomocy standardowego mechanizmu stosowanego np. dystrybucji
Red Hat, tzn linków do skryptów startowych umieszczonych w katalogach
/etc/rc.d/rc?.d

2. Plik opcji.
  W katalogu /etc/ups/fideltronik/ jest umieszczony plik options.cfg. Zawiera
on podstawowe parametry dotyczące wszystkich komponentów.
  Parametry opisujące ścieżki do poszczególnych plików mogą być wykorzystywane
w wersji instalowanej przez skrypt również przed instalacją. Pakiet RPM
korzysta natomiast ze ścieżek domyślnych. Niektóre z parametrów mogą być
zmieniane po zainstalowaniu. Zastosowanie zmian wymaga restartu programu.
Poniżej zostaną omówione te parametry, które prawdopodobnie będą mogły być
modyfikowane po instalacji.

PATH_LOG=/var/log/fideltronik/       ścieżka dla logów
PATH_WWW=/var/www/html/fideltronik/  ścieżka dla plikow html
Obie te ścieżki można zmienić, jeśli użytkownik woli, aby odpowiednie pliki
powstawały pod innymi lokalizacjami.

SERVER_PORT_IP=8881                  numer portu IP serwera
CLIENT_PORT_IP=8882                  numer portu IP klienta
Normalnie nie ma potrzeby zmieniania tych wartości. Wyjątkiem są sytuacje, gdy
inne programy korzystają już z tych portów. Jeśli UPS Monitor ma pracować w
sieci, konieczne jest ustawienie tych samych wartości na każdym komputerze.

SERIAL_PORT=/dev/ttyS0               plik urządzenia portu RS232
Parametr ten należy zmienić, jeśli UPS jest podłączony do innego portu RS232.

UPS_NAME="UPS server"                nazwa lokalizacji UPSa
Nazwa ta pojawia się w komunikatach i na stronach www. Aby móc rozróżnić
zasilacze monitorowane w sieci, należy im przypisać różne nazwy.

SHUTDOWN_TIME=60                     czas od rozpoczęcia zamykania systemu...
Czas ten dotyczy UPSów z interfejsem szeregowym. Określa on czas od początku
zamykania systemu do wyłączenia UPSa. W przypadku dużych systemów lub wolnych
komputerów może się okazać, że system nie zdąży się zamknąć. Należy wtedy
wydłużyć ten czas.

PROTOCOL=all                         domyślny protokół
Domyślnie program próbuje się połączyć z UPSem kolejno przez wszystkie
obsługiwane protokoły transmisji. Jeśli protokół jest znany, można skrócić
czas nawiązywania połączenia przez podanie tu jego nazwy. Dostępne możliwosci:
JOINT (UPSy z interfejsem stykowym), SEC26 (Aresy z komunikacją szeregową),
MEGATEC (Saturny), NEWAVE (Oriony)

REFRESH_WWW=10                       częstość odświeżania stron www [s]
W zależności od lokalizacji, z której mają być oglądane pliki html, czas ten
można wydłużyć, aby strona nie znikała zbyt często.

3. Plik konfiguracyjny klienta.
  Plik konfiguracyjny ups.cfg jest plikiem tekstowym zawierającym konfigurację
programu upsmonc opisującą akcje podejmowane po zajściu określonych zdarzeń
w UPSach. Informacje z tego pliku są pobierane w czasie uruchomienia programu
klienta. Zapisane w nim są konfiguracje wszystkich zasilaczy. Każdy
parametr zapisywany jest w postaci etykiety (klucza) na początku linii oraz
paramertu (parametrów). Linia posiadająca w pierwszej kolumnie znak # jest
traktowana jako komentarz (nie jest analizowana). Nazwy parametrów nie mogą być
w żaden sposób zmieniane.
  Można wyróżnić 3 typy parametrów:
- liczba
- linia tektowa (napis bez spacji)
- tekst (kilka linii tekstu) dowolny napis zapisany w jednej lub wielu liniach
  Przykłady użycia i dalsze komentarze można znaleźć w samym pliku ups.cfg.

3.1. Podział na sekcje opisujące poszczególne zasilacze.
  Opis każdego zasilacza zaczyna się od lini:
[UPS_NR]        numer_ups-a
numer_ups-a jest liczbą z przedziału 1-25. Wszystkie kolejne parametry bedą
dotyczyć zasilacza o numerze numer_ups-a. Kolejna linia zawierająca [UPS_NR]
kończy opis bieżącego zasilacza i równocześnie rozpoczyna konfigurację
kolejnego. Jest to pole obowiązkowe.
  Minimalny opis konfiguracji zasilacza jest pokazany poniżej. Zawiera on tylko
numer zasilacza na liście, oraz jego adres IP.
[UPS_NR]       1
[UPS_ADD_IP]   192.168.1.21
  W konfiguracji znajdują się też pola opisujące zdarzenia i podejmowane akcje
wraz z konfiguracją poczty, powiadamiania użytkowników, a także terminarz UPSa
lokalnego.

3.2. Parametry domyślne.
  W zależności od miejsca umieszczenia danego parametru może on być traktowany
w różny sposób. Parametry umieszczone przed pierwszym wystąpieniem [UPS_NR] są
parametrami domyślnymi dla wszystkich UPSów. Jeśli natomiast występują one tuż
po [UPS_NR] a przed konfiguracją pierwszego zdarzenia, są one domyślne dla
wszystkich zdarzeń dotyczących tego UPSa.
  Jeśli w opisie akcji dla danego zdarzenia nie występuje określony parametr
zamiast niego jest pobierany parametr domyślny dla danego UPSa. Jeśli również
on nie występuje, jest brany parametr domyślny dla wszystkich UPSów.

3.3. Zdarzenia i akcje .
  Konfiguracja powiadamiania polega na przypisaniu pewnych akcji do zdarzeń.
Zdarzenia to:
- awaria zasilania (praca na bateriach)     [EVENT_BAT]
- planowe zamknięcie systemu                [EVENT_SYS_CLOSE]
- rozpoczęcie pracy programu                [EVENT_PRG_START]
- zakończenie pracy programu                [EVENT_PRG_STOP]
- utrata komunikacji                        [EVENT_NO_COMMUNICATION]
- praca AVR                                 [EVENT_AVR_START]
- koniec pracy AVR                          [EVENT_AVR_STOP]
- wyczerpane baterie na pracy bateryjnej    [EVENT_BAT_LOW]
- praca bypass                              [EVENT_BYPASS]
- praca normalna                            [EVENT_NORMAL]
- brak komunikacji na pracy bateryjnej      [EVENT_NO_COMM_BAT]
- zasilacz w stanie "wyłączanie"            [EVENT_UPS_GOING_OFF]
  Typ zdarzenia umieszczony jest na początku linii jako klucz, po nim
następuje opis (lub opisy) akcji.
  Akcje są podejmowane po zajściu zdarzenia. Jeżeli po kluczu opisującym
zdarzenie umieścimy nazwę podejmowanej akcji (i ewentualną konfigurację akcji)
zostanie ona wykonana. Do jednego zdarzenia może być podpiętych (aktywnych)
kilka akcji. Opisy akcji oddziela się przecinkiem.
  Typy akcji i ich opis:
- zapis do dziennika                  WriteToLog
- ostrzeżenie                         Warning
- uruchomienie programu               Run
- wysłanie email                      SendMail
- zamknięcie systemu operacyjnego     CloseSystem

3.3.1. Akcja wysłanie emaila.
  Konfigurując tę akcję należy pamiętać że serwer pocztowy, przez który będzie
wysyłany email, musi umożliwiać wysłanie wiadomości bez autoryzacji. Akcja
wysłania wiadomości email wymaga następujących pól:
  [SEND_MAIL_DELAY] - po kluczu należy podać czas (w sekundach) po jakim nastąpi
wysłanie wiadomości, jeśli dany stan UPSa się utrzyma.
  [SEND_MAIL_TO] - pole opisujące adres odbiorcy. Należy podać adres email bez
spacji, komentarzy. Można podać tylko jeden adres odbiorcy.
  [SEND_MAIL_SMTP] - adres serwera pocztowego, przez który wiadomość będzie
wysyłana
  [SEND_MAIL_FROM] - nadawca wiadomości (bez spacji)
  [SEND_MAIL_SUBJECT] - temat wiadomości. Opis może zawierać spacje i musi
być umieszczony w jednej linii.
  [SEND_MAIL_MESSAGE] - treść wiadomości. Wiadomość może być umieszczona w kilku
liniach. Między kluczami początku [SEND_MAIL_MESSAGE] i końca wiadomości
[SEND_MAIL_MESSAGE_END] należy umieścić pełną treść.

3.3.2. Akcja rozesłania ostrzeżenia.
  Ostrzeżenie jest rozsyłane do wszystkich zalogowanych użytkowników z
wykorzystaniem polecenia wall. Konfiguracja tej akcji wymaga parametrów:
  [WARNING_TEXT] - informacja rozsyłana do użytkowników. Opis musi znajdować
się w jednej linii.
  [WARNING_FIRST_DELAY] - opóźnienie wysłania pierwszego ostrzeżenia, jeśli
stan UPSa się nie zmieni
  [WARNING_NEXT] - jeżeli 1 rozpoczyna się  proces ciągłego informowania
użytkowników co czas [WARNING_NEXT_DELAY]; jeśli podamy po kluczu liczbę 0,
dalsze informacje nie będą rozsyłane.
  [WARNING_NEXT_DELAY] - czas między rozsyłaniem informacji jeżeli
[WARNING_NEXT] wynosi 1.
Wszystkie czasy podawane są sekundach.

3.3.3. Akcja uruchomienia programu.
  Do każdego zdarzenia możemy dopisać akcję uruchomienia zewnętrznego programu.
Konfiguracja tej akcji wymaga jedynie dwóch parametrów:
  [RUN_PRG] - ścieżka do programu
  [RUN_DELAY] - czas opóźnienia do uruchomienia programu po zajściu zdarzenia.
Jeśli przed tym czasem nastąpi inne zdarzenie, program nie będzie uruchomiony.

3.3.4. Akcja zamknięcia systemu.
  Akcja ta jest konfigurowana typowo dla zdarzenia "Baterie wyczerpane". Akcję
zamknięcia systemu można jednak dopisać do każdego zdarzenia (z wyjątkiem
wyłączenia zaplanowanego w terminarzu - w przypadku zasilacza z interfejsem
stykowym). Wymaga ona ustawienia klucza CloseSystem.
  [CLOSE_SYSTEM_RUNUPS] - gdy 1 zasilacz zostanie automatycznie uruchomiony po
powrocie zasilania (dla zasilacza z interfejsem stykowym wartość ignorowana).
  [CLOSE_SYSTEM_TURNOFFUPS] - gdy 1 zasilacz zostanie wyłączony po zamknięciu
systemu. Proces wyłączenia zasilacza z komunikacją szeregową odbywa się w ten
sposób, że po odliczeniu czasu [CLOSE_SYSTEM_DELAY] program upsmonc wysyła do
zasilacza odpowiednie rozkazy wyłączenia z opóźnieniem, a po potwierdzeniu
zostaje wywołany skrypt shutdown.sh, który powoduje rozpoczęcie procesu
zamykania systemu. Wyłączenie zasilacza z interfejsem stykowym odbywa się na
innej zasadzie. Najpierw jest zapisywana informacja do pliku upsoff.conf, że
UPS ma być wyłączony, a przed samym zamknięciem systemu jest wywoływany program
upsoff, który sprawdza ten plik po czym wystawia sygnał wyłączający. Wywołanie
tego programu powinno zostać umieszczone ręcznie przez użytkownika w skrypcie
/etc/rc.d/init.d/halt tuż przed ostatnią instrukcją.
  [CLOSE_SYSTEM_MODE] - tryb zamknięcia zasilacza (obecnie zawsze 1).
  [CLOSE_SYSTEM_DELAY] - opóźnienie w sekundach do wywołania skryptu
zamykającego. Przed tym czasem, jeśli nastąpi zdarzenie kończące stan, w wyniku
którego system miał być zamknięty, nie dojdzie do zamknięcia. Należy pamiętać,
że pominięcie podania wartości czasu opóźnienia do zamknięcia systemu
[CLOSE_SYSTEM_DELAY], bedzie potraktowane przez program jako brak podejmowania
tej akcji (np. dla zdarzenia praca bateryjna, zasilacz bedzie pracował aż do
wyczerpania baterii). Jeśli podamy wartość np. 120, system zostanie
zamknięty po 2 minutach pracy na bateriach.

3.4. Terminarz.
  Terminarz dotyczy tylko zasilacza lokalnego. Poprzez zasilacz lokalny rozumie
się zasilacz z adresem IP localhost (127.0.0.1 lub własnym adresem IP)
i podłączonym zasilaczem. Terminarz dopuszcza 2 typy zadań:
- wyłączenie zasilacza
- wyłączenie zasilacza i włączenie go po zadanym czasie
które są realizowane na 3 sposoby:
- zadania realizowane jeden raz
- zadania realizowane codziennie
- zadania realizowane co tydzień
Można zdefiniować do 25 zadań. Każde zadanie umieszczone jest w osobnej linii
i musi zawierać wszystkie parametry opisujące dany typ zadania czyli datę, czas,
typ zadania. Po typie zadania może znajdować się dodatkowy parametr opóźnienie
(tylko dla zadania wyłącz i włącz ups-a. Poniższe przykłady opisują konfigurację
zadań.
  [TASK_UPS_OFF]     2002.10.31,17:25,DAILY
Zadanie typu "wyłącz ups" codziennie od dnia 2002.10.31 o godzinie 17:25.
  [TASK_UPS_RESTART] 2002.10.27,17:28,ONCE,02:30
Zadanie realizowane jednokrotnie w dniu 2002.10.27 o godzinie 17:28 polegające
na wyłączeniu zasilacza i włączeniu go po czasie 2 godzin 30 minut.
  [TASK_UPS_RESTART] 2002.10.01,17:01,WEEKLY,00:02
Zadanie realizowane co tydzień od dnia 2002.10.10 o godzinie 17:01 polegające
na wyłączeniu zasilacza i włączeniu go po czasie 2 minut.
  Zasilacz z interfejsem stykowym nie rozróżnia zadań wyłączenia i restartu.
O tym, czy nastąpi włączenie wyjścia na pracy sieciowej, decyduje ustawienie
przełącznika z tyłu obudowy (nie dotyczy niektórych tańszych modeli).

4. Modyfikacje po instalacji.

4.1. Informowanie w środowisku graficznym.
  Program umożliwia wysyłanie komunikatów również do użytkownika pracującego w
środowisku graficznym, przy wyłączonym przechwytywaniu komunikatów od konsoli,
na której pracuje UPS Monitor. 
  W dystrybucji Red Hat i pochodnych podczas instalacji jest kopiowany do 
katalogu /etc/X11/xinit/xinit.d skrypt xhostfid, ktory umożliwia dostęp do
Xserwera dla komunikatów generowanych lokalnie. Dzięki temu możliwe jest 
przekazywanie komunikatów o pracy UPSa.
  W przypadku, gdy ten sposób nie działa, w skrypcie /etc/X11/xinit/xinitrc 
trzeba umieścić polecenie "xhost + local:", jednak ten sposob nie działa przy
logowaniu graficznym. Jeśli chcemy umożliwić ich pojawianie się w przypadku 
dostępu przez sieć lub przy kilku X serwerach, konieczna będzie również zmiana
wspomnianego skryptu oraz /usr/sbin/xmess.

4.2. Wyłączanie UPSów z interfejsem stykowym.
  Ponieważ UPSy z interfejsem stykowym są zamykane natychmiast po podaniu
sygnału wyłączającego (nowsze modele z 30s opóźnieniem), nie mogą być one
wyłączane w ten sam sposób, co UPSy z interfejsem szeregowym (możliwość podania
opóźnienia do wyłączenia). Do tego celu jest wykorzystywany program upsoff z
pakietu UPS Monitora, który powinien być wywołany tuż przed całkowitym
zamknięciem systemu, już po odmontowaniu systemów plików (np. przed komendą
"exec $command $HALTARGS").

UWAGA: W przypadku używania urządzeń dyskowych typu RAID i UPSów z interfejsem
       stykowym bez opóźnienia (wyprodukowanych do ok. połowy 2004) wyłączanie
	   UPSów przez komputer może grozić utratą danych na dysku!

5. Monitoring graficzny.
  Oprogramowanie UPS Monitor prezentuje stan zasilacza (lub zasilaczy)
w sposób graficzny w oknie przegladarki http. Na etapie instalacji jest
tworzony katalog, domyślnie /var/www/html/fideltronik/, w którym będą
umieszczane poszczególne pliki html. Jeśli zostanie on udostępniony do odczytu
na zewnątrz sieci, będzie możliwy podgląd działania UPSów z dowolnego miejsca.
Po uruchomieniu upsmons i upsmonc w katalogu tym powstanie plik index.html.
Zawiera on listę podanych zasilaczy (wyszczególnionych w pliku ups.cfg) wraz
z linkami do plików html z opisem ich stanu.
  W czasie pracy do każdego UPSa są przydzielone pliki z informacją o jego
stanie np. ups7.html i ups7txt.html (jest to odpowiednik poprzedniego pliku
pozbawiony elementów graficznych), a także plik log np. ups7log.html.
  W celu umożliwienia ciągłego śledzenia stanu zasilaczy okno przeglądarki
odświeża się cyklicznie (domyślnie co 10 sekund). Wybór zasilacza następuje
przez kliknięcie na link po lewej stronie okna przeglądarki.

ZAŁĄCZNIK

Błędy oraz uwagi dotyczące tego oprogramowania proszę przesyłać
na adres: upssupport@fideltronik.com. Postaram się pomóc w miarę
moich możliwosci.

Pozdrawiamy wszystkich miłośników systemów UNIX-owych.

Leszek Tokarski i Pawel Abramczuk
Fideltronik


NOTA

AUTOR OPROGRAMOWANIA ORAZ FIRMA FIDELTRONIK NIE PONOSZĄ ŻADNEJ
ODPOWIEDZIALNOŚCI ZA JAKIEKOLWIEK SZKODY WYNIKŁE ZE STOSOWANIA TEGO
OPROGRAMOWANIA.
