b10-auth.xml 8.51 KB
Newer Older
1 2 3 4
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	       [<!ENTITY mdash "&#8212;">]>
<!--
5
 - Copyright (C) 2010-2012  Internet Systems Consortium, Inc. ("ISC")
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
 -
 - 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>
23
    <date>March 1, 2012</date>
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
  </refentryinfo>

  <refmeta>
    <refentrytitle>b10-auth</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo>BIND10</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>b10-auth</refname>
    <refpurpose>Authoritative DNS server</refpurpose>
  </refnamediv>

  <docinfo>
    <copyright>
39
      <year>2010-2012</year>
40 41 42 43 44 45 46
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
  </docinfo>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>b10-auth</command>
47
      <arg><option>-n</option></arg>
48 49 50 51 52 53 54 55 56 57
      <arg><option>-v</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para>The <command>b10-auth</command> daemon provides the BIND 10
      authoritative DNS server.
      Normally it is started by the
      <citerefentry><refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum></citerefentry>
58
      boss process.
59 60 61
    </para>

    <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
62
      This daemon communicates with other BIND 10 components over a
63
      <citerefentry><refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum></citerefentry>
64 65
      C-Channel connection.  If this connection is not established,
      <command>b10-auth</command> will exit.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
66
<!-- TODO what if msgq connection closes later, will b10-auth exit? -->
67
      It receives its configurations from
68
<citerefentry><refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
69 70 71

    </para>

72 73
<!-- TODO: mention xfrin, xfrout, zonemgr ? -->

74 75 76 77 78 79 80 81
  </refsect1>

  <refsect1>
    <title>OPTIONS</title>

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

    <variablelist>
82 83 84 85 86 87 88 89 90
      <varlistentry>
        <term><option>-n</option></term>
        <listitem><para>
          Do not cache answers in memory.
          The default is to use the cache for faster responses.
	  The cache keeps the most recent 30,000 answers (positive
	  and negative) in memory for 30 seconds (instead of querying
	  the data source, such as SQLite3 database, each time).
        </para></listitem>
91
<!-- TODO: this is SQLite3 only -->
92 93
      </varlistentry>

94 95 96 97 98 99 100 101 102 103 104 105
      <varlistentry>
        <term><option>-v</option></term>
        <listitem><para>
          Enabled verbose mode. This enables diagnostic messages to
          STDERR.
        </para></listitem>
      </varlistentry>

    </variablelist>

  </refsect1>

106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
  <refsect1>
    <title>CONFIGURATION AND COMMANDS</title>
    <para>
      The configurable settings are:
    </para>

    <para>
      <varname>database_file</varname> defines the path to the
      SQLite3 zone file when using the sqlite datasource.
      The default is
      <filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>.
    </para>

    <para>
      <varname>datasources</varname> configures data sources.
      The list items include:
      <varname>type</varname> to optionally choose the data source type
      (such as <quote>memory</quote>);
      <varname>class</varname> to optionally select the class
      (it defaults to <quote>IN</quote>);
      and
      <varname>zones</varname> to define the
      <varname>file</varname> path name and the
      <varname>origin</varname> (default domain).

      By default, this is empty.

      <note><simpara>
        In this development version, currently this is only used for the
        memory data source.
        Only the IN class is supported at this time.
        By default, the memory data source is disabled.
        Also, currently the zone file must be canonical such as
        generated by <command>named-compilezone -D</command>.
      </simpara></note>
    </para>

143 144 145 146 147 148 149 150 151
    <para>
      <varname>listen_on</varname> is a list of addresses and ports for
      <command>b10-auth</command> to listen on.
      The list items are the <varname>address</varname> string
      and <varname>port</varname> number.
      By default, <command>b10-auth</command> listens on port 53
      on the IPv6 (::) and IPv4 (0.0.0.0) wildcard addresses.
    </para>

152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190
    <para>
      <varname>statistics-interval</varname> is the timer interval
      in seconds for <command>b10-auth</command> to share its
      statistics information to
      <citerefentry><refentrytitle>b10-stats</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
      Statistics updates can be disabled by setting this to 0.
      The default is 60.
    </para>

<!-- TODO: formating -->
    <para>
      The configuration commands are:
    </para>

    <para>
      <command>loadzone</command> tells <command>b10-auth</command>
      to load or reload a zone file. The arguments include:
      <varname>class</varname> which optionally defines the class
      (it defaults to <quote>IN</quote>);
      <varname>origin</varname> is the domain name of the zone;
      and
      <varname>datasrc</varname> optionally defines the type of datasource
      (it defaults to <quote>memory</quote>).

      <note><simpara>
        In this development version, currently this only supports the
        IN class and the memory data source.
      </simpara></note>
    </para>

    <para>
      <command>sendstats</command> tells <command>b10-auth</command>
      to send its statistics data to
      <citerefentry><refentrytitle>b10-stats</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      immediately.
    </para>

    <para>
      <command>shutdown</command> exits <command>b10-auth</command>.
191 192 193 194
      This has an optional <varname>pid</varname> argument to
      select the process ID to stop.
      (Note that the BIND 10 boss process may restart this service
      if configured.)
195 196 197 198
    </para>

  </refsect1>

199 200 201 202 203
  <refsect1>
    <title>STATISTICS DATA</title>

    <para>
      The statistics data collected by the <command>b10-stats</command>
204
      daemon for <quote>Auth</quote> include:
205 206 207 208 209
    </para>

    <variablelist>

      <varlistentry>
210
        <term>queries.tcp</term>
211 212 213 214 215 216
        <listitem><simpara>Total count of queries received by the
          <command>b10-auth</command> server over TCP since startup.
        </simpara></listitem>
      </varlistentry>

      <varlistentry>
217
        <term>queries.udp</term>
218 219 220 221 222 223 224
        <listitem><simpara>Total count of queries received by the
          <command>b10-auth</command> server over UDP since startup.
        </simpara></listitem>
      </varlistentry>

    </variablelist>

225 226
<!-- TODO: missing stats docs. See ticket #1721 -->

227 228
  </refsect1>

229 230 231
  <refsect1>
    <title>FILES</title>
    <para>
232
      <filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>
233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248
      &mdash; Location for the SQLite3 zone database
      when <emphasis>database_file</emphasis> configuration is not
      defined.
    </para>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-loadzone</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
249
        <refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum>
250
      </citerefentry>,
251 252 253
      <citerefentry>
        <refentrytitle>b10-stats</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
254 255 256
      <citerefentry>
        <refentrytitle>b10-zonemgr</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
257
      <citerefentry>
258
        <refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum>
259
      </citerefentry>,
Jeremy C. Reed's avatar
Jeremy C. Reed committed
260
      <citetitle>BIND 10 Guide</citetitle>.
261 262 263 264 265 266 267 268 269 270 271 272 273 274
    </para>
  </refsect1>

  <refsect1>
    <title>HISTORY</title>
    <para>
      The <command>b10-auth</command> daemon was first coded in October 2009.
    </para>
  </refsect1>
</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->