5.3. Configuration Options Reference

The configuration directives for the SysOrb Server fall into nine categories:

5.3.1. Logging Options

logdir (path)

This is the location of the logfile. It is not the filename, but the directory in which the file should be. The file will be named server.log within the specified directory.

Default value (Unix): /var/log/sysorb

Default value (Windows): install-dir\Config

log_assert (boolean)

Whether the server should log critical internal errors.

Default value: true

log_audit (boolean)

Enable/disable audit logging - logging of all user interactions with the system.

Default value: false

log_dbms_cpu (boolean)

Whether the database subsystem should log information about how it spends its time.

Default value: false

log_dbms_debug (boolean)

Whether the database subsystem should log informational messages.

Default value: false

log_dbms_anomaly (boolean)

Whether the database subsystem should log information about certain situations, e.g. another part of sysorb requesting infomation about an object which does not exist in the database. Please note that there can be perfectly valid reasons for such queries, for instance the NetCheck engine requesting information about a NetCheck wich has just been deleted by a user.

Default value: false

log_uplink_debug (boolean)

Whether the uplink (rental license and problem reporting) subsystem should log informational messages.

Default value: false

log_tsdb_debug (boolean)

Whether the time series database subsystem should log informational messages.

Default value: false

log_socketio_debug (boolean)

Whether the network connection manager should log informational messages.

Default value: false

log_keygen_debug (boolean)

This option enables informational messages regarding Diffie-Hellman prime/generator pair generation.

Default value: false

log_snmp_debug (boolean)

Whether the SNMP subsystem should log informational messages.

Default value: false

log_esxi_debug (boolean)

Whether the ESXi subsystem should log informational messages.

default value: false

log_snmpval_debug (boolean)

Whether the SNMP subsystem should log informational messages about the values it receive.

Default value: false

log_general_debug (boolean)

Whether general debugging information should be logged.

Default value: false

log_sched_debug (boolean)

Whether the event-scheduler should log informational messages. These messages are usually not very interesting.

Default value: false

log_alarm_debug (boolean)

Whether the central decision-making process (the alarm logic) should log informational messages.

Default value: false

log_alert_debug (boolean)

Whether the alert dispatcher should log informational messages, which can be used for troubleshooting mail-server or modem dialing problems. Set this to "true" if you have problems getting alerts via e-mail or numerical pager.

Default value: false

log_netcheck_debug (boolean)

This option enables informational messages from the NetCheck module.

Default value: false

log_icmpcheck_debug (boolean)

This option enables informational messages from the ICMP (ping) module.

Default value: false

log_ssl_debug (boolean)

This option enables informational regarding the loading of the SSL library used for SSL based NetChecks..

Default value: false

log_report_debug (boolean)

This option enables informational messages from the Report module.

Default value: false

log_forecast_debug (boolean)

This option enables informational messages from the Forecast module.

Default value: false

log_upgrade_debug (boolean)

This option enables informational messages regarding auto upgrade of the agents.

Default value: false

log_scan_debug (boolean)

This option enables logging when the SysOrb Server receives scan requests from agent machines.

Default value: false

log_nodeclass_debug (boolean)

This option enables logging about the NodeClass check confiugration engine.

Default value: false

log_router_debug (boolean)

This option enables informational messages regarding grid routing.

Default value: false

log_link_debug (boolean)

This option enables informational messages regarding grid link establishment.

Default value: false

log_station_debug (boolean)

This option enables informational messages regarding grid station to station communication.

Default value: false

log_gridrpc_debug (boolean)

This option enables informational messages regarding the grid RPC communication.

Default value: false

log_gridsync_debug (boolean)

This option enables informational messages regarding grid synchronisation.

Default value: false

5.3.2. Database Options

layout_conf (filename)

This is the file from which the database back-end reads the layout information which the Web-interface needs.

Default value (Unix): /var/lib/sysorb/layout.conf

Default value (Windows): install-dir\Config\layout.conf

dbms_tsdb (filename)

This is the file in which the database back-end will store the time-series database data. This file can become rather large if many devices are monitored. The file grows with approximately 1 megabyte per monitored check.

Linux-based systems note: You can specify either a file on your filesystem, or a device-file for a block-device (such as a disk partition or a RAID device) here.

Default value (Unix): /var/lib/sysorb/main.tsdb

Default value (Windows): install-dir\Config\main.tsdb

dbms_odb (filename)

