1.1. SysOrb Components

The SysOrb Network Monitoring System consists of several major software components, the responsibilities of which are outlined below:

• The SysOrb Server: This is the center of the SysOrb System. The Server can remotely check networked services (such as web servers and mail servers) via NetChecks, but it is also the central component to which the Agents will report device information and statistics. The SysOrb Server is the central repository in which all statistical and operational data are stored, and it is the entity in the SysOrb System that will actively alert administrators when problems arise in any of the monitored systems.

  In the following text a node is any machine or device that can be monitored by SysOrb. A host is a node where the SysOrb Agent can be installed.

• The SysOrb Agent: In order to actively monitor local devices (such as harddrives, memory, processor statistics etc.) on networked systems, those systems must run the SysOrb Agent. This program will gather operational information from the system on which it is running, and report these data to the SysOrb Server for further processing. In case of failures (such as a harddisk running full, or a crashed service process), the SysOrb Server can actively alert the administrators of the particular machine that reported the failure.

• The Web Interface: In order to allow easy access to the monitoring data and then configuration of the SysOrb System from anywhere and from any platform, the Web-based Interface is provided. This User Interface ships as a part of the SysOrb Server, and is usually (but not necessarily) run on the same physical machine as the one running the SysOrb Server. In order to fully use and configure monitored services or devices in the SysOrb System, all you need is a computer with a web-browser capable of accessing the SysOrb Server computer.

1.2. How It Works

To illustrate how the SysOrb components work together, Figure 1 shows a setup of a SysOrb Server, some SysOrb Agents and a SysOrb Web Interface.

The setup consists of a SysOrb Server, a SysOrb Agent and a SysOrb Web Interface. When a SysOrb Agent checks in on the SysOrb Server information about the SysOrb Agent's current status is stored in the SysOrb Server's database.

The SysOrb Web Interface connects to the SysOrb Server and through this interface the SysOrb user can monitor the network, add new SysOrb Agents and similar operations.

2.1. Agent Requirements

The SysOrb Agent software will run on most hardware used in servers today, and it currently supports most major server operating systems. Because of this the SysOrb Agent software can be run on your servers without interfering with the servers' normal operations.

In general, the SysOrb Agent has very low system requirements. If your server hardware can run the installed operating system, chances are it can run the SysOrb Agent without problems. The actual requirements for the agents will vary depending on the amount of checks configured on the given agent, and the check-in interval configured.

2.2. Server Requirements

The requirements for the SysOrb Server depend on the number of NetChecks, AgentChecks and snmpChecks monitored. If only a small number of these need to be monitored the SysOrb Server can be run on very modest hardware. The more checks monitored, the higher the requirements for the SysOrb Server.

• Windows 7 or Windows Server 2012 (x86_64):

  • CPU: Intel Core2 compatible or better

  • RAM: 1 GB free memory for smaller installations (less than a hundred nodes configured). 2-8 GB recommended for larger installations.

  • Disk: 100MB for installation and log files and approximately 1 MB per configured check. E.g. an installation with 100 nodes and 100 active checks for each node would require 10 GB of disk space for the database

• Red Hat Enterprise Linux 6 (x86_64):

  • CPU: Intel Core2 compatible or better

  • RAM: 1 GB free memory for smaller installations (less than a hundred nodes configured). 2-8 GB recommended for larger installations.

  • Disk: 30MB for installation and log files and approximately 1 MB per configured check. E.g. an installation with 100 nodes and 100 active checks for each node would require 10 GB of disk space for the database

• Solaris 11 (x86_64):

  • CPU: Intel Core2 compatible or better

  • RAM: 1 GB free memory for smaller installations (less than a hundred nodes configured). 2-8 GB recommended for larger installations.

  • Disk: 50MB for installation and log files and approximately 1 MB per configured check. E.g. an installation with 100 nodes and 100 active checks for each node would require 10 GB of disk space for the database

• Debian GNU/Linux 7.0 (x86_64):

  • CPU: Intel Core2 compatible or better

  • RAM: 1 GB free memory for smaller installations (less than a hundred nodes configured). 2-8 GB recommended for larger installations.

  • Disk: 30MB for installation and log files and approximately 1 MB per configured check. E.g. an installation with 100 nodes and 100 active checks for each node would require 10 GB of disk space for the database

There are many other factors that affect overall system performance. Large installations may need not just bigger but also faster storage. In general, more memory will help the disk I/O system. Using servers with more than one CPU core is also beneficial to SysOrb, especially in large installations.

3.1. Installing the SysOrb Server

The SysOrb Server is a fairly complex piece of software, yet the installation itself is simple. Please refer to Chapter 5 for detailed installation instructions for your particular server platform.

The Server may be able to run with its default configuration right after the install completes, but it is recommended that the configuration section is consulted before actually running the Server.

The SysOrb Server installation also contains the SysOrb Web interface. This section will not describe setup of any specific web-servers. The SysOrb Web Interface consists of CGI programs, which will work with any web-server supporting the CGI standard.

You can install the Web Interface wherever you please, you can even run a SysOrb Server on one platform (say, Solaris) and the Web Interface on another (for example Windows). If you do not want to install a Web-server on the SysOrb Server machine, you can install the SysOrb Server package on any other machine, and then disable the SysOrb Server there so that only the web interface remains active.

3.2. Installing a license file

If you have purchased a license for SysOrb, you need to install it after you finished the installation of SysOrb.

The installation is simple. Just overwrite the old sysorb.lic file with the one that you downloaded from the license manager. The default license location on Microsoft Windows is:

install-dir\Config\sysorb.lic

On Debian, and Red Hat Linux systems it is:

/etc/sysorb/sysorb.lic

And on Solaris it is:

/etc/sysorb/sysorb.lic

Once the license file is in place, you will need to restart the SysOrb Server in order for it to notice the change of the license. If you are not certain that the installation of the new license worked, you can look in the server.log for a line that says:

[dbms]: License is valid for xx servers and xx agents.

3.3. Upgrading the SysOrb Server

This chapter describes the steps necessary to upgrade you SysOrb server to version 4.6.0.

You simply upgrade SysOrb server by stopping the service, installing the new package, and starting the new SysOrb server afterwards. No database conversion is needed.

3.4. Installing the SysOrb Agent

The SysOrb Agent is a very light piece of software, with very few configuration options. It retrieves its configuration from the SysOrb Server during normal operation, so the only configuration actually needed on the agent side (for the basic agent functionality) is the list of SysOrb servers to which the Agent should check in, and a name and a SysOrb domain used by the agent to identify itself to the SysOrb server.

You can use the DNS name of the host as the Agent name, or you can use the host's IP address. Both options will allow the SysOrb server to perform NetChecks and snmpChecks on the host too, provided that the given DNS name or IP address is actually reachable from the SysOrb Server. If you do not need to perform NetChecks or snmpChecks on the host, the Agent name can be chosen freely.

On the SysOrb server you are supposed to create a node with the exact same name as specified in the configuration, in the specified domain.

To actually tell the SysOrb Server to monitor a specific SysOrb Agent you need to use the SysOrb Web Interface. See User's Guide to the SysOrb Monitoring System for more information on how to use the SysOrb Web Interface.

3.5. Unattended installation on Windows

In order to do an unattended on Windows, one must use the msiexec program from the command line. The basic syntax of an unattended installation is:

msiexec /passive /i sysorb-agent-4.6.0-6039.win7-amd64.amd64.msi

