Plik konfiguracyjny programu ibmanager

Program ibmanager działa na podstawie pliku konfiguracyjnego. Plik jest typu xml.

ibmanager.xml

<?xml version="1.0" encoding="UTF-8"?>
<Config xmlns="http://www.insbud.net/ibmanager" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Version="1.13" xsi:schemaLocation="http://www.insbud.net/ibmanager ibmanager.xsd">
 
   <!-- location coordinates -->
   <Location Latitude="52.069167" Longitude="19.480556" />
 
   <!-- installation identifications - optional elements -->
   <Application Name="Installation Name" Version="Version Number" Instance="Instance Name" />
 
   <License Path="/ibsystem/license/license.dat" SignaturePublicKeyPath="" />
 
    <IbGUI>
      <Projects>
        <Project Url="http://update.ibsystem.org/projects/installation-name-installation-version.xml"/>
      </Projects>
    </IbGUI>
 
   <IbProtocol TcpPort="3001" SecureConnection="false" WanHostName="s1a.ibsystem.org" WanTcpPort="520" />
 
   <Discovery QueryPort="2005" ResponsePort="2005" TimeoutSec="3" MaxSilenceSec="20" />
 
   <RemoteServers>
      <RemoteServer HostName="127.0.0.1" TcpPort="2001" TimeoutSec="20" SleepMS="100" Prefix="" SecureConnection="false" />
   </RemoteServers>
 
   <LogicLibDir Path="/ibsystem/ibmanager/logic" />
 
   <Storage DirPath="/ibsystem/ibmanager/storage" DumpPeriodHours="24" MaxDumps="10" />
 
   <Alerts Path="/ibsystem/ibmanager/alerts.xml" />
 
   <TrackedVariable Name="rs.0.id.255.input.t.0.value" />
 
   <!-- Levels: TraceLo, Trace, TraceHi, DebugLo, Debug, DebugHi, Info, Notice, Warning, Error, Critical -->
   <!-- Types: Console, File, None -->
   <Log Type="File" Level="Info" Params="/ibsystem/ibmanager/ibmanager.log" MaxLogFileSize="40000000" MaxLogArchives="20" />
 
   <Credentials Path="/ibsystem/ibmanager/credentials.xml" />
</Config>

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.

<Location Latitude="52.069167" Longitude="19.480556" />

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ą.

<Application Name="Installation Name" Version="Version Number" Instance="Instance Name" />

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.

<License Path="/ibsystem/license/license.dat" SignaturePublicKeyPath="" />

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

<IbGUI>
  <Projects>
    <Project Url="http://update.ibsystem.org/projects/installation-name-installation-version.xml"/>
  </Projects>
</IbGUI>

Element zawiera pogrupowane w elemencie Projects ścieżki URL do plików deskryptorów projektów 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 ibgui.

<IbProtocol TcpPort="3001" SecureConnection="false" WanHostName="s1a.ibsystem.org" WanTcpPort="520" />

Element IbProtocol opisuje parametry protokołu, przy pomocy którego, zewnętrzne programy mogą się komunikować z programem ibmanager.

Element zawiera atrybuty:

• TcpPort - adres portu TCP, na którym nasłuchuje serwer 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 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.

<Discovery QueryPort="2005" ResponsePort="2005" TimeoutSec="3" MaxSilenceSec="20" />

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 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.

<RemoteServers>
   <RemoteServer HostName="127.0.0.1" TcpPort="2001" TimeoutSec="20" SleepMS="100" Prefix="" SecureConnection="false" />
</RemoteServers>

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 ibvunit
• program 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 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).

<LogicLibDir Path="/ibsystem/ibmanager/logic" />

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).

<Storage DirPath="/ibsystem/ibmanager/storage" DumpPeriodHours="24" MaxDumps="10" />

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.

<Alerts Path="/ibsystem/ibmanager/alerts.xml" />

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.

<TrackedVariable Name="rs.0.id.255.input.t.0.value" />

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.

<Log Type="File" Level="Info" Params="/ibsystem/ibmanager/ibmanager.log" MaxLogFileSize="40000000" MaxLogArchives="20" />

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 <Log>, 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.

<Credentials Path="/ibsystem/ibmanager/credentials.xml" />

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