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 eventually
      exited by it.  The server is intended to be server requests by HTTP
      clients like web browsers and third-party modules. When the server is
      asked, it requests BIND 10 statistics data or its schema from
      <command>b10-stats</command>, and it sends the data back 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. There is different URL for each document. But please note that
      you would be redirected to the URL of XML document if you request the URL
      of the root document. For example, you would be redirected to
      http://127.0.0.1:8000/bind10/statistics/xml if you request
      http://127.0.0.1:8000/. 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 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 argument is as follow:</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>
      <!--TODO: The filename should be computed from prefix-->
      &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>
      <!--TODO: The filename should be computed from prefix-->
      &mdash; the template file of XML document.
    </para>
    <para>
      <filename>/usr/local/share/bind10-devel/stats-httpd-xsd.tpl</filename>
      <!--TODO: The filename should be computed from prefix-->
      &mdash; the template file of XSD document.
    </para>
    <para>
      <filename>/usr/local/share/bind10-devel/stats-httpd-xsl.tpl</filename>
      <!--TODO: The filename should be computed from prefix-->
      &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 consists 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. You can change the settings
	    through <refentrytitle>bindctl</refentrytitle><manvolnum>8</manvolnum>.
	  </para>
        </listitem>
      </varlistentry>
    </variablelist>
    <para>
      The 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.
	  </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:
-->