REST API
A REST API is provided with Opsview Monitor, allowing you to interact with it either from the command line on the Orchestrator server or from another system (for example, to pull data into your own portal).
The API is covered in our documentation but here are some usage examples, all based on the command line tool provided on the Orchestrator server.
Note
For instructions on performing bulk changes to SNMP version settings, refer to the REST API documentation on Changing SNMP credentials in bulk.
Basic command line use Copied
The command and necessary minimum options required:
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 shown from the preceding command, the output is not well-formatted for interactive use, but it is suitable 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 hour, 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}
Since 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 IDs 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 the file /tmp/hostname.json, which can be edited as necessary. To upload the configuration, we need to make a note of the value of id in the file, such as the following:
id => 24
This 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
In this case, we are using PUT (to update) rather than PUSH (to create or clone).