Configuration file of the ibmanager program

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

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>

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 Latitude="52.069167" Longitude="19.480556" />

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 Name="Installation Name" Version="Version Number" Instance="Instance Name" />

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 Path="/ibsystem/license/license.dat" SignaturePublicKeyPath="" />

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

The element contains URLs to project descriptor files grouped in the Projects element for 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 ibgui software.

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

The IbProtocol element describes the parameters of the protocol, with which, external programs can communicate with the ibmanager software.

The element contains attributes:

• TcpPort - TCP port address on which the 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 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 QueryPort="2005" ResponsePort="2005" TimeoutSec="3" MaxSilenceSec="20" />

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 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>
   <RemoteServer HostName="127.0.0.1" TcpPort="2001" TimeoutSec="20" SleepMS="100" Prefix="" SecureConnection="false" />
</RemoteServers>

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

• ibvunit program
• 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 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 Path="/ibsystem/ibmanager/logic" />

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 DirPath="/ibsystem/ibmanager/storage" DumpPeriodHours="24" MaxDumps="10" />

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 Path="/ibsystem/ibmanager/alerts.xml" />

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 Name="rs.0.id.255.input.t.0.value" />

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 Type="File" Level="Info" Params="/ibsystem/ibmanager/ibmanager.log" MaxLogFileSize="40000000" MaxLogArchives="20" />

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 Path="/ibsystem/ibmanager/credentials.xml" />

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.