6.2. noitd Wire Protocol
Prev  Chapter 6. Operating the noitd daemon  Next

6.2. noitd Wire Protocol

6.2.1. REST operation over HTTP

A variety of operational read and write operations are available over HTTP. The HTTP layer is only available over SSL (HTTPS), operates on the IANA assigned port number 43191. The SSL implementation of the wire protocol requires client certificates, so this REST mechansim is only available to HTTP clients that support both SSL and user-supplied client certificates. The client certificates must be signed by a certificate authority recognized by the noitd instance.

6.2.1.1. Manipulating Checks

6.2.1.1.1. /checks/show/
method
GET
uri
/checks/show/<path/><checkid>

This call returns an XML document describing the current configuration and state of the specific check. The checkid specified is located under the optional path. If the check exists, but it under another path, a HTTP 403 code is returned. If the check does not exist, a HTTP 404 code is returned.

Example 6.1. REST /checks/show XML output.

Output from an HTTP GET of /checks/show/1b4e28ba-2fa1-11d2-883f-b9a761bde3aa

<?xml version="1.0" encoding="utf8"?>
<check>
  <attributes>
    <uuid>1b4e28ba-2fa1-11d2-883f-b9a761bde3aa</uuid>
    <name>http</name>
    <module inherited="/dc1/web/@module">http</module>
    <target>8.8.38.5</target>
    <period inherited="/dc1/@period">60000</period>
    <timeout inherited="/dc1/@timeout">5000</timeout>
    <filterset inherited="/@filterset">default</filterset>
  </attributes>
  <config>
    <code>200</code>
    <url>https://labs.omniti.com/</url>
  </config>
  <state>
    <running>false</running>
    <killed>false</killed>
    <configured>true</configured>
    <disabled>false</disabled>
    <last_run now="1253124365.131">1253124339.270</last_run>
    <runtime>4.408</runtime>
    <availability>available</availability>
    <state>good</state>
    <status>code=200,rt=4.409s,bytes=8958</status>
    <metrics>
      <duration type="I">4408</duration>
      <code type="s">200</code>
      <bytes type="i">8958</bytes>
    </metrics>
  </state>
</check>
6.2.1.1.2. /checks/set/
method
PUT
uri
/checks/set/<path/><checkid>

This call accepts a document describing a check. That check is instantiated with the checkid specified in the URL. If the check exists, but is not under the provided optional path a HTTP 403 code is returned. If the check already exists under the specified path, the check is updated to reflect the new configuration. The module cannot be changed for existing checks. All other fields can be changed. All fields are required except the disable field; if disable is omitted, it will inherit the disable attribute from parents in the tree (use the default setting). On success, a HTTP 200 is returned and an XML documented that matches the format of the /check/show REST command. The input is as follows:

Example 6.2. REST /checks/set XML input.

<?xml version="1.0" encoding="utf8"?>
<check>
  <attributes>
    <name>http</name>
    <module>http</module>
    <target>8.8.38.5</target>
    <period>60000</period>
    <timeout>5000</timeout>
    <filterset>default</filterset>
  </attributes>
  <config>
    <code>200</code>
    <url>https://labs.omniti.com/</url>
  </config>
</check>
6.2.1.1.3. /checks/delete/
method
DELETE
uri
/checks/delete/<path/><checkid>

This call returns deletes the specified check. If the check does not exist, then a HTTP 404 code is returned. If the check exists, but is outside of the optional path, then a HTTP 403 code is returned. Otherwise, the specified check is removed from the system and a HTTP 200 is returned. Any response payload returned should be ignored by the client.

6.2.1.2. Manipulating Filters

6.2.1.2.1. /filters/show/
method
GET
uri
/filters/show/<path/><filterset>

This call returns an XML document describing the current configuration of the specified filterset. The filterset specified is located under the optional path. If the check exists, but it under another path, a HTTP 403 code is returned. If the check does not exist, a HTTP 404 code is returned.

Example 6.3. REST /filters/show XML output.

Output from an HTTP GET of /filters/show/default

<?xml version="1.0" encoding="utf8"?>
<filterset>
  <rule type="deny" module="^ping_icmp$" metric="^(?:minimum|maximum|count)$"/>
</filterset>
6.2.1.2.2. /filters/set/
method
PUT
uri
/filters/set/<path/><filterset>

This call accepts a document describing a filterset. That filterset is instantiated with the name filterset specified in the URL. If the filterset exists, but is not under the provided optional path a HTTP 403 code is returned. If the filterset already exists under the specified path, the filterset is replaced with the configuration submitted. On success, a HTTP 200 is returned and an XML documented that matches the format of the /check/show REST command. The input is as follows:

Example 6.4. REST /filtert/set XML input.

<?xml version="1.0" encoding="utf8"?>
<filterset>
  <rule type="deny" module="^ping_icmp$" metric="^(?:minimum|maximum|count)$"/>
</filterset>
6.2.1.2.3. /filters/delete/
method
DELETE
uri
/filters/delete/<path/><filterset>

This call returns deletes the specified filterset. If the filterset does not exist, then a HTTP 404 code is returned. If the filterset exists, but is outside of the optional path, then a HTTP 403 code is returned. Otherwise, the specified filterset is removed from the system and a HTTP 200 is returned. Any response payload returned should be ignored by the client.

Prev  Up  Next
Chapter 6. Operating the noitd daemon  Home  Part IV. Reference