Opsview has an API (Application Programmable Interface) that is accessible via a webservice on the master server. It is a secure way of getting status data, setting configuration and taking actions such as reloading.

The API allows you to create or delete hosts. You can also take actions in the status views such as enable/disable notifications at a hostgroup level, as well as getting status information for services and hostgroups.

There are 3 ways to access the APIs:

• via HTTP
• via command line
• via a custom perl script

The method of passing data is via XML.

Note: Configuration changes and actions (such as disabling notifications or scheduling downtime) via the API require ADMINACCESS. Status views are based on the logged in user permissions.

Currently, you can:

• create or delete host objects
• scheduling or disabling downtime for all hosts and services in a hostgroup (within the hierarchy)
• reload Opsview
• delete a monitoringserver
• get status information

You need a HTTP client that can POST or PUT and can set the content-type to text/xml.

These are the URLs that can be hit on your Opsview server:

You need to authenticate to Opsview before you can hit those URLs. You can either:

• add in the query login_username=XX&login_password=YY
• use a client that can save the session cookie from going to /login
• specify authentication via the XML
• include the authentication details in the HTML request headers (required for GET's)

Using the command line tool 'curl', for example, would take a form similar to:

curl -H 'Content-Type: text/xml' -d @post.xml http://opsviewserver/api

In this case the username and password would have to be provided within <authentication> tags in the post.xml file.

The executable is opsview_api. The syntax for this command is:

opsview_api -f file.xml

You can specify ”-” as the file.xml and it will use stdin.

The script needs to be run as the nagios user. This is useful if you want to ssh to the Opsview server in a batch job.

For authentication, it is best to add the credentials into the XML file.

When fetching status information the format is

opsview_api -f file.xml GET api/status/service
opsview_api -f file.xml GET api/status/hostgroup

Again, the authentication details should be supplied via the xml file.

To fetch information on specific groups you can either use the ID number (as per the web UI URL) or by name

opsview_api -f file.xml GET "api/status/hostgroup?by_name=Monitoring Servers"
opsview_api -f file.xml GET api/status/hostgroup/5

These details are for perl, but other languages should work in a similar way.

The following script can be used as a base for getting status information. Note, for status requests the user referenced should be a 'view all, change none' or 'view some, change none' user.

#!/usr/bin/perl
use strict;
use warnings;
use HTTP::Request;
use LWP::UserAgent;
use XML::Simple;
my $user_agent = LWP::UserAgent->new;
my $html_request = HTTP::Request->new( GET => 'http://localhost/api/status/service' );
$html_request->header( 'Content-Type' => 'text/xml' );
$html_request->header( 'X-Username' => 'view_all_change_none' );
$html_request->header( 'X-Password' => 'password' );
my $html_response=$user_agent->request($html_request);
my $xml_output_ref = XMLin( $html_response->content );

All status information is now held within the $xml_output_ref reference.

The input XML data is in this form:

<opsview>
 <authentication>
  <username>admin</username>
  <password>initial</password>
 </authentication>
 <host action="create">
  <name>host</name>
  <ip>10.10.10.10</ip>
  <check_command><name>ping</name></check_command>
  <hostgroup><id>2</id></hostgroup>
  <icon><name>LOGO - Opsview</name></icon>
 </host>
</opsview>

The authentication section is optional.

Note * foreign references, such as check_command or hostgroup, can be referenced by name or by id

• hostgroups must be a “leaf” hostgroup, ie, at the tips of the hostgroup hierarchy
• multiple references, such as host templates or servicechecks, can be nulled by having empty elements

Only a single action can be taken in each request. If you have a number of actions you want to do, say, create 10 hosts, you will need to invoke a new request each time. This allows you to handle errors via your batch program.

There's a simple way to create a host - just use the clone element:

<opsview>
 <host action="create">
  <clone><name>otherhost</name></clone>
  <name>newhostname</name>
 </host>
</opsview>

All non specified attributes of the host will be copied from the clone.

An example host:

<opsview>
  <host action="create">
    <name>opsviewdev1</name>
    <alias>A description</alias>
    <check_command>
      <id>ping</id>
    </check_command>
    <hostgroup>
      <name>production</name>
    </hostgroup>
    <hosttemplates>
      <hosttemplate><name>Base Unix</name></hosttemplate>
      <hosttemplate><name>Base Network</name></hosttemplate>
    </hosttemplates>
    <icon>
      <name>LOGO - 3com</name>
    </icon>
    <ip>opsviewdev1.opsview.org</ip>
    <keywords>
      <keyword><name>auto</name></keyword>
    </keywords>
    <monitored_by>
      <id>1</id>
    </monitored_by>
    <nmis_node_type>router</nmis_node_type>
    <notification_interval>60</notification_interval>
    <notification_options>u,d,r</notification_options>
    <notification_period>
      <id>1</id>
    </notification_period>
    <other_addresses></other_addresses>
    <parents>
    </parents>
    <servicechecks>
      <servicecheck>
        <id>6</id>
      </servicecheck>
      <servicecheck>
        <id>22</id>
      </servicecheck>
      <servicecheck>
        <id>29</id>
      </servicecheck>
    </servicechecks>
    <snmp_community></snmp_community>
    <snmp_version></snmp_version>
    <snmptrap_tracing></snmptrap_tracing>
    <snmpv3_authpassword></snmpv3_authpassword>
    <snmpv3_privpassword></snmpv3_privpassword>
    <snmpv3_username></snmpv3_username>
    <use_nmis>1</use_nmis>
    <use_mrtg>1</use_mrtg>
  </host>
</opsview>

See the schema for the complete list of attributes.

Note: In 3.7.1, we introduced the use_mrtg attribute and deprecated the use of the performancemonitors attribute.

To delete a host, use this XML:

<opsview>
 <host action="delete" by_id="35"/>
</opsview>

Or you can choose a host by name:

<opsview>
 <host action="delete" by_name="hostname"/>
</opsview>

To disable notifications, use this XML:

<opsview>
 <hostgroup action="change" by_name="hostgroupname">
  <notifications>disable</notifications>
 </hostgroup>
</opsview>

You can specify by_id instead of by_name.

Note: Since hostgroup names within the hierarchy are not necessarily unique, all hostgroups of that name will have their notifications disabled.

You can enable notifications in the expected way.

Downtime can only be set up by users with full administrative rights.

To disable all scheduled downtime for a hostgroup, use this XML:

<opsview>
 <hostgroup action="change" by_name="hostgroupname">
  <downtime>disable</downtime>
 </hostgroup>
</opsview>

You can specify by_id instead of by_name.

Note: Since hostgroup names within the hierarchy are not necessarily unique, all hostgroups of that name will have their notifications disabled.

To set up scheduled downtime for a hostgroup, use the following XML:

<opsview>
 <hostgroup action="change" by_name="hostgroupname">
  <downtime
   start="start date and time"
   end="end date and time"
   comment="comment about the downtime"
  >enable</downtime>
 </hostgroup>
</opsview>

For information on formats, look here.

To request a reload, use this XML:

<opsview>
 <system action="reload"/>
</opsview>

The request will not finish until the reload has completed. The returned XML will be OK if the reload was successful or FAILED if there was a fatal error. You can also get a RETRY status, which means that another reload is in progress.

Note: If using HTTP to make this request, there is possibly a timeout at Apache if the reload takes a long time to complete.

The URL's given below fetch all status detail for the given item. To limit to specific states, append the following parameters

i.e. to see all unhandled services in a critical state, use the URL

api/status/service?state=2&filter=unhandled

To fetch data about all hostgroups, use

opsview_api -f auth.xml GET api/status/hostgroup

Specific hostgroup information can be fetched by appending the hostgroup ID onto the path

opsview_api -f auth.xml GET api/status/hostgroup/2

Note: the auth.xml contains just the username and password for authentication; no other XML is required in the file.

To fetch data about all services, use

opsview_api -f auth.xml GET api/status/service

Note: the auth.xml contains just the username and password for authentication; no other XML is required in the file.

The schema for the input data is on http://opsviewserver.example.com/xml/opsview.rng (in RELAX NG format).

If you are having problems, please check this file as this documentation may be slightly out of sync with the schema.

Responses will come back with an XML to show the status including any detailed text about the status. An appropriate return code will come back too: a HTTP query will return 200 for success; the command line script will return 0.

The response XML will be in the form:

<opsview>
 <result>
  <detail>Text</detail>
  <status>STATUS-CODE</status>
 </result>
</opsview>

Valid status codes are:

• OPTIONS-ERROR - invoked with wrong options either on command line or via HTTP
• XML-ERROR - the XML is not well formed
• XML-INVALID - the XML did not pass the schema validation
• FAILED - the action failed. See detail for more information
• RETRY - a temporary error occurred - try again later. See detail for more information
• WARNING - the action succeeded with warnings. See detail for more information
• OK - the action succeeded

Note: The response from a reload request could have more than one detail section.