====== Configuration file of the ibmanager program ======

The ibmanager program operates based on a configuration file. The file is an xml type file.

===== Sample configuration file =====

<code 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>
</code>

The main element of the configuration file is **Config**, which includes, among others, the **Version** attribute, which is the version of the configuration file. The proper version of the configuration file is version 1.13 (for ibmanager program version 3.7.4).

If this version does not match the version number currently supported by the program, then an error will be reported and the program will terminate. The error will be reported in the terminal, as the log parameters of the program are included in the configuration file, which is not supported.

The remaining elements of the configuration file are described in separate chapters of the documentation.

===== <Location>=====

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

Mandatory element defining the latitude and longitude of the place where the system operates. Both longitude and latitude are double type values.

The system's location allows for calculating, for example, sunrise and sunset times by ibmanager's logics.

The element contains the attributes:

  * **Latitude** - geographic latitude.
  * **Longitude** - geographic longitude.

===== <Application> =====

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

Optional element. It represents the identifying data of the application. By application, we mean the appropriately configured ibmanager program equipped with logics, e.g., for software of managed installations. It could be, for instance:

  * central heating installation application
  * heat recovery controller application
  * building control application

The element contains the attributes:

  * **Name** - if defined, the attribute value will be written to the **ibmanager.id.name variable** and will be visible to IB-System programs. It is information about the name of your own application (e.g., code name "ib-ch01-f2-2x-h4"). If this element has been defined, then each alert text will contain the application name
  * **Version** - if defined, the attribute value will be written to the **ibmanager.id.version variable** and will be visible to IB-System programs. It is information about the application version.
  * **Instance** - if defined, the attribute value will be written to the **ibmanager.id.instance variable** and will be visible to IB-System programs. It is information about the application instance name (e.g., place of installation). If this element has been defined, then each alert text will contain the application instance name.

Alert texts have been formatted in such a way to include the application name (the **Name** attribute) and the application instance name (the **Instance** attribute) in the form: **Name-Instance: alert text**. If one of them is not provided, then the alert header will be accordingly reduced and the dash will be removed. In the case when neither of these values is provided, then the prefix along with the colon and space will not be used in the alert text.

===== <License> =====

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

Mandatory element pointing to the provided license file. Without a valid license file, the program will not start.

The element contains the attributes:

  * **Path** - path where the provided license file (license.dat) is located.
  * **SignaturePublicKeyPath**

===== <IbGUI> =====

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

The element contains URLs to project descriptor files grouped in the **Projects** element for [[en:ibgui:start|ibgui]].

These paths will be passed to **ibmanager.ibgui.project.url** variable and separated by the "|" character.

These projects can be displayed and downloaded from the page indicated inside the descriptor files by the [[pl:ibgui:start|ibgui]] software.

===== <IbProtocol> =====

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

The **IbProtocol** element describes the parameters of the protocol, with which, external programs can communicate with the [[en:ibmanager:start|ibmanager]] software.

