Welcome to docs.opsview.com

Differences

This shows you the differences between two versions of the page.

opsview4.6:api [2014/09/09 12:19] (current)
Line 1: Line 1:
 +====== Overview ======
 +<note warning>You should be using the [[opsview4.6:restapi|REST API]] for scripting configuration changes or other integration, starting from Opsview 3.9.0</note>
 +
 +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 [[#input_xml_data|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.
 +
 +====== Supported functionality ======
 +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
 +
 +====== Invocations ======
 +
 +===== HTTP =====
 +
 +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:
 +|| **Verb**   || **Path**          || **Requires XML?** || **Action** ||
 +|| POST or PUT|| /api              || Y                 || Based on XML file ||
 +|| GET        || /api/status/...   || Y                 || Based on XML file ||
 +
 +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.
 +
 +===== Command line =====
 +The executable is opsview_api. The syntax for this command is:
 +<code>
 +opsview_api -f file.xml
 +</code>
 +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
 +<code>
 +opsview_api -f file.xml GET api/status/service
 +opsview_api -f file.xml GET api/status/hostgroup
 +</code>
 +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
 +<code>
 +opsview_api -f file.xml GET "api/status/hostgroup?by_name=Monitoring Servers"
 +opsview_api -f file.xml GET api/status/hostgroup/5
 +</code>
 +
 +===== Status via Custom perl script =====
 +
 +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.
 +<code>
 +#!/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 );
 +</code>
 +
 +All status information is now held within the ''$xml_output_ref'' reference.
 +
 +====== Input XML data ======
 +
 +===== General =====
 +
 +The input XML data is in this form:
 +
 +<code>
 +<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>
 +</code>
 +
 +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.
 +===== Creating a host =====
 +
 +There's a simple way to create a host - just use the clone element:
 +<code>
 +<opsview>
 + <host action="create">
 +  <clone><name>otherhost</name></clone>
 +  <name>newhostname</name>
 + </host>
 +</opsview>
 +</code>
 +
 +All non specified attributes of the host will be copied from the clone.
 +
 +An example host:
 +<code>
 +<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>
 +</code>
 +See the [[#schema|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.
 +
 +===== Deleting a host =====
 +
 +To delete a host, use this XML:
 +<code>
 +<opsview>
 + <host action="delete" by_id="35"/>
 +</opsview>
 +</code>
 +
 +Or you can choose a host by name:
 +<code>
 +<opsview>
 + <host action="delete" by_name="hostname"/>
 +</opsview>
 +</code>
 +
 +===== Disabling notifications for a hostgroup (in hierarchy) =====
 +
 +To disable notifications, use this XML:
 +<code>
 +<opsview>
 + <hostgroup action="change" by_name="hostgroupname">
 +  <notifications>disable</notifications>
 + </hostgroup>
 +</opsview>
 +</code>
 +
 +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.
 +
 +
 +
 +===== Scheduling Downtime for a hostgroup (in hierarchy) =====
 +
 +Downtime can only be set up by users with full administrative rights.
 +
 +To disable all scheduled downtime for a hostgroup, use this XML:
 +<code>
 +<opsview>
 + <hostgroup action="change" by_name="hostgroupname">
 +  <downtime>disable</downtime>
 + </hostgroup>
 +</opsview>
 +</code>
 +
 +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:
 +<code>
 +<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>
 +</code>
 +
 +For information on formats, look [[opsview4.6:downtime#format|here]].
 +
 +
 +===== Reload Opsview =====
 +To request a reload, use this XML:
 +<code>
 +<opsview>
 + <system action="reload"/>
 +</opsview>
 +</code>
 +
 +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.
 +===== Fetching status =====
 +
 +The URL's given below fetch all status detail for the given item.  To limit to specific states, append the following parameters
 +
 +^ Limit to ^ Parameter to append ^
 +| OK state | state=0 |
 +| WARNING state | state=1 |
 +| CRITICAL state | state=2 |
 +| UNKNOWN state | state=3 |
 +| Unhandled | filter=unhandled |
 +
 +i.e. to see all unhandled services in a critical state, use the URL
 +
 +api/status/service?state=2&filter=unhandled
 +==== Status of a hostgroup ====
 +
 +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.
 +
 +==== Status of services ====
 +
 +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.
 +
 +===== Schema =====
 +
 +The schema for the input data is on http://opsviewserver.example.com/xml/opsview.rng (in [[http://relaxng.org/|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 ======
 +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:
 +<code>
 +<opsview>
 + <result>
 +  <detail>Text</detail>
 +  <status>STATUS-CODE</status>
 + </result>
 +</opsview>
 +</code>
 +
 +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.
Navigation
Print/export
Toolbox