This will install the SysOrb agent using the default configuration options, meaning the SysOrb agent will most likely have to be configured after installation.

To avoid having to configure the SysOrg agent after installation, arguments can be given to the installer changing the default settings. The msiexec can be given properties as Property=PropertyValue on the command line.

The SysOrb agent installer uses a number of properties:

• AGENTNAME - The name of this SysOrb Agent.

• SERVERLIST - Comma seperated list of SysOrb servers the agent should check in to.

• AGENTDOMAIN - The domain for this SysOrb agent.

• AUTOUPGRADE - Set to 'true' to

• LOGFILE - The full path to the agent log file.

• LOGCHKCONF - The full path to the log check configuration file.

• SERVERPORT - The port the SysOrb server is listening on.

• LOGDAYS - The number of days between log file rotation.

• LOGLEVEL - The amount of logging.

• AUTOUPGRADE - Set to 'true' to allow autoupgrade of the agent, 'false' otherwise.

So, in order to do an unattended installation of the SysOrb agent with the name MySysOrbAgent checking in to the server MySysOrbServer disallowing automatic upgrades, one could execute:

msiexec -passive -i sysorb-agent-4.6.0-6039.win7-amd64.amd64.msi AGENTNAME=MySysOrbAgent SERVERLIST=MySysOrbServer AUTOUPGRADE=false

5.1. Microsoft Windows

Server configuration is done in a program called SysOrb Config which can be found in the start menu. This program includes detailed descriptions of each option.

The program is located in the Programs folder specified during the installation.

5.2. Unix-like systems (FreeBSD, Linux and Solaris)

The configuration file is located in:

/etc/sysorb/server.conf

on all Unix-like platforms, except FreeBSD where it is located in:

/usr/local/etc/sysorb/server.conf

This file contains the configuration for the server. If you change this file you must restart the server for the changes to take effect.

You can however make the server reopen its log file by sending a hangup signal (SIGHUP) to the sysorbd process. This is used in the logrotate script that accompanies the server on Linux.

The options of primary interest are likely to be the location of the database files, and the logging options. See the reference for details.

5.3. Configuration Options Reference

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

• Logging Options defines where the SysOrb Server should keep its logfiles and what information should be logged.

• Database Options defines where the data files for the SysOrb Server's database should be stored.

• Network Connection Manager Options defines what TCP port the SysOrb Server should use and how many concurrent connections it will accept.

• NetCheck Manager Options defines maximum number of NetChecks (e.g. mail server check).

• General SysOrb Server Options defines other options for the SysOrb Server.

• Alert Dispatcher Options defines how and to whom alerts will be given.

• SNMP options Options defines various apects on how SysOrb should perform SnmpChecks.

• Grid Options defines options for a grid of SysOrb servers and satellites.

• WebAPI Options defines options for a WebAPI service.

5.4. Troubleshooting HTTPS/IMAPS/POP3S problems

The SysOrb Servers SSL support uses the OpenSSL libraries. On all platforms except Windows, it uses the version of OpenSSL that ships with the operating system. This chapter describes how to troubleshoot SSL check problems on the Unix-like platforms.

The most common problem is that the check shows "No Connection" even though the service is accessible. It usually happens because the OpenSSL library is not installed on the host OS. If this is the case, you will be seeing "No connection" errors in the SysOrb Web Interface, and the server log will contain the following message:

Could not load SSL-library. Please check the administrators guide for information 
about how to fix this problem

The first thing to check is that the OpenSSL library is installed on the host OS. How to ensure this can be seen in the list below:

It is not necessary to restart the SysOrb Server, if the OpenSSL library was installed while the SysOrb Server was running.

If the OpenSSL library is installed, and SysOrb still cannot find the OpenSSL library, you can specify the exact location of libssl.so (or similar named), by using the libssl server configuration option. See Section 5.3.4 for information about this option.

If you instead get a message stating

Error loading library

Error dynamically loading function

5.5. On the fly debug logging

SysOrb has the ability to add debug logging on the fly without having to restart the service. The extra debug information will be added in the "server.log" file.

To add debug logging, simply create a new empty file in the log director, naming it according to the information you want to add to the serverlog. It is important that the naming of the files, does not include any extensions. Once they have been placed in the correct directory, the logging should start to add data to the server.log

Default settings for where log files are placed, and where the log check-files should be added, are:

• Default log directory (Unix): /var/log/sysorb

• Default log directory (Windows): install-dir\Config

To avoid that you get huge log files, you should only add debug logging when needed. Once you do not need the debug logging, you simply delete the files again, and the logging will stop.

Below is a list of filenames that can be used to add the debug logging.

Look in Section 5.3.1 to get more detailed information about the debug logging options.

6.1. General Web Interface Options

7.1. Web Server Configuration Reference

The following sections list the available configuration options for the Web Server. Note that usually the Web Server is ready for use after the installation.

8.1. Agent Configuration Reference

Most of the options in the SysOrb Agent configuration are specific to the site where the SysOrb runs and, as such, no appropriate default values can be given. When installing the SysOrb Agent remember to check that the configuration options matches the environment in which the SysOrb Agent works.

The first three options need to be changed on almost all new installations.

The following options rarely needs to be changed:

8.2. Releasing keys to force registering at SysOrb server

If you for some reason would like an agent to check-in to another server than the one it already does, you have to release the authentication key for the agent. Both the server and the agent has the key, which is used for security purposes.

8.3. Configuration of custom checks

If the built-in checks of the SysOrb Agent does not suffice for you particular setup, you may write extension scripts that can perform the check.

You can write these scripts in any language you desire. The only requirement is that the script must deliver the result of the check to the SysOrb Agent in one of two ways.

• If the check is either good or bad, the script must tell the SysOrb agent by the exit code. A non-zero exit code indicates a bad result, while an exit code of zero indicates a good result. How exit with specific exit codes depends on the script language used.

• If the check can return a numeric value within some range, it must output that value decimally to standard output on a line like: "Result: 1234". Note that the colon must be present, and that the Agent is case sensitive. The SysOrb Agent will parse the output from the script, putting any line not conforming to the above format into the agent log file.

The custom checks that an Agent is able to execute is configured using a file on the machine running the SysOrb Agent. It may have been more convenient to be able to do it from the web interface, but that would open serious security risks, as any SysOrb user, with capabilities to configure checks, would be able to have the agent execute arbitrary shell commands.

In order to use custom checks you must first tell the SysOrb Agent where to find the custom check configuration file. On non-windows systems this is done by adding a line like

custom_chk_conf=/etc/sysorb/custom.conf

to the agent configuration file (usually located in /etc/sysorb/agent.conf). On Windows you must open the SysOrb Configuration utility located in Start menu->Programs->SysOrb->SysOrb Configuration. In the configuration tree choose SysOrb Agent->Configuration files->Custom checks and enter the path where you are going to put the new configuration file.

After changing this path, the Agent must be restarted, but wait until you have put something into the new file.

You must edit the new file custom.conf in order to configure which custom checks the agent can perform. The format of the file is most easily illustrated with a few examples of custom checks:

New to 4.4: it is now possible to get extended result description from boolean check: just add result_pattern string to the check config with appropriate pattern. Then this description will be displayed in the check result.

# Comment lines begin with #
[check name]
command=/path/to/the/execfile parameters
timeout=10
        

[check name]
type=integer
unit=kB
command=/path/to/the/execfile parameters
timeout=10
        