The element contains attributes:

  * **TcpPort** - TCP port address on which the [[en:ibprotocol:start|ibprotocol]] server listens
  * **SecureConnection** - a bool type attribute, it says whether the ibprotocol server will use secure SSL communication. If so, it will use the PEM key.pem, local ibpackage certificate (local.cert.pem) and local certifying institution certificate (local.ca.cert.pem). All these files should be located in the [[en:ibmanager:ibmanager-config#<License>|license]] directory.
  * **WanHostName** -  this is auxiliary information passed to the ibprotocol client through the **ibmanager.wan.hostname** variable specifies on which public server, ibmanager's ibprotocol will be made available, thus enabling access to the application via the Internet.
  * **WanTcpPort** - this is auxiliary information passed to the ibprotocol client through the **ibmanager.wan.tcp.port variable** specifies the TCP port of the public WanHostName server, on which ibmanager's ibprotocol will be made available.

===== <Discovery> =====

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

The **Discovery** element is optional. Its definition includes the mechanism for detecting IB-System programs in the local network using the UDP transport layer broadcast mechanism.

The **discovery** detection mechanism was used in the **ibmanager** program as a server, in order to be detected by other IB-System programs (e.g., the [[en:ibgui:start|ibgui]] program).

The ibmanager program has an implemented **discovery** mechanism client - it is able to detect other IB-System programs - this functionality is currently disabled.

The element contains attributes:

  * **QueryPort** - UDP port, on which the program listens to **discovery** queries (listening is carried out on all network interfaces of the machine). If this attribute has not been defined, then port 2005 will be used. The **discovery** client of the ibmanager program will in the future direct **discovery** queries to this port (to all network interfaces in the machine), in order to detect other IB-System programs.
  * **ResponsePort** - UDP port, on which the program sends **discovery** responses as a result of received queries. If this attribute has not been defined, then port 2005 will be used. Responses are directed only to the network interface of the machine from which the query came. This port will also be used in the future by the **discovery** client of the** ibmanager** program, in order to receive **discovery** responses from other IB-System programs (listening will then be conducted on all network interfaces of the machine).
  * **TimeoutSec** - a time expressed in seconds - will be used by the **discovery** client to wait for responses after sending a **discovery** query. If no response comes during this time, then the query will be resent.
  * **MaxSilenceSec** - a time expressed in seconds - will be used by the **discovery** client. The client will continuously send **discovery** queries to all network interfaces and listen for responses. This way, it will build a database of visible IB-System programs. If, during this time, one of the previously detected programs does not respond, then the ibmanager program will determine that it is no longer active, after which it will remove it from the database.

===== <RemoteServers> =====

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

The **RemoteServers** element is responsible for defining all remote servers that support ibprotocol and are a source of control variables. These can be:

  * [[en:ibvunit:start|ibvunit]] program 
  * [[en:ibmanager:start|ibmanager]] program 

Variables of these programs are fundamental elements for logic libraries - which fetch and update their values.

The **RemoteServer** element describes a single instance of a remote server and contains the following mandatory attributes:

  * **HostName** - DNS name or IP address of the machine running the remote variable server (e.g., the ibvunit program or another ibmanager).
  * **TcpPort** - TCP port number on which the given remote variable server is listening.
  * **TimeoutSec** - timeout used in communication with the given server. If any network operation associated with the given variable server takes longer than the value of this attribute, then it is interrupted and an error is logged.
  * **SleepMS** - the number of milliseconds the thread communicating with the given server is put to sleep after each attempt to communicate with it. This value should always be greater than zero to avoid excessive network load and starvation of other threads in the system trying to access the local data store.
  * **Prefix** - a string that is added to the name of each variable originating from the given variable server. This parameter was introduced to avoid conflicts in variable names, for example, when the program had more than one remote variable server defined. For instance, let's consider two ibvunit programs. If in each instance of this variable server, the Prefix attribute was set to an empty string "", then a problem would arise with variable names such as **ibvunit.version**, since each of the servers would provide the same name. However, if the **Prefix** attribute of a particular instance of the variable server was defined as **"a."** and **"b."**, then the **ibmanager** program would create two variables: **a.ibvunit.version** and **b.ibvunit.version**, thereby avoiding the problem of name conflict. A trivial example of a variable whose conflict in typical applications will not be significant is given, but the problem is relevant in the case of complex applications with multiple gateways and when there is a conflict in process variable names (e.g., **rs.0.id.1.output.do.0**). The **Prefix** attribute should be unique to prevent a conflict of names. If only one variable server is supported, then the **Prefix** attribute can contain an empty string.
  * **SecureConnection** - a Boolean attribute that indicates whether the remote server will use secure SSL communication. If so, it will use the PEM key.pem, the local ibpakiet certificate (local.cert.pem), and the local certifying authority certificate (local.ca.cert.pem). All these files should be located in the [[en:ibmanager:ibmanager-config#<License>|license]] directory.

Handling of each remote server begins with the **describe_all** command. This is intended to create variables of the appropriate types, then **get_all** commands interspersed with **set** commands are sent - if a change in the value of a variable belonging to a given server has occurred (e.g., by the control logic, the parent program, or directly by the user via the communication interface).

===== <LogicLibDir> =====

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

The **LogicLibDir** element is optional. If this section has not been defined, then the **ibmanager** program will not handle control logics and will only function as a repeater of variable servers (operating in proxy mode).

The element contains the attributes:

  * **Path** - defines the path to the directory containing the configuration files of logics and dynamic libraries of logics.

If the **LogicLibDir** element has been defined, then the **ibmanager** program, when starting, will start loading xml type configuration files of logics placed in the directory defined in the **Path** attribute, then it will start loading logics from dynamic libraries (.dll/.so).

===== <Storage> =====

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

The **Storage** element is mandatory and is responsible for configuring the local data storage mechanism.

The element contains the attributes:

  * **DirPath** - (mandatory) specifies the path to the directory where the **ibmanager** program will store data. If this directory does not exist, it will be created. If the creation fails, an error will be logged and the program will stop running.
  * **DumpPeriodHours** -  (optional) this is the time period expressed in hours. If it is defined, it must be greater than 0. This attribute defines how often the **ibmanager** program should dump the local data store to an archive file. The name of the archive file is created based on the current time and the archive files themselves are created in the archive subdirectory of the directory indicated by the **DirPath** attribute. If this attribute is not defined, then the periodic dump of archival data is not performed.
  * **MaxDumps** - (optional) specifies the maximum number of archival variable files. If it is defined then it must be greater than 0. Each time variables are dumped (periodic or on-demand, by setting the **ibmanager.dump.vars variable**), archives are counted and if their number exceeds this value, then the excess is removed from the oldest. When this attribute is not defined, then the maximum number of dumps is not checked.

===== <Alerts> =====

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

The **Alerts** element is optional. If it is defined, then the **ibmanager** program loads the alerts configuration file from the location specified in the **Path** attribute of this element. Any failure during its loading will terminate the program's operation along with an appropriate entry in the logs. If this element is not defined, then the alerts mechanism will be disabled, and any requests to send an alert by running logics will be ignored.

===== <TrackedVariable> =====

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

The **TrackedVariable** element is not significant for the user, only for the developer for the purpose of detecting software errors. It was introduced due to the complexity of handling remote variables. It is an optional element and its definition results in specific entries in the logs, which carry no information for the user.

===== <Log> =====

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

Element responsible for configuring the logging system of the **ibmanager** program.

The element contains the attributes:

  * **Type** -  indicates the outlet for the logs and can take values:
    * **Console** –  logs are displayed only on the console
    * **File** - logs are saved to a file
    * **None** - logging is disabled
  * **Level** - indicates the logging level and can take values:
    * **TraceLo** - most details
    * **Trace**
    * **TraceHi**
    * **DebugLo**
    * **Debug**
    * **DebugHi**
    * **Info**
    * **Notice**
    * **Warning**
    * **Error**
    * **Critical** – least details
  * **Params** - specifies the file where the log file is located and if it does not exist, where it should be created. The path should have syntax appropriate for the given operating system.
  * **MaxLogFileSize** - (optional) has a default value equal to 10*1024*1024 and determines the maximum size of a single log file. For performance and practical reasons, the size of a single file is larger than this value with the accuracy of the size of the logged line (in order to finish logging a full line) and up to 5 seconds.
  * **MaxLogArchives** - (optional) has a default value equal to 10, which means that in addition to the current log file, there may be up to 10 archival files. Archival files are created by adding a .N suffix to the log file name where N is an index numbered from 0. 0 means the newest archive, the higher the number, the older. The oldest archival files are removed if their number exceeds the value of this attribute.

In the sample definition of the <Log> element, the log rotation mechanism assumes the existence of up to 20 archival files. Both archival and current can be up to about 40MB in size.

===== <Credentials> =====

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

Optional element. If it is defined, then the application will include the authorization mechanism on the ibprotocol interface side.

The element contains the attributes:

  * **Path** -  points to the configuration file of the authorization mechanism.