====== Plik konfiguracyjny programu ibmanager ====== Program ibmanager działa na podstawie pliku konfiguracyjnego. Plik jest typu xml. ===== Przykładowy plik konfiguracyjny =====

Głównym elementem pliku konfiguracyjnego jest **Config**, posiadający między innymi atrybut **Version**, będący wersją pliku konfiguracyjnego. Właściwą wersją pliku konfiguracyjnego jest wersja 1.13 (dla programu ibmanager w wersji 3.7.4). Jeżeli wersja ta nie będzie się zgadzała z numerem wersji aktualnie obsługiwanym przez program, wówczas zostanie zgłoszony błąd i program zakończy działanie. Błąd zostanie zgłoszony w terminalu, ponieważ parametry logów programu są zawarte w pliku konfiguracyjnym, który nie jest wspierany. Pozostałe elementy pliku konfiguracyjnego zostały opisane w osobnych rozdziałach dokumentacji. ===== =====

Element obowiązkowy definiująca szerokość oraz długość geograficzną miejsca, gdzie system pracuje. Zarówno długość jak i szerokość geograficzna są wartościami typu double. Lokacja systemu umożliwia obliczanie np. wschodów i zachodów słońca przez logiki ibmanagera. Element zawiera atrybuty: * **Latitude** - szerokość geograficzną. * **Longitude** - długość geograficzną. ===== =====

Element opcjonalny. Stanowi dane identyfikacyjne aplikacji. Pod pojęciem aplikacji rozumiane jest odpowiednio skonfigurowany i wyposażony w logiki program ibmanager np. dla oprogramowania instalacji zarządzanej. Może to być np. * aplikacja instalacji centralnego ogrzewania * aplikacja sterowania rekuperatora * aplikacja sterowania budynkiem Element zawiera atrybuty: * **Name** - jeżeli jest zdefiniowany, wówczas wartość atrybutu zostanie wpisana do zmiennej **ibmanager.id.name** i będzie widoczna dla programów IB-System. Jest to informacja o nazwie własnej aplikacji (np. kodowa nazwa "ib-ch01-f2-2x-h4") Jeżeli element ten został zdefiniowany, wówczas każdy tekst alertu będzie zawierał nazwę aplikacji. * **Version** - jeżeli jest zdefiniowany, wówczas wartość atrybutu zostanie wpisana do zmiennej **ibmanager.id.version** i będzie widoczna dla programów IB-System. Jest to informacja o wersji aplikacji. * **Instance** - jeżeli jest zdefiniowany, wówczas wartość atrybutu zostanie wpisana do zmiennej **ibmanager.id.instance** i będzie widoczna dla programów IB-System. Jest to informacja o nazwie instancji aplikacji (np. miejsce zamontowania). Jeżeli element ten został zdefiniowany, wówczas każdy tekst alertu będzie zawierał nazwę instancji aplikacji. Teksty alertów zostały sformatowane w ten sposób, aby zawierały w sobie nazwę aplikacji (atrybut **Name**) oraz nazwę instancji aplikacji (atrybut **Instance**) w postaci: **Name-Instance: tekst alertu**. Jeżeli jeden z nich nie został podany, wówczas nagłówek alertu zostanie odpowiednio zredukowany oraz myślnik zostanie usunięty. W przypadku gdy żadna z tych wartości nie została podana, wtedy przedrostek wraz z dwukropkiem i spacją nie zostanie użyta w tekście alertu. ===== =====

Element obowiązkowy wskazuje na dostarczony plik licencji. Bez ważnego pliku licencji aplikacja nie uruchomi się. Element zawiera atrybuty: * **Path** - ścieżka gdzie znajduje się dostarczony plik licencji (license.dat) * **SignaturePublicKeyPath** ===== =====

Element zawiera pogrupowane w elemencie **Projects** ścieżki URL do plików deskryptorów projektów [[pl:ibgui:start|ibgui]]. Ścieżki te zostaną w wpisane do zmiennej **ibmanager.ibgui.project.url** i rozdzielone znakiem "|". Projekty te mogą zostać wyświetlone i pobrane ze strony wskazanej wewnątrz plików deskryptorów przez program [[pl:ibgui:start|ibgui]]. ===== =====