[check name]
type=real
unit=s
command=/path/to/the/execfile parameters
timeout=10
        

[check name]
type=diff_integer
unit=kB/s
command=/path/to/the/execfile parameters
timeout=10
        

[check name]
type=diff_integer
unit=kB/s
command=/path/to/the/execfile parameters
timeout=10
        

Whenever you edit this file, you must push open a web interface and push Rescan on the AgentChecks tab on the Configure page for the host in question. You do not need to restart the SysOrb Agent, unless you have changed the location of this file.

Sometimes you do not write the script yourself, and there is no easy way of having it output its result on a line like Result: 1234. In that case you can instruct the SysOrb Agent to look for the result in lines containing other text. You do that by means of a POSIX regular expression. The syntax of regular expression can be found at: http://www.opengroup.org/onlinepubs/007908799/xbd/re.html

[resp_time]
type=integer
command=measure-command
result_pattern=^Response time: ([[:digit:]]+) ms$
timeout=10
        

[temp_count]
type=integer
command=find /tmp -maxdepth 1 | wc -l
result_pattern=([[:digit:]]+)
timeout=10
        

8.4. Configuration of AgentActions

Starting with SysOrb version 2.4, you can now define AgentActions, which is actions carried out on the Agent machine, when a user orders this through the Web Interface. These actions can help ease remote administration, as they can be defined to carry out common tasks on machines. An AgentAction could as an example restart a webserver, or reboot the target machine.

In order to use AgentActions you will first have to configure the Agent to read the actions from a configuration file. The name of this file is specified through the actions_conf option in the agent configuration (see Section 8.1 for information about how this is done).

The fileformat for the AgentAction configuration file resembles the fileformat of the Custom Check configuration file very much. The format consists of a block as following for each action:

# Comment lines begin with #
[action name]
command=/path/to/the/execfile parameters

The action name between the [ and ] is the name displayed to the user of the Web Interface. The command parameter is the command which is executed. On Unix-like systems this command is passed to the shell, so normal shell syntax can be used.

As an example, the following configuration file will create an action that will restart IIS on a Windows 2000 Server installation.

# Restart IIS.
[Restart IIS]
command=iisreset
        

Once the AgentAction configuration file is in place, you must rescan the agent before the actions appear in the Web Interface. When they appear, they will be accessible from the Node overview page, and from the AgentCheck configuration pages.

8.5. Configuration of Automated Actions - Remedy

Introduced in SysOrb 4.0, remedy is a functionality that makes it possible for SysOrb to automatically carry out an agent action. A typical situation where remedy is used, could be to automatically restart a service if it stops.

To set up a remedy, the first thing to do is to set up a Agent actions, look in Section 8.4 if you want to know more about this topic.

After this, configure the check, by choosing the action that you want to happen when the check goes into alert in the remedy dropdown. Once this is done, remedy should run as soon as the check goes into alert, triggering the action that have been selected.

Once an automatic action has been carried out by SysOrb, the remedy will be disabled for 30 minutes, which means, that if a second alert comes up, the check will go into alert state, and follow through as normal.

To come with an example: A server is monitoring a service, that HAS to run all the time. However, due to some issues on the server, the service will shut down every now and again, therefore a agent action that restarts the service have been set up. Remedy will make sure, that if the service only shuts down one time, it will automatically restart it with the agent action, however, if the service goes down a second time within 30 minutes (while remedy is disabled) it will go into alert. This is done to make sure that if the service goes down for good, and do not recover, SysOrb will tell you.

At the same time, when remedy is executed, there is automatically introduced a 5 minutes unexpected downtime for the whole node, this is done in order to avoid alarms from other checks which might arise because of the action being executed. A common situation could be: A web site starts running poorly. SysOrb remedy is set to re-starts IIS, if a site is responding above a certain limit. Restarting IIS causes all sites on the host to temporarily malfunction, but we do not want to have alarms from all sites. If restarting the web server has solved the problem, everything will be back to normal when the node comes out of downtime. The incident log on the given node will tell you when SysOrb executed the remedy.

8.6. Configuration of LogChecks

The SysOrb Agent can scan logfiles on the host machine, and report any error messages or unexpected event to the SysOrb Server, providing a quick overview of all machines on your network.

The files that the Agent can monitor this way must be specified in a configuration file on the machine running the SysOrb Agent. This is a safety measure, guarding agaist a compromised SysOrb Server being able to retrieve a copy of any file on the hosts running SysOrb Agents.

The name of the file containing the definitions of the allowed LogChecks is given in the Agent configuration option log_chk_conf (see Chapter 8 for more information). It is usually called log.conf, a sample file allowing a few system log files to be scanned is included in the SysOrb Agent package.

The file contains a number of lines that each specifies a path that is to be searched for log files to monitor. This can be a specific file path, such as C:\logs\error.log or /var/log/messages. But it can also contain the following special wildcard characters. '?' can match any character. '*' matches any character string of any length. '**' matches any directory path. Thus, the path C:\logs\log??\**\error.log matches C:\logs\log01\sub\dir\error.log and C:\logs\log02\sub\sub\dir\error.log, but not C:\logs\log002\sub\dir\error.log.

You can also specify to scan for eventlogs by setting the path o 'eventlog:*'. This will scan for all eventlogs available, but you can replace '*' with a specific event log name.