This is the file that keeps all configuration information about hosts, services, devices, users, groups, etc. It is the entire hierarchical configuration of your monitored systems and their users. This file also keeps passwords for user accounts, so you should make sure that its permissions are set correctly if you run the SysOrb Server on a multiuser system with other interactive users.

Default value (Unix): /var/lib/sysorb/main.odb

Default value (Windows): install-dir\Config\main.odb

dbms_odbj (filename)

This is the journal file for the aforementioned main.odb meta-data database file. The journal provides an efficient method for the SysOrb Server to guarantee data consistency in the meta database. The default size of this file is 8 megabytes, and the size will never change during the lifetime of the database.

Default value (Unix): /var/lib/sysorb/main.odbj

Default value (Windows): install-dir\Config\main.odbj

Performance tip: The journal can be placed on a small but fast storage device, in order to improve overall meta database performance. With the modest size of the journal, it is even possible to place it on a battery backed SDRAM device.

dbms_buffer_blocks (number of blocks)

This option specifies how many ODB blocks (default block size is 8 KiB) the sysorb-dbms process will keep in memory, to speed up normal database queries and other common operations. The larger the value, the more memory the database process will consume. The memory overhead can be estimated by multiplying the number of blocks with the block size - for example, 4096 blocks will consume approximately 4096*8 KiB = 32 megabytes of memory.

Default value: 4096

tsdb_buffer_entries (number of entries)

This option specifies how many data records (per check) there can be in the write buffer allocated allocated for each check. Enlarging this buffer will give the time series more freedom in choosing when to flush data to disk, possibly increasing performance. The cost of an increase is a larger memory footprint of the sysorb-tsdb process.

Default value: 64

tsdb_buffer_write_min (number of entries)

This option controls how many entries we want in the entry write buffer before we start flushing entries to disk. The larger this number, the fewer writes to disk will be needed. It is, however, advised that this number stays well below the tsdb_buffer_entries parameter, so that the write buffers do not fill up. If a write buffer is filled, flushing of the buffer will be forced, thereby limiting the freedom the database has to choose a convenient time to flush the data.

Default value: one quarter of tsdb_buffer_entries

tsdb_buffer_age_max (seconds)