Element **IbProtocol** opisuje parametry protokołu, przy pomocy którego, zewnętrzne programy mogą się komunikować z programem [[pl:ibmanager:start|ibmanager]]. Element zawiera atrybuty: * **TcpPort** - adres portu TCP, na którym nasłuchuje serwer [[pl:ibprotocol:start|ibprotokołu]] * **SecureConnection** - atrybut typu bool, mówi czy serwer ibprotokołu będzie wykorzystywał bezpieczną komunikację SSL. Jeżeli tak, wówczas użyje on klucza PEM key.pem, lokalnego certyfikatu ibpakietu (local.cert.pem) oraz lokalnego certyfikatu instytucji certyfikującej (local.ca.cert.pem). Wszystkie te pliki powinny się znajdować w katalogu [[pl:ibmanager:ibmanager-config#|licencji]]. * **WanHostName** - to pomocnicza informacja przekazywana do klienta ibprotokołu poprzez zmienną **ibmanager.wan.hostname** określa na jakim publicznym serwerze, ibprotokół ibmanagera zostanie udostępniony, umożliwiając tym samym dostęp do programu przez Internet. * **WanTcpPort** - to pomocnicza informacja przekazywana do klienta ibprotokołu poprzez zmienną **ibmanager.wan.tcp.port** określa port TCP publicznego serwera **WanHostName**, na którym ibprotokół ibmanagera zostanie udostępniony. ===== =====

Element **Discovery** jest opcjonalny. Jego definicja załącza mechanizm wykrywania programów IB-System w lokalnej sieci za pomocą mechanizmu boradcast warstwy transportowej UDP. Mechanizm wykrywania **discovery** został użyty w programie **ibmanager** w charakterze serwera, w celu wykrywania przez inne programy IB-System (np. program [[pl:ibgui:start|ibgui]]). Program ibmanager posiada zaimplementowanego klienta mechanizmu **discovery** – jest w stanie wykryć inne programy IB-System – funkcjonalność ta na chwilę obecną jest wyłączona. Element zawiera atrybuty: * **QueryPort** - port UDP, na którym program nasłuchuje zapytań **discovery** (nasłuch prowadzony jest na wszystkich interfejsach sieciowych maszyny). Jeżeli atrybut ten nie został zdefiniowany, wówczas użyty zostanie port 2005. Na ten port klient **discovery** programu ibmanager będzie w przyszłości kierował zapytania **discovery** (do wszystkich interfejsów sieciowych w maszynie), w celu wykrycia innych programów IB-System. * **ResponsePort** - port UDP, na który program wysyła odpowiedzi **discovery** na skutek odebranych zapytań. Jeżeli atrybut ten nie został zdefiniowany, wówczas użyty zostanie port 2005. Odpowiedzi kierowane są jedynie do interfejsu sieciowego maszyny, z którego przyszło zapytanie. Port ten zostanie również użyty w przyszłości przez klienta **discovery** programu **ibmanager**, w celu odebrania odpowiedzi **discovery** od innych programów IB-System (nasłuch wówczas będzie prowadzony na wszystkich interfejsach sieciowych maszyny). * **TimeoutSec** - czas wyrażony w sekundach – zostanie użyty przez klienta **discovery** do oczekiwania na odpowiedzi po wysłaniu zapytania **discovery**. Jeżeli przez ten czas nie przyjdzie odpowiedź, wówczas zapytanie zostanie ponownie rozesłane. * **MaxSilenceSec** - czas wyrażony w sekundach - zostanie użyty przez klienta **discovery**. Klient na bieżąco będzie wysyłać zapytania **discovery** do wszystkich interfejsów sieciowych i będzie nasłuchiwał odpowiedzi. W ten sposób zbuduje bazę widocznych programów **IB-System**. Jeżeli przez ten czas, któryś z wykrytych wcześniej programów nie odpowie, wówczas program ibmanager stwierdzi że nie jest on już aktywna po czym ją usunie z bazy. ===== =====

Element **RemoteServers** jest odpowiedzialny za zdefiniowanie wszystkich zdalnych serwerów obsługujących ibprotocol, które są źródłem zmiennych sterujących. Mogą nimi być: * program [[pl:ibvunit:start|ibvunit]] * program [[pl:ibmanager:start|ibmanager]] Zmienne tych programów są podstawowymi elementami dla bibliotek logik – które pobierają oraz uaktualniają ich wartości. Element **RemoteServer** opisuje pojedynczą instancję zdalnego serwera i zawiera następujące obowiązkowe atrybuty: * **HostName** - nazwa DNS lub adres IP maszyny, na której jest uruchomiony zdalny serwer zmiennych (np. program ibvunit lub inny ibmanager). * **TcpPort** - numer portu TCP, na którym dany zdalny serwer zmiennych nasłuchuje. * **TimeoutSec** - timeout użyty w komunikacji z danym serwerem. Jeżeli jakakolwiek operacja sieciowa związana z danym serwerem zmiennych trwa dłużej jak wartość tego atrybutu, wówczas jest ona przerywana i logowany jest błąd. * **SleepMS** - to liczba milisekund, na którą wątek komunikujący się z danym serwerem jest usypiany, po każdej próbie komunikacji z nim. Wartość ta zawsze powinna być większa od zera, aby nie powodować nadmiernego obciążenia sieci oraz nie powodować zagłodzenia innych wątków w systemie, próbujących uzyskać dostęp do lokalnego magazynu danych. * **Prefix** - to łańcuch znakowy, który jest dodawany do nazwy każdej zmiennej, pochodzącej z danego serwera zmiennych. Wprowadzono ten parametr, aby uniknąć konfliktu nazw zmiennych np. gdy program miałby zdefiniowane więcej niż jeden zdalny serwer zmiennych. Dla przykładu niech będą to dwa programy **ibvunit**, jeżeli w każdej instancji tego serwera zmiennych atrybut **Prefix** ustawiony zostałby na pusty ciąg "", wówczas powstał by problem nazw zmiennych takich jaki **ibvunit.version**, ponieważ każdy z serwerów dostarczał by tą samą nazwę. Gdy natomiast atrybut **Prefix** poszczególnej instancji serwera zmiennych był zdefiniowany jako **"a."** i **"b."**, wówczas program **ibmanager** utworzy dwie zmienne: **a.ibvunit.version** oraz **b.ibvunit.version** i tym samym problem konfliktu nazw nie powstanie. Podano trywialny przykład zmiennej, której konflikt w typowych aplikacjach nie będzie istotny, jednak problem jest istotny w przypadku złożonych aplikacji z wieloma bramkami i gdy nastąpi konflikt nazw zmiennych procesowych (np. **rs.0.id.1.output.do.0**). Atrybut **Prefix** powinien być unikatowy aby nie nastąpił konflikt nazw. Jeżeli obsługiwany jest jedynie jeden serwer zmiennych, wówczas atrybut **Prefix** może zawierać pusty łańcuch. * **SecureConnection** - atrybut boolowski, który wskazuje, czy zdalny serwer będzie wykorzystywał bezpieczną komunikację SSL. Jeżeli tak, wówczas użyje on klucza PEM key.pem, lokalnego certyfikatu ibpakietu (local.cert.pem) oraz lokalnego certyfikatu instytucji certyfikującej (local.ca.cert.pem). Wszystkie te pliki powinny się znajdować w katalogu [[pl:ibmanager:ibmanager-config#|licencji]]. Obsługa każdego zdalnego serwera rozpoczyna się od wydania komendy **describe_all**. Ma to na celu utworzenie zmiennych o odpowiednich typach, następnie wysyłane są komendy **get_all** przeplatane z komendami **set** – o ile nastąpiła modyfikacja wartości zmiennej należącej do danego serwera (np. przez logikę sterującą, program nadrzędny lub bezpośrednio przez użytkownika przez interfejs komunikacyjny). ===== =====

Element **LogicLibDir** jest opcjonalny. Jeżeli sekcja ta nie została zdefiniowana, wówczas program **ibmanager** nie będzie obsługiwał logik sterujących a jedynie będzie pełniła funkcję repeatera serwerów zmiennych (praca w trybie proxy). Element zawiera atrybuty: * **Path** - definiuje ścieżkę do katalogu zawierającego pliki konfiguracyjne logik oraz biblioteki dynamiczne logik. Jeżeli element **LogicLibDir** został zdefiniowany, wówczas program **ibmanager** podczas startu rozpocznie wczytywanie plików konfiguracyjnych logik typu xml umieszczonych w katalogu zdefiniowanym w atrybucie **Path**, po czym rozpocznie ładowanie logik z bibliotek dynamicznych (.dll/.so). ===== =====

Element **Storage** jest obowiązkowy i jest odpowiedzialny za konfigurację mechanizmu lokalnego magazynu danych. Element zawiera atrybuty: * **DirPath** - (obowiązkowy) określa ścieżkę do katalogu, w którym program **ibmanager** będzie przechowywał dane. Jeżeli katalog ten nie istnieje, to zostanie on utworzony. Jeżeli tworzenie się nie powiedzie, wówczas zalogowany zostanie błąd i program zakończy działanie. * **DumpPeriodHours** - (opcjonalny) jest to okres czasu wyrażony w godzinach. Jeżeli jest zdefiniowany, musi być większy od 0. Atrybut ten definiuje, co ile godzin program **ibmanager** ma dokonać zrzutu lokalnego magazynu danych do pliku archiwalnego. Nazwa pliku archiwalnego tworzona jest na podstawie bieżącego czasu a same pliki archiwalne tworzone są w podkatalogu **archive** katalogu wskazanego przez atrybut **DirPath**. Jeżeli ten atrybut nie jest zdefiniowany, wówczas okresowy zrzut danych archiwalnych nie jest realizowany. * **MaxDumps** - (opcjonalny) określa maksymalną liczbę archiwalnych plików zmiennych. Jeżeli jest zdefiniowany wówczas musi być większy od 0. Przy każdorazowym zrzucie zmiennych (okresowego lub na żądanie, poprzez ustawienie zmiennej **ibmanager.dump.vars**) archiwa są liczone i jeżeli ich liczba przekroczy tą wartość, wówczas nadmiar jest usuwany od najstarszego. Gdy atrybut ten nie jest zdefiniowany, wówczas maksymalna liczba zrzutów nie jest sprawdzana. ===== =====

Element **Alerts** jest opcjonalny. Jeżeli został zdefiniowany wówczas program **ibmanager** wczytuje plik konfiguracyjny alertów z lokalizacji zdefiniowanej w atrybucie **Path** tego elementu. Jakiekolwiek niepowodzenie przy jego wczytywaniu zakończy pracę programu wraz z odpowiednim wpisem w logach. Jeżeli ten element nie została zdefiniowany, wówczas mechanizm alertów zostanie wyłączony a zgłaszanie żądania wysłania alertu przez działające logiki będą ignorowane. ===== =====

Element **TrackedVariable** jest nie istotny dla użytkownika, jedynie dla programisty w celu wykrycia błędów w oprogramowaniu. Został on wprowadzony ze względu na złożoność obsługi zdalnych zmiennych. Jest to element opcjonalny i jego definicja powoduje odpowiednie wpisy w logach, które nie niosą żadnych informacji dla użytkownika. ===== =====

Element odpowiedzialny za konfigurację systemu logowania programu **ibmanager**. Element zawiera atrybuty: * **Type** - oznacza określenie ujścia dla logów i może przyjmować wartości: * **Console** – logi wyświetlane jedynie na konsoli * **File** - logi zapisywane do pliku * **None** - wyłączenie logowania * **Level** - oznacza poziom logowania i może przyjmować wartości: * **TraceLo** - najwięcej szczegółów * **Trace** * **TraceHi** * **DebugLo** * **Debug** * **DebugHi** * **Info** * **Notice** * **Warning** * **Error** * **Critical** – najmniej szczegółów * **Params** - określa plik gdzie znajduje się plik logów a jeżeli go nie ma to gdzie ma zostać utworzony. Ścieżka powinna mieć składnię odpowiednią dla danego systemu operacyjnego. * **MaxLogFileSize** - (opcjonalny) posiada wartość domyślną równą 10*1024*1024 i określa maksymalny rozmiar pojedynczego pliku logów. Ze względów wydajnościowych i po części praktycznych, rozmiar pojedynczego pliku jest większy od tej wartości z dokładnością do rozmiaru zalogowanej linii (tak aby zakończyć logowanie pełnej linii) oraz do 5 sekund. * **MaxLogArchives** - (opcjonalny) posiada wartość domyślną równą 10 co oznacza że że oprócz bieżącego pliku logów, może się znaleźć do 10 archiwalnych plików. Pliki archiwalne tworzone są przez dodanie do nazwy pliku logu sufiksu .N gdzie N jest indeksem numerowanym od 0. 0 oznacza najnowsze archiwum, im wyższy numer tym starsze. Najstarsze pliki archiwalne są usuwane, jeżeli ich liczba przekroczy wartość tego atrybutu. W przykładowej definicji elementu , mechanizm rotacji logów zakłada istnienie do 20 plików archiwalnych. Zarówno archiwalne jak i bieżące będą mogły mieć rozmiar do ok. 40MB. ===== =====

Element opcjonalny. Jeżeli został zdefiniowany wówczas aplikacja załączy mechanizm autoryzacji po stronie interfejsu ibprotokołu. Element zawiera atrybuty: * **Path** - wskazuje na plik konfiguracyjny mechanizmu autoryzacji