Note that for these logs to actually be monitored, you will have to configure them on the SysOrb server, setting up how often the check should be performed, along with various other parameters. (See the User's Guide for information on how to activate LogChecks.)

/var/log/messages
/var/log/apache/virtual-domain-*/error.log
eventlog:*

8.7. Enabling IPMI hardware monitoring

The agent supports monitoring of hardware parameters such as fan speeds, temperatures, voltages etc. by means of the IPMI (Intelligent Platform Management Interface) standard on supported server and operating system combinations.

Hardware monitoring with IPMI is supported on these operating systems:

9.1. Grid overview

The SysOrb Grid functionality allows for centralized secure monitoring of remote networks. A "satellite" can be installed on a remote network, and perform NetChecks, SNMPChecks and receive Agent Check-ins on that remote LAN. The satellite can securely deliver all locally gathered check results back to a "master", the single centralized SysOrb Server.

A grid will contain one master, and one or more satellites. These are collectively called "Stations" in the grid. It must be possible, network wise, for either the master to initiate a TCP connection to the satellite, or, for the satellite to initiate a TCP connection to the master. Therefore, it is actually possible to monitor multiple LANs sharing the same IP ranges (for example the 10.0.1.X series), as long as the satellites can connect to the master.

If the network connectivity between a satellite and the master fails, the satellite will continue to run all configured checks on its local network. It will hold all measurements gathered in its local database, until the network connectivity comes back up. The satellite does not hold measurement data locally for any longer than what is necessary - but since it does include the full featured database already used in the common SysOrb Server product, it can spool measurement data to disk efficiently for very long periods of time, if the network outage is prolonged.

The high levels of security in the grid networking layer, combined with the autonomy of the grid satellites, allows the use of satellites for running SNMPChecks and NetChecks on remote locations, securely on the LAN, and reporting back these results in a safe manner to a central SysOrb Server (a Grid Master). Even though a VPN could also be used to secure the otherwise inherently insecure SNMPChecks and NetChecks, a VPN would not allow for continued monitoring in case of network outages, and the VPN itself would incur a significant and unpredictable latency to the checks. In other words, the grid solution with satellites allow for consolidated monitoring scenarios that are not possible to achieve using other conventional technologies, as, for example, VPNs.

9.2. Configuring the Master

Your grid master will be the station on which all day-to-day operations happen. It is the station that will send out alerts, and it is the station that will store all historical data for every check running on the grid. Except for the initial satellite setup, all configuration of every monitored node in your grid will also be done via. the web interface on the grid master.

9.3. Configuring the Satellite

Configuring the satellite is very similar to configuring the master. You must perform a number of steps here using the web interface on the satellite system. However, there will be no use for the web interface once the satellite is configured. It would therefore be wise to un-install or disable the web interface on the satellite once the configuration is done. Please also note that the satellite will have its own administrator user, with the default "admin" login name and default password. The password on this account should be changed to prevent others from reconfiguring the satellite station!

9.4. Getting started with remote monitoring

You can specify, either on a check-by-check basis, per node, or per domain, from which grid GID SNMPChecks and NetChecks should be performed. In order to get started with your satellite quickly, we suggest that you enter the configuration page for the exported domain, using the web interface on your master station, and specify that all checks should be performed on the GID of the satellite. Enter "Configure" and "Edit" for the exported domain, in order to do this.

Now, you can run an "Auto discovery" under the exported domain. This will start an auto-discovery process on the remote satellite, and the satellite will then configure any nodes that it discover on the remote network. These nodes will appear as they are found, in the web interface on the master.

From here on, you can add new checks, re-configure the ones already set up, add or delete nodes, etc. etc. All reconfiguration that you perform via. the web interface on the master, will be propagated to the relevant remote satellites. The satellites will report back check results to the master, where you can access the graphs and where alerts can be generated. In fact, as soon as the grid is configured, the day to day administration is very similar to the common setup with only one SysOrb Server, except that you now have the ability to run NetChecks and SNMPChecks efficiently and securely on remote locations.

10.1. Adding MIB files

In order to monitor nodes using snmpChecks the SysOrb server must know about the name, measuring scale etc. of the parameters to be monitored. These informations is stored in MIB (Management Information Base) files.

SysOrb comes with a number of MIB's pre-installed. These MIB's cover standard parameters such as traffic statistics for routers and switches, and some common printer parameters. You should be able to set up basic monitoring of almost any SNMP enabled router, switch or printer without adding other MIB files.

Should you, however, wish to monitor vendor-specific parameters on your network equipment, you will need to add the relevant MIB files to the ones already in SysOrb. This is done while the SysOrb server is running and operational.

To add a MIB file named xyz.mib to a running SysOrb server, execute the command sysorb-mibparser -l admin xyz.mib, assuming a SysOrb user named admin exists in the root domain, and has appropriate privileges. The sysorb-mibparser utility will then extract the information from the MIB file and insert them into the running SysOrb database. Afterwards SysOrb does not need the file xyz.mib any more.

After adding the needed MIB files, you must perform a SNMP scan (again) of the nodes supporting any of the newly added parameters. You do that through the SysOrb web interface by clicking configure, browsing to find the node, clicking snmpChecks and finally clicking on the rescan button at the bottom of the page.

The full syntax of sysorb-mibparser is:

sysorb-mibparser [-h] [-s server] [-p port] -l login [-P password] -e | -r | mib-file...

10.2. Custom NetChecks

In some cases the NetCheck capabilities of the SysOrb Server is not good enough to satisfy a specific need. In these cases a Custom NetCheck can be created.

A Custom NetCheck functions the same way as a normal NetCheck. That is, the result from a Custom NetCheck is the amount of time it took to perform the check. They can of course be used for other purposes, but a Custom NetCheck always returns a number as its result.

This number must be an integer, and represents the number of milliseconds it took to perform the check, and must be written to output by the Custom NetCheck, in order for SysOrb to find it. The format of the line containing this number, can be specified for each check.

If SysOrb did not locate this line in the output from the Custom NetCheck before it exits, the check is marked as giving no reply. If the check does not write the line, in ten seconds, plus the upper limit for the check, the check will be marked as timed out.

The Custom NetCheck is executed as stated in the configuration, with the name of the node to perform the check on, given as the first parameter.

# Comment lines start with a #
[NetCheck Name]
command=command to execute
result_pattern=([[:digit:]]+)
          

10.3. Custom AlertPaths

In addition to the built-in ways, that the SysOrb server can alert its users (Email, SMS, paging), you can also have SysOrb execute a script of your choice. This could be used to send SMS through a gateway of your provider, to put events into your help-desk system, to send an instant message, or whatever you can do through any command line utility.

The SysOrb server passes information about the alert to be sent exclusively through environment variables. Before instructing SysOrb to invoke the script, you probably want to debug it by running it on the command line with the environment variables manually set. You will find a list with descriptions of each of the variables at the end of this section.

In order to be able to set up the script to be invoked by SysOrb, you must have a running SysOrb server. Log into the web interface using an administrator account, and click the System Setup button. Then select Custom Alerts and click New type of Custom AlertPath. All you have to supply is a name of your choice for this type of custom alerts, and the command for running the script.

After registering the script with SysOrb. You can select any user, click Edit, and the you should see a new option called Add custom path. Try creating a path, and testing it by clickng Test next to the new path on the list.

10.4. Creating a new database

One can re-create a clean SysOrb database using the sysorb-createdb tool. This is required if one wishes to change the database block sizes, or if one wishes to run the database on raw disk devices (or partitions) rather than on a file system (on operating systems where this functionality is available).

The database creation tool will create two or three files, depending on chosen options. The files are:

The tool accepts a number of command line options, described blow:

A number of advanced settings can be specified in the "interactive" mode of the createdb tool. When using the tool in the standard non-interactive mode, good defaults are chosen. It should not usually be necessary for an administrator to specify these options manually, but there are certain situations where such flexibility is useful.

Most notably, when creating a database on "raw" devices (partitions or volumes, rather than in files on a file system), it is necessary to use the interactive mode in order to specify the individual device locations (as the database needs two or three locations, and if volumes or partitions are used, two or three distinct locations must be specified).

In interactive mode, the user will be prompted for each of the advanced settings in turn:

• Journal type: The meta database can use either an internal or an external journal. An external journal allows the administrator to place the journal on a smaller but faster storage device.

• Journal size: A too small journal will, sooner or later, cause the SysOrb Server to perform an emergency shutdown. It is absolutely vital, that the journal is not chosen too small. The default journal size is 8 Megabytes, which is sufficient. If the journal can be placed on a very fast storage device, it may be beneficial to raise the journal size somewhat. It is not possible to give hard numbers for this though - a busy metadatabase with the journal on a fast storage device, may see speed improvements from a 16 Megabyte journal. It is generally recommended to just go with the default size of 8 Megabytes though.

• Number of chains: The time series database relies on "phase chains" rather than a journal to guarantee consistency over unexpected system shutdowns. A number of chains is allocated - the database needs at least one chain as the "consistent" chain, and one as the "active" chain. Thus, the number of chains can not be set lower than two. Setting the number of chains higher does in theory not improve reliability - it does however give the operating system and hardware some amount of "slack" - the default is three chains.

• Block size: A uniform block size is used in both the time series database and the meta database. Meta data objects cannot span blocks in the database, therefore the block size must be large enough for the largest possible object. It is not recommended to set the block size lower than 4 kilobytes, although a minimum of 1 kilobyte is possible using the createdb tool. Both databases use 32-bit block indexing, and are therefore limited in size to approximately four billion blocks. A block size of 8 kilobytes thus results in a maximum database size (for each of the metadata and time series databases) of 32 terabytes. Increasing the block size further will raise this limit. The default block size is 8 kilobytes.

• Estimated number of checks: As a convenience, the createdb tool can - upon database creation - allocate space in the time series database for some given number of checks. This is only an initial allocation, and the database will be grown later as needed. The default of 1000 checks will result in a database of approximately one gigabyte in size. For small installations, use a smaller number. Again, the database will be grown as needed, anyone can put "10" here - which will make the creatdb run significantly faster.

The following will create a standard database with the default "admin" (password: "admtest") login in the directory /mnt/database/:

sysorb-createdb -d /mnt/database -f

The following will create a completely empty database:

sysorb-createdb -d /mnt/database -f -c

11.1. sysorb-exporter

The sysorb-exporter can be used to export a part of the SysOrb database to XML. Once the data is exported to XML, it can easily be manipulated and imported into SysOrb again, or it can be imported into other programs.

The syntax of the sysorb-exporter tool is:

sysorb-exporter [-h] [-s server] [-p port] [-d domain] -l login [-P password] [-f filename] [-e domain] [-i classes] [-I classes]

11.2. sysorb-importer

The sysorb-importer can import XML-data exported from the sysorb-exporter, or XML-data generated by scripts or programs, as long as they use the same format as the sysorb-exporter.

The syntax of the tool is:

sysorb-importer [-h] [-s server] [-p port] [-d domain] -l login [-P password] [-f filename] [-m]

11.3. Examples of how to use

In the following we will demonstrate how the importer and exporter can be used to automate the creation of nodes in SysOrb. These concepts can easily be expanded to allow automatic creation of other objects is SysOrb.

In this example we will assume that there exists a domain in the root-domain called Test, and in that domain a node called template is placed.

In order to export the contents of the Test domain, the command in the first line of the following example is used. The program will respond with something like the following lines.

$ sysorb-exporter -l admin -P admtest -e Test -i CheckGroup -f template.xml
Exporting database
Exporting domain Test.
Exporting statistical data (1.3266410235). Please wait.


Done

The above command will export a file called template.xml which will contain the following (note that there will be some differences between different exports):

<?xml version="1.0"?>
<Meta version="1.0" description="SysOrb exported database" timestamp="2004-04-13-T15:52:38">
</Meta><Object id="1.3266410236" type="Domain">
  <Property type="Enumeration(14)" name="downNotify" value="1"/>
  <Property type="String" name="label" value=""/>
  <Property type="String" name="name" value="Test"/>
  <Property type="Computed String" name="siblingName" value="Test"/>
  <Object id="1.3266410235" type="Node">
    <Property type="Boolean" name="acknowledgeAlerts" value="false"/>
    <Property type="Integer" name="alert" value="1000"/>
    <Property type="Integer" name="alertCeiling" value="1100"/>
    <Property type="Enumeration(12)" name="alertStrategy" value="1"/>
    <Property type="Unsigned Integer" name="checkinFrequency" value="30"/>
    <Property type="Integer" name="checkinScore" value="-5"/>
    <Property type="Enumeration(14)" name="downNotify" value="1"/>
    <Property type="String" name="label" value=""/>
    <Property type="Integer" name="missedCheckinScore" value="10"/>
    <Property type="String" name="name" value="template"/>
    <Property type="ObjectSet" name="nodeClasses" value=""/>
    <Property type="Computed String" name="siblingName" value="template"/>
    <Property type="String" name="snmpCommunity" value="public"/>
    <Property type="Enumeration(20)" name="snmpVersion" value="0"/>
    <Property type="Integer" name="warn" value="200"/>
    <Property type="Integer" name="warnCeiling" value="300"/>
  </Object>
</Object>

Before this file can be used to create new nodes in SysOrb, the name of the node must be changed. This is the property called name. Just change the value to something other than template. The following example shows the modified file, which can be used to create a node called New Node.

<?xml version="1.0"?>
<Meta version="1.0" description="SysOrb exported database" timestamp="2004-04-13-T15:52:38">
</Meta><Object id="1.3266410236" type="Domain">
  <Property type="Enumeration(14)" name="downNotify" value="1"/>
  <Property type="String" name="label" value=""/>
  <Property type="String" name="name" value="Test"/>
  <Property type="Computed String" name="siblingName" value="Test"/>
  <Object id="1.3266410235" type="Node">
    <Property type="Boolean" name="acknowledgeAlerts" value="false"/>
    <Property type="Integer" name="alert" value="1000"/>
    <Property type="Integer" name="alertCeiling" value="1100"/>
    <Property type="Enumeration(12)" name="alertStrategy" value="1"/>
    <Property type="Unsigned Integer" name="checkinFrequency" value="30"/>
    <Property type="Integer" name="checkinScore" value="-5"/>
    <Property type="Enumeration(14)" name="downNotify" value="1"/>
    <Property type="String" name="label" value=""/>
    <Property type="Integer" name="missedCheckinScore" value="10"/>
    <Property type="String" name="name" value="New Node"/>
    <Property type="ObjectSet" name="nodeClasses" value=""/>
    <Property type="Computed String" name="siblingName" value="template"/>
    <Property type="String" name="snmpCommunity" value="public"/>
    <Property type="Enumeration(20)" name="snmpVersion" value="0"/>
    <Property type="Integer" name="warn" value="200"/>
    <Property type="Integer" name="warnCeiling" value="300"/>
  </Object>
</Object>

Using the modified file it is possible to create a node called New Node in any domain on the SysOrb Server. To create the node in the domain called New Domain (must be created before the command is executed), use the following command:

$ sysorb-importer -l admin -P admtest -i "New Domain" -f template.xml
Importing database into domain 1.1004032985 and replacing it.
Importing configuration..                       Done

It is possible to expand on this to create domains, checks etc. from the command line. It is also possible to export the statistical data gathered by SysOrb if it must be processed by some other tool. However in this case sysorb-tool is a better solution, which is described in the next chapter.

12.1. The select command

select [-t timeformat | -u] [-b starttime] [-e endtime]

The select command allows you to extract statistical information about a specific check, or the incident log from a node, into a CSV (Comma Seperated Value) file.

12.2. The insert command

insert

The insert command reads a CSV file, and imports the data from that file, into a specific check in the SysOrb database.

The command takes no options, and it expects the timeformat of the CSV file to be either the default format outputted from select, or the format obtained when -u is used. The command will automatically determine which of the formats are used for the CSV file.

12.3. The listdomains command

listdomains [-o N | i | p | d ] [-r]

The listdomains command will list the sub-domains of the specified domain.

12.4. The listnodes command

listnodes [-o N | i | p | d | n ] [-r]

The listnodes command will list the nodes of the specified domain.

12.5. The listchecks command

listchecks [-o N | i | p | d | n | c ] [-r]

The listchecks command will list the checks of the specified node or domain.

12.6. The listactions command

listactions [-o N | i | p | d | n | c ] [-r]

The listactions command lists all the actions on a node or domain identified either by an ID, or by a path. Output is the same format as listdomains uses. If the command is run on a domain, all actions on nodes directly under the selected domain will be displayed. If a node is used, all the actions are displayed.

12.7. The listproperties command

listproperties {path-specification} [-a] [-t] {property-name}...

The listproperties command will list some or all of the properties of a Domain, Node or Check together with the value of said properties..

12.8. The update command

update {path-specification} {property-name=new-property-value}...

The update command will update one or more properties of a Domain, Node or Check, if necessary.

The commands arguments is a list of properties together with the new value of the property.

If you wish to alter the name of a domain, the parameter name="New Name" will change the name property of the specified domain to "New Name". When you use parameters that contains spaces, make sure that you quote according to the rules of your shell.

12.9. The resetscores command

resetscores {path-specification}

The resetscores command can be used to reset ScoreKeeper scores on a node or check.

12.10. The setdowntime command

setdowntime {path-specification} {interval} [-c]

Thesetdowntime command can be used to set unexpected downtime on a domain, a node or a check.

12.11. Understanding the CSV file-format

sysorb-tool has 3 different CSV formats, depending on which kind of check is selected.

The first line of each CSV file identifies the columns of the file. After this line, comes the real data from the check. Each line corresponds to one record in the SysOrb database. A record can contain several measurements. This is because SysOrb will "compress" older data, by combining several measurements into one record.

A measurement can be either good or bad. If it is good, it means that SysOrb actually have obtained a value from the check. If it is bad, it means that SysOrb was unable to obtain a value from the check. For example this is the case when SysOrb tries to perform a HTTP check, but cannot connect to the server.

12.12. Example scripts

In this section we will present two scripts which automate the extraction of all data in SysOrb (except Incident Logs) through the sysorb-tool.

One script is for bash, and should work with all Unix'es where bash is installed. The other script is for Windows.

#!/bin/bash

#
# Change these variables to match your setup.
#
SOTOOL="/usr/bin/sysorb-tool"
USERNAME=admin
PASSWORD=admtest
DOMAIN=.
SERVER=localhost

# This directory will be created by the script. If such a file or
# directory already exists, it will be deleted.
OUTPUTDIR=output

STDCMDLINE="${SOTOOL} -l ${USERNAME} -P ${PASSWORD} -s ${SERVER} -d ${DOMAIN}"


# Prepare the output directory.
if [ -e "$OUTPUTDIR" ]; then
    rm -rf "$OUTPUTDIR"
fi;

mkdir -p "$OUTPUTDIR"

# The outer loop extracts a list of all the nodes on the server.
$STDCMDLINE listnodes -r -o iN . | while read i; do

    # The id of the node is the characters before the first space
    NODEID=`echo $i | cut -d ' ' -f 1`

    # The name of the node is the rest of the characters. Remember to
    # translate /'es to _, as /'es are illegal in filenames.
    NODENAME=`echo $i | cut -d ' ' -f 2- | tr / _`

    echo "Exporting $NODENAME"

    # The inner loop extracts all the checks on one of the nodes
    $STDCMDLINE listchecks -o iN -i $NODEID | while read j; do
        
        # The check's id and the checks name, is extracted in the same 
        # way as the nodes.
        CHECKID=`echo $j | cut -d ' ' -f 1`
        CHECKNAME=`echo $j | cut -d ' ' -f 2- | tr / _`

        # Extract all data for the check. If there is only need for a
        # period of data, the -b and -e options to the select command
        # can be used, together with the unix date command.
        $STDCMDLINE -f "$OUTPUTDIR/$NODENAME - $CHECKNAME".csv select -i $CHECKID
    done;
done;

@ECHO off

REM The parameters to the sysorb-tool. The current one logs in as the user
REM admin with the password admtest in the domain . on the server localhost
SET params="-l admin -P admtest -d . -s localhost"

REM Change sotool to point to the path of the SysOrb tool.
SET sotool="%ProgramFiles%\SysOrb Server\sysorb-tool.exe"

REM Execute the sysorb-tool in order to extract the list of all the domains.
%sotool% %params% -f %tmp%\nodes.txt listnodes -r -o iN .

REM Now use the nodes.txt file as a parameter to the for loop

FOR /F "tokens=1*" %%i IN (%tmp%\nodes.txt) DO (
        REM echo Processing node %%j

        REM Extract a list of all checks present on the node
        %sotool% %params% -f %tmp%\%%i-checks.txt listchecks -o iN -i %%i

        REM If there are no checks on the node, the file will not be created.
        IF EXIST %tmp%\%%i-checks.txt (
                FOR /F "tokens=1*" %%k IN (%tmp%\%%i-checks.txt) DO (
                        ECHO Extracting data for %%l on %%j to file %%k.csv

                        REM Store the name of the check in the first line 
                        REM of the CSV file.
                        ECHO Node,CheckName > %%k.csv
                        ECHO %%j,%%l >> %%k.csv
        
                        REM Extract the data for the check.
                        %sotool% %params% select -i %%k >> %%k.csv
                )
                DEL /F %tmp%\%%i-checks.txt
        )
)

rem DEL /F %tmp%\nodes.txt

13.1. GD Graphics Library

Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000 by Cold Spring Harbor Laboratory. Funded under Grant P41-RR02188 by the National Institutes of Health.

Portions copyright 1996, 1997, 1998, 1999, 2000 by Boutell.Com, Inc.

Portions relating to GD2 format copyright 1999, 2000 Philip Warner.

Portions relating to PNG copyright 1999, 2000 Greg Roelofs.

Portions relating to libttf copyright 1999, 2000 John Ellson (ellson@lucent.com).

Portions relating to JPEG copyright 2000, Doug Becker and copyright (C) 1994-1998, Thomas G. Lane. This software is based in part on the work of the Independent JPEG Group.

Portions relating to WBMP copyright 2000 Maurice Szmurlo and Johan Van den Brande.

Permission has been granted to copy, distribute and modify gd in any context without fee, including a commercial application, provided that this notice is present in user-accessible supporting documentation.

This does not affect your ownership of the derived work itself, and the intent is to assure proper credit for the authors of gd, not to interfere with your productive use of gd. If you have questions, ask. "Derived works" includes all programs that utilize the library. Credit must be given in user-accessible documentation.

This software is provided "AS IS." The copyright holders disclaim all warranties, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with respect to this code and accompanying documentation.

Although their code does not appear in gd 1.8.4, the authors wish to thank David Koblas, David Rowley, and Hutchison Avenue Software Corporation for their prior contributions.

13.2. OpenSSL Library

14.1. Overview

From SysOrb version 4.2 a RESTfull API is shipped with SysOrb. The API allows integrating SysOrb with 3rd party services or extends its functionality. This chapter provides documentation of how to use SysOrb RESTfull API..

14.2. Getting Started

// uname is the user name
// upass is the user password
// udom is the user domain
var auth = btoa(uname + ":" + upass + ":" + udom); // build authentication string in Base64 encoding
var url = 'localhost:8080/token';
request = new XMLHttpRequest();
 
request.open('GET', url, true);
request.setRequestHeader('authorization', 'Basic ' + auth);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // Process XML to extract user domain id and access token
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// utoken is the access token
 
var api_url = 'localhost:8080/token';
request = new XMLHttpRequest();
 
request.open('DELETE', api_url, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // User signed off successfully
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// udom - is the Domain id which we want to get subdomains
// utoken - access token
 
//
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// Call domains function with udom parameter
request.open('GET', api_url + '/domains/' + udom, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // We got xml which contain a list of domains with their object id,
      // version and label, parse it.
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// udom - is the Domain id which we want to get subdomains with StatusInfo objects
// utoken - access token
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to StatusInfo function
var si_url = '/domains/' + udom + '/statusinfo';
 
// Call get statusinfo function with udom parameter
request.open('GET', api_url + si_url, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // We got xml which contain a list of domains with StatusInfo object,
      // parse it.
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// udom - is the Domain where we want to create a new one
// utoken - access token
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to template function
var template_url = '/domains/' + udom + '/template';
 
request.open('GET', api_url + template_url, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // We got xml which contain a list of editable properties,
      // parse it.
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// udom - is the Domain where we want to create a new one
// utoken - access token
// req_xml is xml that contain a list of properties with values
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to the function
var func_url = '/domains/' + udom;
 
request.open('POST', api_url + func_url, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
request.setRequestHeader('content-type', 'text/xml');
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 201) {
      // Domain was created, it's id is in the 'location' header
      // and version is in the 'content-version'
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(req_xml);

// domain_id - is the domain we want to edit
// version - current version of the domain
// utoken - access token
// req_xml is the xml that contain a list of properties we want to change
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to the function
var func_url = '/domains/' + domain_id;
 
request.open('PUT', api_url + func_url, true);
 
// Setup required headers
request.setRequestHeader('authorization', 'Basic ' + utoken);
request.setRequestHeader('content-version', version);
request.setRequestHeader('content-type', 'text/xml');
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // Domain was updated, the new version is in the 'content-version'header
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(req_xml);

// domain_id - is the domain we want to delete
// version - current version of the domain
// utoken - access token
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to the function
var func_url = '/domains/' + domain_id;
 
request.open('DELETE', api_url + func_url, true);
 
// Setup required headers
request.setRequestHeader('authorization', 'Basic ' + utoken);
request.setRequestHeader('content-version', version);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // Domain was deleted
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// udom - is the Domain id which we want to get Nodes
// utoken - access token
 
//
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// Call nodes function with udom parameter
request.open('GET', api_url + '/nodes/' + udom, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // We got xml which contain a list of nodes with their object id,
      // version and label, parse it.
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// udom - is the Domain where we want to create a new Node
// utoken - access token
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to template function
var template_url = '/nodes/' + udom + '/template';
 
request.open('GET', api_url + template_url, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // We got xml which contain a list of editable properties,
      // parse it.
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// udom - is the Domain where we want to create a new node
// utoken - access token
// req_xml is xml that contain a list of properties with values
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to the function
var func_url = '/nodes/' + udom;
 
request.open('POST', api_url + func_url, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
request.setRequestHeader('content-type', 'text/xml');
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 201) {
      // Node was created, it's id is in the 'location' header
      // and version is in the 'content-version'
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(req_xml);

// node_id - is the id of node we want to edit
// version - current version of the node
// utoken - access token
// req_xml is the xml that contain a list of properties we want to change
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to the function
var func_url = '/nodes/' + node_id;
 
request.open('PUT', api_url + func_url, true);
 
// Setup required headers
request.setRequestHeader('authorization', 'Basic ' + utoken);
request.setRequestHeader('content-version', version);
request.setRequestHeader('content-type', 'text/xml');
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // Node was updated, the new version is in the 'content-version' header
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(req_xml);

// node_id - is the id of node we want to delete
// version - current version of the node
// utoken - access token
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to the function
var func_url = '/nodes/' + domain_id;
 
request.open('DELETE', api_url + func_url, true);
 
// Setup required headers
request.setRequestHeader('authorization', 'Basic ' + utoken);
request.setRequestHeader('content-version', version);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // Node was deleted
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// node_id - entry point to start traversing the checks tree
// utoken - access token
 
//
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
request.open('GET', api_url + '/subtree/' + node_id, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // We got xml which contain a list of checkgroup/check objects with their
      // object id, version and label
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// node_id - this function requires node id to apply filter
// utoken - access token
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// Notice that we don't specify filter - by default function returns all active checks
request.open('GET', api_url + '/checks/' + node_id, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // We got xml which contain a list of active checks with CheckSummary
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// node_id - this function requires node id to apply filter
// utoken - access token
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// Get active ESXi checks that are in WARN state
var filter = '/type=esxichecks&status=warn';
request.open('GET', api_url + '/checks/' + node_id + filter, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // We got xml which contain a list of active checks with ScoreInfo
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// check_grp - notice that we need to pass a Network Checks group.
// utoken - access token
// sibling - is the sibling name of the check we want to get template.
// Use 'get /subtree' to get a full list of network checks with their SiblingNames
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to template function
var template_url = '/checks/' + check_grp + '/template/' + sibling;
 
request.open('GET', api_url + template_url, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // We got xml which contain a list of editable properties,
      // parse it.
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// id - parent check group id
// utoken - access token
// req_xml is xml that contain a list of properties with values
// sibling - is the sibling name of the check we want to create
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to the function
var func_url = '/checks/' + id + '/template/' + sibling;
 
request.open('POST', api_url + func_url, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
request.setRequestHeader('content-type', 'text/xml');
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 201) {
      // Check was created, it's id is in the 'location' header
      // and version is in the 'content-version'
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(req_xml);

// check_id - id of check we want to get a list of editable properties.
// utoken - access token
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to template function
var template_url = '/checks/' + check_id + '/template/';
 
request.open('GET', api_url + template_url, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // We got xml which contain a list of editable properties,
      // parse it.
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// check_id - is the id of check we want to edit
// version - current version of the check
// utoken - access token
// req_xml is the xml that contain a list of properties we want to change
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to the function
var func_url = '/checks/' + check_id;
 
request.open('PUT', api_url + func_url, true);
 
// Setup required headers
request.setRequestHeader('authorization', 'Basic ' + utoken);
request.setRequestHeader('content-version', version);
request.setRequestHeader('content-type', 'text/xml');
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // Check was updated, the new version is in the 'content-version' header
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(req_xml);

// check_id - check we want to delete
// version - current version of the check
// utoken - access token
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to the function
var func_url = '/checks/' + check_id;
 
request.open('DELETE', api_url + func_url, true);
 
// Setup required headers
request.setRequestHeader('authorization', 'Basic ' + utoken);
request.setRequestHeader('content-version', version);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // Check was deleted
      ....
    } else if (request.status == 202) {
      // Check was made inactive - new version is in content-version header
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// domain_id - Domain we want to get a Users list
// utoken - access token
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
request.open('GET', api_url + '/users/' + domain_id, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // We got xml which contain a list of users registered in the domain
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// udom - is the Domain where we want to create a new User
// utoken - access token
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to template function
var template_url = '/users/' + udom + '/template';
 
request.open('GET', api_url + template_url, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // We got xml which contain a list of editable properties,
      // parse it.
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// udom - is the Domain where we want to create a new user
// utoken - access token
// req_xml is xml that contain a list of properties with values
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to the function
var func_url = '/users/' + udom;
 
request.open('POST', api_url + func_url, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
request.setRequestHeader('content-type', 'text/xml');
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 201) {
      // USer was created, it's id is in the 'location' header
      // and version is in the 'content-version'
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(req_xml);

// user_id - is the id of user we want to edit
// version - current version of the user
// utoken - access token
// req_xml is the xml that contain a list of properties we want to change
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to the function
var func_url = '/users/' + node_id;
 
request.open('PUT', api_url + func_url, true);
 
// Setup required headers
request.setRequestHeader('authorization', 'Basic ' + utoken);
request.setRequestHeader('content-version', version);
request.setRequestHeader('content-type', 'text/xml');
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // User was updated, the new version is in the 'content-version' header
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(req_xml);

// user_id - is the id of user we want to delete
// version - current version of the user
// utoken - access token
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
// URL to the function
var func_url = '/users/' + domain_id;
 
request.open('DELETE', api_url + func_url, true);
 
// Setup required headers
request.setRequestHeader('authorization', 'Basic ' + utoken);
request.setRequestHeader('content-version', version);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // User was deleted
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

// id - opject id want to get a list of properties
// utoken - access token
 
var api_url = 'localhost:8080';
request = new XMLHttpRequest();
 
request.open('GET', api_url + '/objects/' + id, true);
request.setRequestHeader('authorization', 'Basic ' + utoken);
 
request.onreadystatechange = function() {
  if (request.readyState == 4) {
    if (request.status == 200) {
      // We got xml which contain a list of properties of the object
      ....
    }
    else {
      // Handle errors
      ....
    }
  }
};
 
request.send(null);

14.3. Reference

authorization: Basic encodeBase64(uname:upass:.)

element authenticated {
 element domain { text }
 & element user { text }
 & element token { text }
}

element domains {
 element object {
  element class { test }
  & element id { text }
  & element version { text }
  & element treelabel { text }
 }*
}

element domains {
 element object {
  element class { test }
  & element id { text }
  & element version { text }
  & element treelabel { text }
  & element infourl { text }
  & element statusinfo {
  element property {
    element name { text }
    & element value { text }
   }*
  }
 }*
}

element alertlist {
  element alerts {
    element domain {
      element id { text }
      & element label { text }
      & element comment { text } ?
      & element infourl { text } ?
      & element node {
        element id { text }
        & element label { text }
        & element comment { text } ?
        & element infourl { text } ?
        & element status { text } ?
        & element check {
          element id { text }
          & element label { text }
          & element comment { text } ?
          & element infourl { text } ?
          & element status { text }
        }*
      }*
    }*
  }
  & element warnings {
    element domain {
      element id { text }
      & element label { text }
      & element comment { text } ?
      & element infourl { text } ?
      & element node {
        element id { text }
        & element label { text }
        & element comment { text } ?
        & element infourl { text } ?
        & element status { text } ?
        & element check {
          element id { text }
          & element label { text }
          & element comment { text } ?
          & element infourl { text } ?
          & element status { text }
        }*
      }*
    }*
  }
  & element downtime {
    element domain {
      element id { text }
      & element label { text }
      & element comment { text } ?
      & element infourl { text } ?
      & element node {
        element id { text }
        & element label { text }
        & element comment { text } ?
        & element infourl { text } ?
        & element status { text } ?
        & element check {
          element id { text }
          & element label { text }
          & element comment { text } ?
          & element infourl { text } ?
          & element status { text }
        }*
      }*
    }*
  }
}

element template {
  element class { text}
  & element property {
    element name { text }
    & element value { text }
    & element type { text }
 }*
}

element class { text }
& element property {
  element name { text }
  & element value { text }
}*

element class { text }
& element property {
  element name { text }
  & element value { text }
}*

element nodes {
 element object {
  element class { test }
  & element id { text }
  & element version { text }
  & element treelabel { text }
 }*
}

element nodes {
  element object {
    element class { test }
    & element id { text }
    & element version { text }
    & element treelabel { text }
    & element infourl { text }
    & element object {
      element class { text }
      & element property {
        element name { text }
        & element value { text }
      }*
    }
  }*
}

element template {
  element class { text}
  & element property {
    element name { text }
    & element value { text }
    & element type { text }
  }*
}

element class { text }
& element property {
  element name { text }
  & element value { text }
}*

element class { text }
& element property {
  element name { text }
  & element value { text }
}*

element object {
  element class { text }
  & element id { text }
  & element version { text}
  & element property {
    element name { text }
    & element value { text }
    & element type { text }
  }*
}

element parents {
  element object {
    element class { text }
    & element id { text }
    & element version { text}
    & element treelabel { text }
  }*
}

element scoreinfo {
  element class { text }
  element property {
    element name { text }
    & element value { text }
  }*
}

element statusinfo {
  element class { text }
  element property {
    element name { text }
    & element value { text }
  }*
}

element nodesummary {
  element class { text }
  element property {
    element name { text }
    & element value { text }
  }*
}

element objects {
  element object {
    element class { text }
    & element id { text }
    & element version { text}
    & element treelabel { text }
    & element siblingname { text } ?
    & element active { bool } ?
  }*
}

element checksummary {
  element class { text }
  & element property {
     element name { text }
     & element value { text }
  }*
}

element timeseries {
  element timestart { timestamp }
  & element timeend { timestamp }
  & element limit { integer }
  & element offset { integer }
}

element timeseries {
  element type { text }
  & element datainterval {
    element timestart { timestamp }
    & element timeend { timestamp }
    & element ngood { integer }
    & element nbad { integer }
    & element min { float }
    & element avg { float }
    & element max { float }
  }*
}

element timeseries {
  element type { text }
  & element datainterval {
    element timestart { timestamp }
    & element timeend { timestamp }
    & element ngood { integer }
    & element nbad { integer }
    & element mask { integer }
  }*
}

element timeseries {
  element type { text }
  & element datainterval {
    element time { timestamp }
    & element severity { integer }
    & element message { text }
  }*
}

element checks {
  element object {
    element class { text }
    & element id { text }
    & element version { text }
    & element treelabel { text }
    & element group { text }
    & element checksummary {
      element class { text }
      & element property {
        element name { text }
        & element value { text }
      }*
    }
  }*
}

element checks {
  element object {
    element class { text }
    & element id { text }
    & element version { text }
    & element treelabel { text }
    & element group { text }
    & element checksummary {
      element class { text }
      & element property {
        element name { text }
        & element value { text }
      }*
    }
  }*
}

element checks {
  element object {
    element class { text }
    & element id { text }
    & element version { text }
    & element treelabel { text }
    & element group { text }
    & element scoreinfo {
      element class { text }
      & element property {
        element name { text }
        & element value { text }
      }*
    }
  }*
}

element template {
  element class { text}
  & element property {
    element name { text }
    & element value { text }
    & element type { text }
 }*
}

element class { text }
& element property {
  element name { text }
  & element value { text }
}*

element class { text }
& element property {
  element name { text }
  & element value { text }
}*

element users {
  element object {
    element class { text }
    & element id { text }
    & element version { text}
    & element name { text }
  }*
}

element template {
  element class { text}
  & element property {
    element name { text }
    & element value { text }
    & element type { text }
  }*
}

element class { text }
& element property {
  element name { text }
  & element value { text }
}*

element class { text }
& element property {
  element name { text }
  & element value { text }
}*

element enum {
 element enumvalue {
  element text { text }
  & element value { uint }
 }*
}

element alertpaths {
  element object {
    element class { text }
    & element id { text }
    & element version { text}
    & element name { text }
  }*
}

element alertpaths {
                element template {
  element class { text}
  & element property {
    element name { text }
    & element value { text }
    & element type { text }
  }*
}*
}

element class { text }
& element property {
  element name { text }
  & element value { text }
}*

element class { text }
& element property {
  element name { text }
  & element value { text }
}*

element alertgroups {
  element object {
    element class { text }
    & element id { text }
    & element version { text}
    & element name { text }
  }*
}

                  element alertgroups {
                  element template {
                  element class { text}
                  & element property {
    element name { text }
    & element value { text }
    & element type { text }
  }*
}*
}

element class { text }
& element property {
  element name { text }
  & element value { text }
}*

element class { text }
& element property {
  element name { text }
  & element value { text }
}*