kea/src/bin/stats/b10-stats-httpd.xml

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	       [<!ENTITY mdash "&#8212;">]>
<!--
 - Copyright (C) 2011  Internet Systems Consortium, Inc. ("ISC")
 -
 - Permission to use, copy, modify, and/or distribute this software for any
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 -
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
-->

<refentry>

  <refentryinfo>
    <date>Mar 8, 2011</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle>b10-stats-httpd</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo>BIND10</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>b10-stats-httpd</refname>
    <refpurpose>BIND 10 HTTP server for HTTP/XML interface of statistics</refpurpose>
  </refnamediv>

  <docinfo>
    <copyright>
      <year>2011</year>
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
  </docinfo>

  <refsynopsisdiv>
    <cmdsynopsis>      <command>b10-stats-httpd</command>
      <arg><option>-v</option></arg>|<arg><option>--verbose</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para>
      <command>b10-stats-httpd</command> is a standalone HTTP server. It is
      intended for HTTP/XML interface for statistics module. This server
      process runs as a process separated from the process of the BIND 10 Stats
      daemon (<command>b10-stats</command>). The server is initially executed
      by the BIND 10 boss process (<command>bind10</command>) and finally
      exited by it.  The server is intended to be requested by HTTP clients
      like web browsers and third-party modules. When the server is requested,
      it requests BIND 10 statistics data to <command>b10-stats</command>,
      and <command>b10-stats</command> sends the data to the server in Python
      dictionary format and the server converts it into XML format. The server
      sends it to the HTTP client. The server can send three types of document,
      which are XML (Extensible Markup Language), XSD(XML Schema definition)
      and XSL(Extensible Stylesheet Language). The XML document is the
      statistics data of BIND 10, The XSD document is the data schema of it,
      and The XSL document is the style sheet to be showed for the web
      browsers. Please see the manual and the spec file
      of <command>b10-stats</command> for more details about the items of BIND
      10 statistics. The server uses CC session in communication
      with <command>b10-stats</command>. CC session is provided
      by <command>b10-msgq</command> which is started
      by <command>bind10</command> in advance. The server is implemented by
      HTTP-server libraries included in Python 3. The parameter of the server
      is a list of pairs of the listening address and the port number specified
      in the spec file of it. The server obtains the configuration from the
      config manager (<command>b10-cfgmgr</command>) in runtime. Please see
      below for more details about this spec file and configuration of the
      server.
    </para>
  </refsect1>

  <refsect1>
    <title>OPTIONS</title>
    <para>The arguments are as follows:</para>
    <variablelist>
      <varlistentry>
        <term><option>-v</option>, <option>--verbose</option></term>
        <listitem>
	  <para>
          <command>b10-stats-httpd</command> switches to verbose mode and sends
          verbose messages to STDOUT.
	  </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>FILES</title>
    <para>
      <filename>/usr/local/share/bind10-devel/stats-httpd.spec</filename>
      &mdash; the spec file of <command>b10-stats-httpd</command>. This file
      contains configurable settings
      of <command>b10-stats-httpd</command>. This setting can be configured in
      runtime via
      <refentrytitle>bindctl</refentrytitle><manvolnum>1</manvolnum>. Please
      see the manual
      of <refentrytitle>bindctl</refentrytitle><manvolnum>1</manvolnum> about
      how to configure the settings.
    </para>
    <para>
      <filename>/usr/local/share/bind10-devel/stats-httpd-xml.tpl</filename>
      &mdash; the template file of XML document.
    </para>
    <para>
      <filename>/usr/local/share/bind10-devel/stats-httpd-xsd.tpl</filename>
      &mdash; the template file of XSD document.
    </para>
    <para>
      <filename>/usr/local/share/bind10-devel/stats-httpd-xsl.tpl</filename>
      &mdash; the template file of XSL document.
    </para>
  </refsect1>

  <refsect1>
    <title>CONFIGURATION AND COMMANDS</title>
    <para>
      The configurable setting in 
      <filename>stats-httpd.spec</filename> is:
    </para>
    <variablelist>
      <varlistentry>
        <term><varname>listen_on</varname></term>
        <listitem>
	  <para>
      	    a list of pairs of address and port for
	    <command>b10-stats-httpd</command> to listen HTTP requests on. The
	    pair is consist of the <varname>address</varname> string
	    and <varname>port</varname> number. The default setting is the list
	    of address 127.0.0.1 port 8000. If the server is started by the
	    default setting being left, for example, the URL for XML document
	    is http://127.0.0.1:8000/bind10/statistics/xml. And also IPv6
	    addresses can be configured and they works in the runtime
	    environment for dual stack.
	  </para>
        </listitem>
      </varlistentry>
    </variablelist>
    <para>
      The configuration commands in <filename>stats-httpd.spec</filename> are:
    </para>
    <variablelist>
      <varlistentry>
        <term><command>status</command></term>
        <listitem>
	  <para>
	    shows the status of <command>b10-stats-httpd</command> with its
	    PID on the runtime machine.
	  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><command>shutdown</command></term>
        <listitem>
	  <para>
	    exits the <command>b10-stats-httpd</command> process. (Note that
	    the BIND 10 boss process will restart this service.)
	  </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>b10-stats</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>bindctl</refentrytitle><manvolnum>1</manvolnum>
      </citerefentry>,
      <citetitle>BIND 10 Guide</citetitle>.
    </para>
  </refsect1>

  <refsect1>
    <title>HISTORY</title>
    <para>
      <command>b10-stats-httpd</command> was designed and implemented by Naoki
      Kambe of JPRS in Mar 2011.
    </para>
  </refsect1>
</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->