This is the maximum allowed age (measured in seconds) of an entry in the write buffer. If an entry older than this is found in a write buffer, entries from that buffer will be flushed (no matter if tsdb_buffer_write_min is exceeded or not. The larger this option is, the more freedom the database will have in choosing when to flush data. However, if the SysOrb Server machine loses power or is in some other way shut down without giving sysorb-tsdb a chance to flush the write buffers from memory to disk, all records in the write buffers will be lost. This option is used to limit the maximum amount of data loss.

Default value: 600

tsdb_buffer_flush_batch (number of buffers)

The time series database will go through its live write-buffers in a round-robin fashion. Each second, it will consider tsdb_buffer_flush_batch buffers, and inspect whether each inspected buffer should be flushed (either because of tsdb_buffer_age_max or tsdb_buffer_write_min). This option controls how many buffers are inspected each second. The higher the number, the greater the potential peak workload on the database. If this number is low, compared to the number of checks in the system, it can however take a long time for the database to actually discover that a buffer holds entries that are too old and should be flushed.

Default value: 8

5.3.3. Network Connection Manager Options

socketio_bind_port (integer)

This is the TCP port on which the Connection Manager will listen for incoming connections. The standard SysOrb port is 3241, and there should be no reason to change this. If you must use another port, make sure that you change the port number both in the server, the agents and the web interface configuration files.

Default value: 3241

socketio_max_connections (integer)

This is the maximum number of concurrent connections the connection manager will accept. The number should be sufficiently low not to overload the server, and sufficiently high to allow service of both agents and user interface. Both agent and user interface connections are only active when needed, so this number can be less than the number of agents and active users on the SysOrb Monitoring System. If you are seeing many messages in the SysOrb Server log about connections being expired because high or low-water pressure, and your SysOrb Server can handle the higher load, you should raise this number.

Default value: 300

socketio_max_inflight (integer)

This is the maximum number (in thousands) of check-in results the connection manager will accept holding in memory, before it starts refusing agent connections. The purpose of this limit, is to prevent "check-in storms" - a situation in which a large number of agents simultaneously check in a very large number of results, causing the server to slow down, in turn causing even more data to queue up. By limiting the number of results held in memory and asking the agents to "check back later", the server can limit the load and prevent the overload. If this number is set too low, you may see the server refusing agent checkins even though it is not too heavily loaded.

Default value: 10 (thousands)

socketio_agentconf_rate (integer)

This option defines how often a single SysOrb agent may request configuration from the SysOrb server. It is given as a number of seconds. Under normal operation, an Agent will only request this information when re-started. If this limit is reached it usually points towards a problem with an agent restarting over and over. There should be no reason to increase this limit.

Default value: 600

socketio_agentconf_burst (integer)

This option defines how often a single SysOrb agent may request configuration from the SysOrb server. When an agent has requested information this many times in a row, the above rate limit will be enforced.

Default value: 5

agent_package_path (directory)

This option specifies the directory where the Network Connection Manager should look for packages for the agent autoupgrade. The directory is automatically scanned once in a while.

Default value (Unix): /var/lib/sysorb/upgrade

Default value (Windows): install-dir\Upgrade

5.3.4. NetCheck Manager Options

netcheck_limit_children (integer)

This is the number of simultaneous TCP-based NetChecks that can run at any given time. Checking mail-server or web-server response times, or the response time of any other TCP based service, will cause a check program to run. This number limits how many check programs can run at any given time. The default value should be sufficient for a very large number of NetCheck services, as most checks only run for a few milliseconds each. Setting this value too low will cause checks to be queued but not lost. Setting it too high will consume more system memory and possibly slow down the entire system thereby reducing the accuracy of the NetChecks. It is better to leave this value low than set it too high.

Note: Windows has a hard limit of 30 children, and it is not recommended setting the value above 25.

Default value (Unix): 32

Default value (Windows): 20

netcheck_process_pool_size (integer)

This option controls the size of the netcheck process pool that SysOrb will spawn. Network checks to be performed are scheduled amongst the processes in the pool in a round-robin fashion. The default value of 0 means that SysOrb will attempt to autodetect a sane value and most users should not need to overrule this.

Default value : 0 (autodetect)

custom_netcheck_conf (filename)

This option points to the configuration file for the custom NetChecks. An example of how such a file should be written can be seen in the custom_netcheck.conf.sample in the same directory as the main configuration file.

netcheck_ping_spacing (integer)

This option defines the minimal spacing between ICMP ECHO REQUEST packets in microseconds, increase this if your network equipment drops ICMP packets because of buffer overruns.

Default value: 10000 μs

dns_cache_secs (integer)

The maximal time SysOrb will cache the result of DNS lookups in seconds.

Default value: 86400 s

libssl (filename)

In the event that the NetCheck engine cannot locate the SSL-library, the excact path to the library can be specified using the libssl option. If the libssl option is set, the NetCheck engine will only try to load the exact specified library. Otherwise it will try a list of possible names for the library, and use the first one that loads.

Default value: not set

Note: This option is not available on Windows, as the SSL library is distributed with the SysOrb Server package.

5.3.5. General SysOrb Server Options

working_directory (pathname)

This is the directory that will be used as working directory by the server once it is running. It does not matter much what this is set to, if all other filenames use absolute paths (which they should). On UN*X systems and Linux this option lets you set the working directory to somewhere outside of e.g. /home thereby allowing you to unmount /home without shutting down the SysOrb Server. On Microsoft Windows this option has no other effect than providing a base path for relative filenames.

Default value (Unix): /var/lib/sysorb

Default value (Windows): install-dir

license_path (pathname)

The SysOrb server will search this directory for the sysorb.lic license file.

Default value (most Unix'es): /etc/sysorb

Default value (Windows): install-dir\Config

variable_file (filename, Unix only)

This file is used for storing various non-critical values. The sysorb user must have write access to this file.

Windows note: This option does not exist on Windows, because the information is stored in the sub-key Variables in the registry under SOServer.

Default value (most Unix'es): /var/lib/sysorb/variables.server

smem_prefix (path and filename prefix)

This location prefix is used when building up the absolute filenames of files used internally by SysOrb to set up communications between the various processes that make up the SysOrb server.

Default value (most Unix'es): /var/lib/sysorb/smem

Default value (Windows): SMem

smem_size (size in megabytes)

Total size of the shared memory region used by the SysOrb processes for intercommunication.

A too small value will cause excessive communication overhead on a busy server, while a too large value will waste too much memory and may exceed operating system or architecture limitations on memory mapping sizes.

Default value: 128

resource_directory (pathname)

The resource directory is the directory where pictures and css-files used for email-alerts and -reports are kept.

Default value (most Unix'es): /var/lib/sysorb/resources

Default value (Windows): install-dir\Resources

upload_serverinfo (boolean)

This option controls whether this SysOrb server should send important information about its health to Evalesco A/S. If enabled the SysOrb server will try uploading the information using the HTTP protocol.

Default value: false

allow_import_export (boolean)

In order to export or import sensitive data like passwords and agent keys you need to enable this option. This option should _only_ be set to true during import or export. When enabled the system in vulnerable to password and agent key sniffing among other things..

Default value: false

max_scan_processes (integer)

The maximum number of parallel jobs to run during AutoDiscovery.

Default value: 8

allowed_candidate_nodes (integer)

When a sysorb agent checks in to the server, but is not already configured on the server, a candidate node is created. This candidate node can be viewed in the web interface and used to create a real node. This option allows you to limit the number of candidate nodes that can be on the server at one time. Futher agents will be rejected without notice.

Default value: 10

spare_keypool_size (integer)

The SysOrb server will try to have this number of Diffie-Hellman prime/generator pairs precalculated for future agents checking in.

Only if you have many agents registering with the SysOrb server in quick succession will it make sense to increate this value.

Default value: 5

keypool_reuse (integer)

The SysOrb server will use a Diffie-Hellman prime/generator pair for negotiating secret keys with this many agents before discarding it.

Only if you have many agents registering with the SysOrb server in quick succession will it make sense to increase this value.

Default value: 1

passive (boolean)

If this option is enabled, the SysOrb server will perform no NetChecks, generate no reports, not do AutoDiscovery, or take any other action. It will still accept incoming connection from the web interface and from SysOrb agents. This option is mostly useful for recovery, if one has accidentally started an AutoDiscovery, SNMP scan or the like, that turns out to slow down or crash the SysOrb server.

Default value: false

5.3.6. Alert Dispatcher Options

mail_server (hostname)

This is the name of the mail-server (a server accepting SMTP connections, and willing to relay for the SysOrb Server). It should be set to the name of a local mail relay on your site.

Default value: localhost

mail_from (string)

This is the domain name that will be used in the HELO mail_from SMTP negotiation with the mail server, when an alert is sent via e-mail.

Default value: localdomain

reply_mail_to (string)

This is the e-mail address that will be put in the From: field of all e-mails sent by the SysOrb Server. It should be a valid e-mail address of the SysOrb Server administrator in the form of: user or user@host.

Default value: root@localhost.localdomain

alert_sms_subject (string)

Setting this option to a value, will make all SMS's sent via email to SMS gateways have the same subject. This can be useful, if the email to SMS gateway requires that the email has identification in the subject.

Note: Even with this option set, it is still possible to override the subject individually by "Forcing" the subject on a specific path, through the web-interface.

alert_defer_at_boot (minutes)

If the SysOrb Server has a lot of agents configured, it sometimes sends out premature alerts, for agent checkin etc. In order to prevent this, the alert_defer_at_boot can specify for how long in minutes the SysOrb Server will defer sending out alerts, when it is started.

Default value: 2

alert_retry_delay (seconds)

If an alert transmission fails, this is the delay in seconds that the SysOrb Alert module will wait until it re-tries the transmission.

Default value: 30

alert_attempts (integer)

This option specifies the maximum number of times the SysOrb Alert module will attempt the transmission of a single alert message.

Default value: 5

alert_to_incident_log (boolean)

This option controls wether SysOrb will log alert path usage to the nodes incident log.

Default value: false

agent_checkin_delay (integer)

This option controls when agent checkin reached ALERT level.

Default value: 30

webinterface_url (string)

This is the URL for the Web-interface that will be put in the alert messages, for the user to click on. It should point on the preferred Web-interface for the server.

Default value: http://localhost/sysorb

modem_port (filename)

This is the name of the modem device on your system. On Unix-like platforms, please make sure that the sysorb user has both read and write access to the device pointed to by this option, as the server will otherwise be unable to use the modem.

Default value (Unix): /dev/modem

Default value (Windows): COM1

modem_options (string)

This comma separated list specifies the capabilities of the attached modem. The possible elements are

page

The modem is able to dial a numerical pager. (Any modem should have this capability).

sms

Indicates that the modem supports the GSM 07.07 and GSM 07.05 standards.

Default value: page

modem_init (string)

This string is sent to the modem before a number is dialed.

Default value: ATE0 S7=20 S8=2

modem_sim_pin (string)

If you use the Siemens M20 GSM box for sending SMS messages directly to your cellular phone, you must supply the PIN code for the SIM card here, if one is needed for the SIM card to work.

modem_baud_rate (integer)

Use this option to set the baud-rate of the serial port SysOrb uses to communicator with the modem. The allowed values are 200, 300, 600, 1200, 2400, 3800, 9600, 19200, 38400.

Default value: 19200

modem_pager_timeout (seconds)

Use this option to set the maximal time to elapse between the ATD and ATH commands, when SysOrb is dialing a numerical pager (or an analog phone.)

Default value: 30

agent_checkin_delay (seconds)

Allows the user to define how much time SysOrb server gives an agent before SysOrb server generate "late for checkin" alert

Default value: 30

Note: You might experience "false" agent late for checkin alarms e.g. during the night. These alerts go away after a few minutes however it is annoying for a person on night call to get woken up, just to see a clean SysOrb alert list with no alerts.

Cause: These alarms are not a result of buggy SysOrb, but a natural result of e.g. a network under heavy pressure. It might be the case that a lot of backup jobs are running and this is taking up all the bandwidth in the network. This can prevent the agent from checking in to the SysOrb server in time. Once there is enough available bandwidth the SysOrb agent will check in again.

5.3.7. SNMP Options

max_snmp_table_entries (integer)

If SysOrb sees more that this number of entries in one SNMP table during a scan, the rest will be ignored.

You may increase this value if any of your SNMP devices has huge tables. Please note that the SysOrb web interface may navigate slowly in such cases.

Default value: 500

snmp_max_retrans (integer)

The number of retransmits that will be done if no response is received for SNMP probes during normal operation.

Normally you should never need to change this value, but if your network or the probed device is frequently dropping UDP packets it may be necessary to increase this value slightly.

Default value: 3

snmp_max_retrans_walk (integer)

The number of retransmits that will be done if no response is received for SNMP probes during a SNMP walk of a device.

Normally you should never need to change this value, but if your network or the probed device is frequently dropping UDP packets it may be necessary to increase this value slightly.

Default value: 5

snmp_timeout_initial (integer)

SNMP probe packets are timed out and retransmitted if they do not receive a timely reply (number of retransmits are controlled by 'snmp_max_retrans' and 'snmp_max_retrans_walk'). For each retransmit the timeout is doubled, up to a maximum ceiling specified by 'snmp_timeout_max'. This value specifies the initial timeout for the first packet, before retransmit, in milliseconds.

You should only ever raise this value if you experience that SNMP probes often fail and you suspect this to be due to dropped UDP packets on the network rather than a problem with the probed device.

Default value: 500

snmp_timeout_max (integer)

SNMP probe packets are timed out and retransmitted if they do not receive a timely reply. For each retransmit the timeout is doubled, up to a maximum ceiling specified by this parameter. This value is in milliseconds.

You should only ever raise this value if you experience that SNMP probes often fail and you suspect this to be due to dropped UDP packets on the network rather than a problem with the probed device.

Default value:

snmp_packet_spacing (integer)

This option defines the minimal spacing between SNMP packets in microseconds, increase this if your network equipment drops SNMP packets because of buffer overruns.

Default value: 10000 μs

5.3.8. Grid Options

ssec_keylength (bits)

This SysOrb station (server) will generate RSA station keys with this many bits.

Default value: 1024

ssec_min_keylength (bits)

This SysOrb station will require RSA keys from other stations to be at least this many bits.

Default value: 1024

ssec_secret_keylength (bits)

This SysOrb station will generate AES session keys with this many bits

Default value: 256

ssec_secret_min_keylength (bits)

This SysOrb station will require AES session keys from other stations to be at least this many bits.

Default value: 128

ssec_secret_lifetime (seconds)

Determines how often session keys should be replaced

Default value: 600

grid_default_ttl (integer)

Default TTL for grid messages

Default value: 8

master_notify_queue (integer)

The maximum number of pending updates that a SysOrb master will keep track of. If the satellite fails to acknowledge them, the master will kick the satellite.

Default value: 8192

satellite_tsdb_async (integer)

The maximum number of timeseries being propagated from the satellite at one time

Default value: 32

5.3.9. WebAPI Options

wapi_enabled (boolean)

This option enables WebAPI service

Default value: false

wapi_port (integer)

This option defines a port WebAPI uses to serve requests.

Default value: 8088

wapi_use_ssl (boolean)

This option tells WebAPI to use ssl.

Default value: false

wapi_ssl_cert_path(string)

This option defines path to ssl certificate files.

wapi_threads (integer)

This option defines the number of threads to serve user requests in parallel.

Default value: 1