Chapter 12. SysOrb Tool

Table of Contents
12.1. The select command
12.2. The insert command
12.3. The listdomains command
12.4. The listnodes command
12.5. The listchecks command
12.6. The listproperties command
12.7. The update command
12.8. Understanding the CSV file-format
12.9. Example scripts

The SysOrb Tool is provided in order to access the SysOrb database using a command line tool.

The syntax of the tool is:

sysorb-tool [-h] [-s server] [-p port] [-d domain] -l login [-P password] [-f filename] command [command-options] path | -i id

-h

Displays a text on how to use the tool

-s server

Instructs the utility which SysOrb server to connect to. Defaults to the local machine.

-p port

If you SysOrb server uses a non-default port, use this switch.

-d domain

Specifies the domain in which the user that is used for the login is placed.

-l login

The login name of the user.

-P password

The password for the login.

-f file

This option specifies the input or output file. If not specified standard in or out will be used, according to the command used.

The command argument determines the output of the program. Currently there are seven different commands available:

select

The select command is used for extracting statistical information about a check or the incident log from a node, and output it to a CSV file. It is possible to specify the time interval that should be exported. In this case the path argument is a path to a check.

insert

The insert command allows the user to insert data into a check. The data is read from an CSV file, in the same format used by the select command.

listdomains

listdomains is used to extract a list of domains. Which domains are listed are determined by the path, which must point to a domain. The command then lists all subdomains in this domains. This can also be done recursively, so the subdomains of the subdomains also are listed.

listnodes

listnodes will list the nodes located under the domain, specified by the path.

listchecks

listchecks will, if given a node as parameter, list all the checks on this node. If given a domain, all the checks on the nodes in the domain will be listed.

listproperties

listproperties will list all the properties of the object identified by the path. This can be both Domains, Nodes and Checks.

update

update will update the value of one or more properties in the object identified by the path.

The path is a string identifying either a domain, a node or a check. If the path identifies a domain, the path only consists of one item. This is a '.' seperated list of the domain names, leading to the domain. So a path to the 'Routers' domain located in the 'Backbone' domain would be 'Backbone.Routers'.

If the path identifies a node, it will consist of two parts seperated by a ','. The first path will identify the domain in which the node is located, in the same way as specifying a path to a domain. The second part is the node's name (not label) in SysOrb. I.e. a path to the node 'mainrouter' in teh 'Routers' subdomain would be 'Backbone.Routers,mainrouter'.

A third part is added when the path identifies a check. This part identifies the check for the SysOrb Server. However constructing thi part by hand is not easy, so the listchecks command should be used in order to obtain thie part of the path.

Instead of a path, the -i switch can be used. This switch allows you to give an ID to the domain/node/check instead of the path. The id's can be retrieved by the list commands.

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.

-t timeformat

Using this switch allows you to change the format of the time, when written to the CSV file. How to do this is documented in Section 12.1.1.

-u

Using this switch will format the time as seconds passed since '1970-01-01 00:00:00 GMT'. Note that only one of the -u and -t switches can be used at a time.

-b starttime

The earliest point in time, for which data should be extracted. This should be specified as either as the number of seconds passed since '1970-01-01 00:00:00 GMT', or as ISO time (YYYY-MM-DD-Thh:mm:ss). If -b is not given, the extraction will include the first data record, present in SysOrb.

-e endtime

The latest point in time, for which data should be extracted. The format of endtime is the same as for starttime for the -b switch.

12.1.1. How to specify the timeformat

If you have specific requirements as to how the time stamps should be formatted, the -t option allows you to customize the output.

The timeformat is a string, in which some special character sequences will be replaced with specific parts of the date.

The following sequences are supported (note that the specific output of some of these sequences will depend on the language and region setting of the node where sysorb-tool is executed):

%a

The abbreviated weekday name for the date.

%A

The un-abbreviated weekday name.

%b

The abbreviated month name for the date.

%B

The full month name.

%c

The preferred date and time format, according to the languange and region settings of the machine.

%d

The day of the month. (01-31).

%H

The hour on a 24-hour clock, as a number (00-23).

%I

The hour on a 12-hour clock, as a number (01-12).

%j

The day of the year as a number (001-366).

%m

The month as a number (01-12).

%M

The minute as a number (00-59).

%p

AM/PM for 12-hour clocks.

%S

The seconds as a number (00-61). The number of seconds can reach 61, in order to account for leap-seconds.

%U

The week number of the year (00-53). This will start the numbering with the first sunday as the first day of week 01.

%w

The weekday as a number (0-6). Sunday is 0.

%W

The week number of the year (00-53). This will start the numbering with the first monday as the first day of week 01.

%x

The preferred date format, according to the languange and region settings of the machine.

%X

The preferred time format, according to the languange and region settings of the machine.

%y

The year without the century as a number (00-99).

%Y

The year with the century as a number

%%

A '%' will be output.