REST API
A REST API is provided with Opsview Monitor that you can use to interact with Opsview Monitor from either the command line on the Orchestrator server or from another system (for example, if you need to pull data into your own portal).
The API is covered in our documentation, but here are some examples of its use, all of which are based upon the command line tool provided on the Orchestrator server.
Basic command line use Copied
The command and necessary minimum options required are:
$ opsview_rest --username=$USERNAME --password=$PASSWORD <URI>
The command ‘opsview_rest ’ is available within the directory /opt/opsview/coreutils/bin so either run the command as the opsview user or add this directory to your PATH.
Using this, the following command would give you basic information about your system:
$ opsview_rest --username=$USERNAME --password=$PASSWORD GET info
{'uuid' => '5529AC1E-048A-11E5-B6D1-E02AB995B4E0','hosts_limit' => '1000','opsview_edition' => 'commercial','opsview_build' => '5.0.0.26912','server_timezone_offset' => '3600','server_timezone' => 'Europe/London','opsview_version' => '5.0.0'}
As can be seen from the above, the output is a bit messy for interactive use, but it is fine for parsing from a script. To make it easier for us to read what is going on, add the option ‘–pretty’:
$ opsview_rest --username=$USERNAME --password=$PASSWORD --pretty GET info
{
hosts_limit => 1000,
opsview_build => "5.0.0.26912",
opsview_edition => "commercial",
opsview_version => "5.0.0",
server_timezone => "Europe/London",
server_timezone_offset => 3600,
uuid => "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
}
If this is going to be used in a script then hard-coding the username and password would be a security risk. Instead, on the first invocation we can save a security token and from then on just use that token along with the username in the script:
$ opsview_rest --username=$USERNAME --password=$PASSWORD --pretty --token-file=$HOME/.ov_token GET info
{
hosts_limit => 1000,
opsview_build => "5.0.0.26912",
opsview_edition => "commercial",
opsview_version => "5.0.0",
server_timezone => "Europe/London",
server_timezone_offset => 3600,
uuid => "5529AC1E-048A-11E5-B6D1-E02AB995B4E0",
}
$ ls -la $HOME/.ov_token
-rw------- 1 user group 40 Oct 7 14:58 /home/user/.ov_token
$ opsview_rest --username=$USERNAME --token-file=$HOME/.ov_token --pretty GET info
{
hosts_limit => 1000,
opsview_build => "5.0.0.26912",
opsview_edition => "commercial",
opsview_version => "5.0.0",
server_timezone => "Europe/London",
server_timezone_offset => 3600,
uuid => "5529AC1E-048A-11E5-B6D1-E02AB995B4E0",
}
If the token is not used for 1 hours then it will expire and a new one must be generated.
Performing a reload Copied
A reload can be initiated by running:
$ opsview_rest --username=$USERNAME --token-file=$HOME/.ov_token --pretty POST reload
{
auditlog_entries => 0,
average_duration => 10,
configuration_status => "uptodate",
lastupdated => 1444227602,
messages => [],
server_status => 0,
}
The command will return when the reload is complete; the Opsview Monitor User Interface will also reflect the reload is happening. The *server_status *in the output returns ‘0’ when the reload has completed successfully, or any error messages in the messages entry.
Creating a Host Copied
Some REST API commands require extra data to work, for example when creating a host. For this example, we will create a file containing the minimum amount of configuration required:
Create the file /tmp/host.json containing:
{
"object" => {
"name" => "test_host",
"ip" => "123.123.123.123",
}
}
Below is a sample command with partial output:
$ opsview_rest --username=$USERNAME --token-file=$HOME/.ov_token --pretty --content-file=/tmp/host.json POST config/host
{
object => {
id => 24,
ip => "123.123.123.123",
name => "test_host",
.....
},
}
Any fields we have not specified will take the default value, the same as if the Host creation page in the Opsview Monitor User Interface were used. The returned information shows how the configuration was applied along with the Host id - this will be required when we update the host.
Reading through the docs for configuration API calls shows the following:
GET- retrieve either an object information or a list of objects.PUT- update. Will also create if the object does not currently exist. Will return the object after update.POST- create when POSTed to an objecttype URL, clone when POSTed to an object URL. However, creations will update if the object already exists. Will return the object after creation.DELETE- delete object. Will return a hash with response{'success':1}
so as this is a new Host we need to use POST (to create) rather than PUSH (to update).
Amending a Host Copied
The easiest way to amend a Host (or any other object) is to fetch the current configuration into a file, amend the file, then upload that back into Opsview Monitor.
The REST API works on ID’s for all objects, so we need to search to get the right object before we can fetch the configuration; here is how we do it for our previously created host:
$ opsview_rest --username=$USERNAME --token-file=$HOME/.ov_token --pretty GET
'/rest/config/host?json_filter={"name":{"=":"test_host"}}'
> /tmp/hostname.json
The output from the command is captured directly into a file (/tmp/hostname.json) - we can then edit this file as necessary. To upload the configuration we need to make a note of the value of ‘id’ in the file - in my case it is:
id => 24,
which is the same as the result we had when we first created the entry.
$ opsview_rest --username=$USERNAME --token-file=$HOME/.ov_token --pretty --content-file=/tmp/hostname.json PUT config/host/24
Notice, in this case, we are using PUT (to update) rather than PUSH (to create or clone).
Summary Copied
As you can see from the above, the API is straight forward to use but it is also very powerful. Almost anything you can do in the Opsview Monitor User Interface, you can do on the command line, and more functionality is being added all the time.