kea/src/bin/bind10/bind10.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) 2010  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>March 31, 2011</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle>bind10</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo>BIND10</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>bind10</refname>
    <refpurpose>BIND 10 boss process</refpurpose>
  </refnamediv>

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

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>bind10</command>
      <arg><option>-c <replaceable>config-filename</replaceable></option></arg>
      <arg><option>-m <replaceable>file</replaceable></option></arg>
      <arg><option>-n</option></arg>
      <arg><option>-p <replaceable>data_path</replaceable></option></arg>
      <arg><option>-u <replaceable>user</replaceable></option></arg>
      <arg><option>-v</option></arg>
      <arg><option>--brittle</option></arg>
      <arg><option>--cmdctl-port</option> <replaceable>port</replaceable></arg>
      <arg><option>--config-file</option> <replaceable>config-filename</replaceable></arg>
      <arg><option>--data-path</option> <replaceable>directory</replaceable></arg>
      <arg><option>--msgq-socket-file <replaceable>file</replaceable></option></arg>
      <arg><option>--no-cache</option></arg>
      <arg><option>--pid-file</option> <replaceable>filename</replaceable></arg>
      <arg><option>--pretty-name <replaceable>name</replaceable></option></arg>
      <arg><option>--user <replaceable>user</replaceable></option></arg>
      <arg><option>--verbose</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>

    <para>The <command>bind10</command> daemon starts up other
    BIND 10 required daemons.  It handles restarting of exiting
    programs and also the shutdown of all managed daemons.</para>

<!-- TODO: list what it starts here? -->

<!-- TODO
    <para>The configuration of the <command>bind10</command> daemon
    is defined in the TODO configuration file, as described in the
    <citerefentry><refentrytitle>TODO</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    manual page.</para>
-->

  </refsect1>

  <refsect1>
    <title>ARGUMENTS</title>

    <para>The arguments are as follows:</para>

    <variablelist>

      <varlistentry>
        <term>
          <option>--brittle</option>
        </term>
        <listitem>
          <para>
	    Shutdown if any of the child processes of
	    <command>bind10</command> exit.  This is intended to
	    help developers debug the server, and should not be
	    used in production.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-c</option> <replaceable>config-filename</replaceable>,
          <option>--config-file</option> <replaceable>config-filename</replaceable>
        </term>
        <listitem>
          <para>The configuration filename to use. Can be either absolute or
          relative to data path. In case it is absolute, value of data path is
          not considered.</para>
          <para>Defaults to b10-config.db.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>--cmdctl-port</option> <replaceable>port</replaceable>
        </term>
        <listitem>
	  <para>The <command>b10-cmdctl</command> daemon will listen
	    on this port.
	    (See
	    <refentrytitle>b10-cmdctl</refentrytitle><manvolnum>8</manvolnum>
            for the default.)
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>-p</option> <replaceable>directory</replaceable>,
          <option>--data-path</option> <replaceable>directory</replaceable>
        </term>
        <listitem>
          <para>The path where BIND 10 programs look for various data files.
          Currently only b10-cfgmgr uses it to locate the configuration file,
          but the usage might be extended for other programs and other types
          of files.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-m</option> <replaceable>file</replaceable>,
           <option>--msgq-socket-file</option> <replaceable>file</replaceable></term>

        <listitem>
          <para>The UNIX domain socket file for the
	    <citerefentry><refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum></citerefentry>
            daemon to use.
            The default is
            <filename>/usr/local/var/bind10-devel/msg_socket</filename>.
<!-- @localstatedir@/@PACKAGE_NAME@/msg_socket -->
           </para>
         </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-n</option>, <option>--no-cache</option></term>
        <listitem>
	  <para>Disables the hot-spot caching used by the
	    <citerefentry><refentrytitle>b10-auth</refentrytitle><manvolnum>8</manvolnum></citerefentry>
	  daemon.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-u</option> <replaceable>user</replaceable>, <option>--user</option> <replaceable>name</replaceable></term>
        <listitem>
          <para>The username for <command>bind10</command> to run as.
<!-- TODO: example more detail. -->
            <command>bind10</command> must be initially ran as the
            root user to use this option.
            The default is to run as the current user.</para>
         </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--pid-file</option> <replaceable>filename</replaceable></term>
        <listitem>
          <para>If defined, the PID of the <command>bind10</command> is stored
             in this file.
             This is used for testing purposes.
          </para>
         </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--pretty-name <replaceable>name</replaceable></option></term>

        <listitem>
          <para>The name this process should have in tools like
          <command>ps</command> or <command>top</command>. This
          is handy if you have multiple versions/installations
          of <command>bind10</command>.
<!-- TODO: only supported with setproctitle feature
The default is the basename of ARG 0.
-->
</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-v</option>, <option>--verbose</option></term>
        <listitem>
	  <para>Display more about what is going on for
	  <command>bind10</command> and its child processes.</para>
<!-- TODO: not true about all children yet -->
        </listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

<!--
TODO: configuration section
-->
<!--
  <refsect1>
    <title>FILES</title>
    <para><filename></filename>
    </para>
  </refsect1>
-->

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>bindctl</refentrytitle><manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-auth</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-cmdctl</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-xfrout</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-zonemgr</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citetitle>BIND 10 Guide</citetitle>.
    </para>
  </refsect1>

  <refsect1 id='history'><title>HISTORY</title>
    <para>The development of <command>bind10</command>
    was started in October 2009.</para>
  </refsect1>

  <refsect1>
    <title>AUTHORS</title>
    <para>
      The <command>bind10</command>
      daemon was initially designed by Shane Kerr of ISC.
    </para>
  </refsect1>
</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->