<!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-2012  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>April 12, 2012</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>2010-2012</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>-i</option></arg>
      <arg><option>-m <replaceable>file</replaceable></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>-w <replaceable>wait_time</replaceable></option></arg>
      <arg><option>--clear-config</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-kill</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>
      <arg><option>--wait <replaceable>wait_time</replaceable></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>-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.
          Defaults to <filename>b10-config.db</filename>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>--clear-config</option>
        </term>
        <listitem>
	  <para>
	    This will create a backup of the existing configuration
	    file, remove it and start
	    <refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum>
            with the default configuration.
	    The name of the backup file can be found in the logs
	    (<varname>CFGMGR_BACKED_UP_CONFIG_FILE</varname>).
	    (It will append a number to the backup filename if a
	    previous backup file exists.)

          </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
	  <citerefentry><refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>
	  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>-i</option>, <option>--no-kill</option></term>
        <listitem>
	  <para>When this option is passed, <command>bind10</command>
	  does not send SIGTERM and SIGKILL signals to modules during
	  shutdown. (This option was introduced for use during
	  testing.)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-u</option> <replaceable>user</replaceable>, <option>--user</option> <replaceable>name</replaceable></term>
<!-- TODO: example more detail. -->
        <listitem>
          <para>The username for <command>bind10</command> to run as.
            <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.
          </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>

      <varlistentry>
        <term><option>-w</option> <replaceable>wait_time</replaceable>, <option>--wait</option> <replaceable>wait_time</replaceable></term>
        <listitem>
	  <para>Sets the amount of time that BIND 10 will wait for
	  the configuration manager (a key component of BIND 10)
	  to initialize itself before abandoning the start up and
	  terminating with an error.  The
	  <replaceable>wait_time</replaceable> is specified in
	  seconds and has a default value of 10.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

<!--
TODO: configuration section
-->

  <refsect1>
    <title>CONFIGURATION AND COMMANDS</title>

    <para>
      The configuration provides settings for components for
      <command>bind10</command> to manage under
      <varname>/Boss/components/</varname>.
      The default elements are:
    </para>

    <itemizedlist>

      <listitem>
        <para> <varname>/Boss/components/b10-cmdctl</varname> </para>
      </listitem>

      <listitem>
        <para> <varname>/Boss/components/b10-stats</varname> </para>
      </listitem>

    </itemizedlist>

    <para>
      (Note that the startup of <command>b10-sockcreator</command>,
      <command>b10-cfgmgr</command>, and <command>b10-msgq</command>
      is not configurable. They are hardcoded and <command>bind10</command>
      will not run without them.)
    </para>

    <para>
      The named sets for components contain the following settings:
    </para>

    <variablelist>

      <varlistentry>
        <term><varname>address</varname></term>
        <listitem>
	  <para>The name used for communicating to it on the message
	  bus.</para>
<!-- NOTE: vorner said:
These can be null, because the components are special ones, and
the special class there already knows the address. It is (I hope)
explained in the guide. I'd like to get rid of the special components
sometime and I'd like it to teach to guess the address.
-->
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>kind</varname></term>
        <listitem>
          <para>
            This defines how required a component is.
            The possible settings for <varname>kind</varname> are:
            <varname>core</varname> (system won't start if it won't
            start and <command>bind10</command> will shutdown if
            a <quote>core</quote> component crashes),
            <varname>dispensable</varname> (<command>bind10</command>
            will restart failing component),
            and
	    <varname>needed</varname> (<command>bind10</command>
	    will shutdown if component won't initially start, but
	    if crashes later, it will attempt to restart).
            This setting is required.
<!-- TODO: formatting -->
          </para>
        </listitem>
      </varlistentry>

<!--
TODO: currently not used
      <varlistentry>
        <term> <varname>params</varname> </term>
        <listitem>
          <para>
list
</para>
        </listitem>
      </varlistentry>
-->

      <varlistentry>
        <term> <varname>priority</varname> </term>
        <listitem>
          <para>This is an integer. <command>bind10</command>
            will start the components with largest priority numbers first.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
          <term> <varname>process</varname> </term>
        <listitem>
          <para>This is the filename of the executable to be started.
            If not defined, then <command>bind10</command> will
            use the component name instead.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
          <term> <varname>special</varname> </term>
        <listitem>
          <para>
            This defines if the component is started a special, hardcoded
            way.
<!--
TODO: document this ... but maybe some of these will be removed
once we get rid of some using switches for components?

auth
cfgmgr
cmdctl
msgq
resolver
sockcreator
xfrin
-->

</para>
        </listitem>
      </varlistentry>

    </variablelist>

<!-- TODO: formating -->
    <para>
      The <varname>Boss</varname> configuration commands are:
    </para>
<!-- TODO: let's just let bind10 be known as bind10 and not Boss -->

<!-- TODO -->
<!--
    <para>
      <command>drop_socket</command>
      This is an internal command and not exposed to the administrator.
    </para>
-->

<!-- TODO -->
<!--
    <para>
      <command>get_socket</command>
      This is an internal command and not exposed to the administrator.
    </para>
-->

    <para>
      <command>getstats</command> tells <command>bind10</command>
      to send its statistics data to the <command>b10-stats</command>
      daemon.
      This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
    </para>

    <para>
      <command>ping</command> is used to check the connection with the
      <command>bind10</command> daemon.
      It returns the text <quote>pong</quote>.
    </para>

    <para>
      <command>show_processes</command> lists the current processes
      managed by <command>bind10</command>.
      The output is an array in JSON format containing the process
      ID, the name for each and the address name used on each message bus.
<!-- TODO: what is name? -->
<!-- TODO: change to JSON object format? -->
<!-- TODO: ticket #1406 -->
    </para>

    <para>
      <command>shutdown</command> tells <command>bind10</command>
      to shutdown the BIND 10 servers.
      It will tell each process it manages to shutdown and, when
      complete, <command>bind10</command> will exit.
    </para>

  </refsect1>

  <refsect1>
    <title>STATISTICS DATA</title>

    <para>
      The statistics data collected by the <command>b10-stats</command>
      daemon for <quote>Boss</quote> include:
    </para>

    <variablelist>

      <varlistentry>
        <term>boot_time</term>
        <listitem><para>
          The date and time that the <command>bind10</command>
          process started.
          This is represented in ISO 8601 format.
        </para></listitem>
      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1>
    <title>FILES</title>
    <para><filename>sockcreator-XXXXXX/sockcreator</filename>
    &mdash;
    the Unix Domain socket located in a temporary file directory for
    <command>b10-sockcreator</command>
<!--    <citerefentry><refentrytitle>b10-sockcreator</refentrytitle><manvolnum>8</manvolnum></citerefentry> -->
    communication.
    </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>,
      <citerefentry>
        <refentrytitle>b10-stats</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citetitle>BIND 10 Guide</citetitle>.
    </para>
  </refsect1>
<!-- <citerefentry>
        <refentrytitle>b10-sockcreator</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>, -->

  <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:
-->
