[Reconnoiter-devel] [reconnoiter commit] r846 - in docs: . operation operation/wire

svn-commit at lists.omniti.com svn-commit at lists.omniti.com
Wed Sep 16 14:28:55 EDT 2009


Author: jesus
Date: 2009-09-16 14:28:55 -0400 (Wed, 16 Sep 2009)
New Revision: 846

Added:
   docs/operation/
   docs/operation/cli/
   docs/operation/noitd.xml
   docs/operation/wire/
   docs/operation/wire/rest.xml
Modified:
   docs/index.xml
Log:
information about operating reconnoiter, refs #39

Modified: docs/index.xml
===================================================================
--- docs/index.xml	2009-09-16 15:07:59 UTC (rev 845)
+++ docs/index.xml	2009-09-16 18:28:55 UTC (rev 846)
@@ -32,6 +32,10 @@
     <title>Configuration</title>
     &config.all;
   </part>
+  <part id="operation">
+    <title>Operation</title>
+    &operation.all;
+  </part>
   <part id="reference">
     <title>Reference</title>
     <reference id="exe">

Added: docs/operation/noitd.xml
===================================================================
--- docs/operation/noitd.xml	                        (rev 0)
+++ docs/operation/noitd.xml	2009-09-16 18:28:55 UTC (rev 846)
@@ -0,0 +1,38 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
+[
+  <!ENTITY % magic.fixup SYSTEM "http://labs.omniti.com/docbook/ent">
+  %magic.fixup;
+]>
+<chapter id="operation.noitd">
+  <title>Operating the noitd daemon</title>
+
+<para>
+Once <command>noitd</command> is configured and running, there
+are several methods of interacting with the service.  The operator
+can interactively manage the instance via the integrated command line
+console (accessible via telnet on the port of your choice) and
+programmatic access is available over the <command>noitd</command>
+wire protocol on port 43191.
+</para>
+
+<para>
+The wire protocol is a binary protocol that is leverage for
+inter-system communication.  While not entirely compliant with
+the HTTP specification, the protocol will give well formed HTTP
+responses to sessions that commence with the terms: "DELETE"
+"GET " "HEAD" "POST" "PUT ".
+</para>
+
+<section id="noitd.interactive.console">
+<title><command>noitd</command> Interactive Console</title>
+&operation.cli.all;
+</section>
+
+<section id="noitd.wire.protocol">
+<title><command>noitd</command> Wire Protocol</title>
+&operation.wire.all;
+</section>
+
+</chapter>

Added: docs/operation/wire/rest.xml
===================================================================
--- docs/operation/wire/rest.xml	                        (rev 0)
+++ docs/operation/wire/rest.xml	2009-09-16 18:28:55 UTC (rev 846)
@@ -0,0 +1,150 @@
+<?xml version="1.0"?>
+<section>
+<title>REST operation over HTTP</title>
+
+<para>
+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 <command>noitd</command>
+instance.
+</para>
+
+<section>
+<title>Manipulating Checks</title>
+
+<section>
+<title>/checks/show/</title>
+  <variablelist>
+    <varlistentry>
+      <term>method</term>
+      <listitem><code>GET</code></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>uri</term>
+      <listitem><code>/checks/show/&lt;path/&gt;&lt;checkid&gt;</code></listitem>
+    </varlistentry>
+  </variablelist>
+  <para>
+  This call returns an XML document describing the current configuration and
+  state of the specific check.  The <code>checkid</code> specified is located
+  under the optional <code>path</code>.  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.
+  </para>
+
+  <example>
+    <title>REST /checks/show XML output.</title>
+    <para>Output from an HTTP GET of <code>/checks/show/1b4e28ba-2fa1-11d2-883f-b9a761bde3aa</code></para>
+    <programlisting><![CDATA[
+<?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>
+    ]]></programlisting>
+  </example>
+</section>
+
+<section>
+<title>/checks/set/</title>
+  <variablelist>
+    <varlistentry>
+      <term>method</term>
+      <listitem><code>PUT</code></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>uri</term>
+      <listitem><code>/checks/set/&lt;path/&gt;&lt;checkid&gt;</code></listitem>
+    </varlistentry>
+  </variablelist>
+  <para>
+  This call accepts a document describing a check.  That check is
+  instantiated with the <code>checkid</code> specified in the URL.  If the
+  check exists, but is not under the provided optional <code>path</code> a
+  HTTP 403 code is returned.  If the check already exists under the specified
+  <code>path</code>, the check is updated to reflect the new configuration.
+  The <code>module</code> cannot be changed for existing checks.  All other
+  fields can be changed.  All fields are required except the
+  <code>disable</code> 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 <code>/check/show</code> REST command.
+  The input is as follows:
+  </para>
+
+  <example>
+    <title>REST /checks/set XML input.</title>
+    <programlisting><![CDATA[
+<?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>
+    ]]></programlisting>
+  </example>
+</section>
+<section>
+<title>/checks/delete/</title>
+  <variablelist>
+    <varlistentry>
+      <term>method</term>
+      <listitem><code>DELETE</code></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>uri</term>
+      <listitem><code>/checks/delete/&lt;path/&gt;&lt;checkid&gt;</code></listitem>
+    </varlistentry>
+  </variablelist>
+  <para>
+  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 <code>path</code>, 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.
+  </para>
+</section>
+
+</section>
+</section>



More information about the Reconnoiter-devel mailing list