bind10-guide.xml 104 KB
Newer Older
1 2 3 4
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash  "&#x2014;" >
5 6
<!ENTITY % version SYSTEM "version.ent">
%version;
7
]>
8 9

<!--
Jeremy C. Reed's avatar
Jeremy C. Reed committed
10
 - Copyright (C) 2010-2012  Internet Systems Consortium, Inc. ("ISC")
11 12 13 14 15 16 17 18 19 20 21 22 23 24
 -
 - 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.
-->

25
<book>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
26
  <?xml-stylesheet href="bind10-guide.css" type="text/css"?>
27

28
  <bookinfo>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
29
    <title>BIND 10 Guide</title>
30 31 32
    <subtitle>Administrator Reference for BIND 10</subtitle>

    <copyright>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
33
      <year>2010-2012</year><holder>Internet Systems Consortium, Inc.</holder>
34 35
    </copyright>

36
    <abstract>
37 38 39 40 41 42
      <para>BIND 10 is a framework that features Domain Name System
      (DNS) suite and Dynamic Host Configuration Protocol (DHCP)
      servers managed by Internet Systems Consortium (ISC). It
      includes DNS libraries, modular components for controlling
      authoritative and recursive DNS servers, and experimental DHCPv4
      and DHCPv6 servers.
43
      </para>
44 45
      <para>
        This is the reference guide for BIND 10 version &__VERSION__;.
46 47 48 49
        The most up-to-date version of this document (in PDF, HTML,
        and plain text formats), along with other documents for
        BIND 10, can be found at <ulink url="http://bind10.isc.org/docs"/>.
        </para> </abstract>
50 51 52 53

      <releaseinfo>This is the reference guide for BIND 10 version
        &__VERSION__;.</releaseinfo>

54 55
  </bookinfo>

56 57 58 59 60 61 62 63 64 65 66 67 68 69
  <preface>
    <title>Preface</title>

    <section id="acknowledgements">
      <title>Acknowledgements</title>

      <para>ISC would like to acknowledge generous support for
      BIND 10 development of DHCPv4 and DHCPv6 components provided
      by <ulink url="http://www.comcast.com/">Comcast</ulink>.</para>

    </section>

  </preface>

70 71 72 73 74
  <chapter id="intro">
    <title>Introduction</title>
    <para>
      BIND is the popular implementation of a DNS server, developer
      interfaces, and DNS tools.
75 76
      BIND 10 is a rewrite of BIND 9.  BIND 10 is written in C++ and Python
      and provides a modular environment for serving and maintaining DNS.
77 78 79
      BIND 10 provides a EDNS0- and DNSSEC-capable authoritative
      DNS server and a caching recursive name server which also
      provides forwarding.
80 81
    </para>

82 83 84 85
    <para>
      This guide covers the experimental prototype of
      BIND 10 version &__VERSION__;.
    </para>
86

87
    <section>
88 89
      <title>Supported Platforms</title>
      <para>
90 91 92
  BIND 10 builds have been tested on Debian GNU/Linux 5 and unstable,
  Ubuntu 9.10, NetBSD 5, Solaris 10, FreeBSD 7 and 8, CentOS
  Linux 5.3, and MacOS 10.6.
93

94 95
  It has been tested on Sparc, i386, and amd64 hardware
  platforms.
96 97 98 99 100 101

        It is planned for BIND 10 to build, install and run on
        Windows and standard Unix-type platforms.
      </para>
    </section>

102
    <section id="required-software">
103 104
      <title>Required Software</title>
      <para>
105 106 107 108 109 110 111 112 113
        BIND 10 requires at least Python 3.1
        (<ulink url="http://www.python.org/"/>).
        It has also been tested with Python 3.2.
      </para>

      <para>
        BIND 10 uses the Botan crypto library for C++
        (<ulink url="http://botan.randombit.net/"/>).
        It requires at least Botan version 1.8.
114 115
      </para>

116
      <para>
117 118 119
        BIND 10 uses the log4cplus C++ logging library
        (<ulink url="http://log4cplus.sourceforge.net/"/>).
        It requires at least log4cplus version 1.0.3.
120
      </para>
121

122
      <para>
123 124 125 126
        The authoritative DNS server uses SQLite3
        (<ulink url="http://www.sqlite.org/"/>).
<!-- TODO: is this still required? -->
        It needs at least SQLite version 3.3.9.
127
      </para>
128

129
      <para>
130
        The <command>b10-xfrin</command>, <command>b10-xfrout</command>,
131 132 133 134
        and <command>b10-zonemgr</command> components require the
        libpython3 library and the Python _sqlite3.so module
        (which is included with Python).
        The Python module needs to be built for the corresponding Python 3.
135 136 137
      </para>
<!-- TODO: this will change ... -->

138
      <note>
139 140 141 142 143 144 145
        <para>
          Some operating systems do not provide these dependencies
          in their default installation nor standard packages
          collections.
          You may need to install them separately.
        </para>
      </note>
146
    </section>
147

148 149
    <section id="starting_stopping">
      <title>Starting and Stopping the Server</title>
150

151 152 153
      <para>
        BIND 10 is modular.  Part of this modularity is
        accomplished using multiple cooperating processes which, together,
154 155 156
        provide the server functionality.  This is a change from
        the previous generation of BIND software, which used a
        single process.
157 158 159
      </para>

      <para>
160 161 162 163 164 165 166
        At first, running many different processes may seem confusing.
        However, these processes are started, stopped, and maintained
        by a single command, <command>bind10</command>.
        This command starts a master process which will start other
        processes as needed.
        The processes started by the <command>bind10</command>
        command have names starting with "b10-", including:
167
      </para>
168

169
      <para>
170

171
        <itemizedlist>
172

173 174 175
          <listitem>
            <simpara>
              <command>b10-auth</command> &mdash;
176
              Authoritative DNS server.
177
              This process serves DNS requests.
178 179
            </simpara>
          </listitem>
180

181 182 183
          <listitem>
            <simpara>
              <command>b10-cfgmgr</command> &mdash;
184
              Configuration manager.
185
              This process maintains all of the configuration for BIND 10.
186 187
            </simpara>
          </listitem>
188

189 190 191
          <listitem>
            <simpara>
              <command>b10-cmdctl</command> &mdash;
192
              Command and control service.
193
              This process allows external control of the BIND 10 system.
194 195
            </simpara>
          </listitem>
196

Jeremy C. Reed's avatar
Jeremy C. Reed committed
197 198 199 200 201 202 203 204 205
          <listitem>
            <simpara>
              <command>b10-msgq</command> &mdash;
              Message bus daemon.
              This process coordinates communication between all of the other
              BIND 10 processes.
            </simpara>
          </listitem>

206 207 208 209 210 211 212 213 214
          <listitem>
            <simpara>
              <command>b10-resolver</command> &mdash;
              Recursive name server.
              This process handles incoming queries.
<!-- TODO: -->
            </simpara>
          </listitem>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
215 216 217 218 219 220 221 222 223
          <listitem>
            <simpara>
              <command>b10-sockcreator</command> &mdash;
              Socket creator daemon.
              This process creates sockets used by
              network-listening BIND 10 processes.
            </simpara>
          </listitem>

224 225 226 227 228 229 230 231
          <listitem>
            <simpara>
              <command>b10-stats</command> &mdash;
              Statistics collection daemon.
              This process collects and reports statistics data.
            </simpara>
          </listitem>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
232 233 234 235 236 237 238 239
          <listitem>
            <simpara>
              <command>b10-stats-httpd</command> &mdash;
              HTTP server for statistics reporting.
              This process reports statistics data in XML format over HTTP.
            </simpara>
          </listitem>

240 241 242
          <listitem>
            <simpara>
              <command>b10-xfrin</command> &mdash;
243
              Incoming zone transfer service.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
244
              This process is used to transfer a new copy
245
              of a zone into BIND 10, when acting as a secondary server.
246 247
            </simpara>
          </listitem>
248

Jeremy C. Reed's avatar
Jeremy C. Reed committed
249 250 251 252
          <listitem>
            <simpara>
              <command>b10-xfrout</command> &mdash;
              Outgoing zone transfer service.
253 254 255
              This process is used to handle transfer requests to
              send a local zone to a remote secondary server,
              when acting as a master server.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
256 257 258
            </simpara>
          </listitem>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
259 260 261 262
          <listitem>
            <simpara>
              <command>b10-zonemgr</command> &mdash;
              Secondary manager.
263
              This process keeps track of timers and other
Jeremy C. Reed's avatar
Jeremy C. Reed committed
264 265 266 267
              necessary information for BIND 10 to act as a slave server.
            </simpara>
          </listitem>

268 269
        </itemizedlist>
      </para>
270 271

      <para>
272 273
        These are ran automatically by <command>bind10</command>
        and do not need to be run manually.
274 275
      </para>

276
    </section>
277

278 279
    <section id="managing_once_running">
      <title>Managing BIND 10</title>
280

281
      <para>
282 283
        Once BIND 10 is running, a few commands are used to interact
        directly with the system:
284 285 286 287
        <itemizedlist>
          <listitem>
            <simpara>
              <command>bindctl</command> &mdash;
288
              interactive administration interface.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
289 290 291
              This is a low-level command-line tool which allows
              a developer or an experienced administrator to control
              BIND 10.
292 293 294 295 296
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <command>b10-loadzone</command> &mdash;
297 298 299
              zone file loader.
              This tool will load standard masterfile-format zone files into
              BIND 10.
300 301
            </simpara>
          </listitem>
302 303 304 305 306
          <listitem>
            <simpara>
              <command>b10-cmdctl-usermgr</command> &mdash;
              user access control.
              This tool allows an administrator to authorize additional users
307
              to manage BIND 10.
308 309
            </simpara>
          </listitem>
310 311 312 313
  <!-- TODO usermgr -->
        </itemizedlist>
      </para>
    </section>
314 315

    <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
316
      The tools and modules are covered in full detail in this guide.
317 318 319
<!-- TODO point to these -->
      In addition, manual pages are also provided in the default installation.
    </para>
320

321 322 323 324 325 326 327 328 329 330 331 332
<!--
bin/
  bindctl*
  host*
lib/
  libauth
  libdns
  libexceptions
  python3.1/site-packages/isc/{cc,config}
sbin/
  bind10
share/
333
  share/bind10/
334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352
    auth.spec
    b10-cmdctl.pem
    bob.spec
    passwd.csv
  man/
var/
  bind10/b10-config.db
-->

    <para>
      BIND 10 also provides libraries and programmer interfaces
      for C++ and Python for the message bus, configuration backend,
      and, of course, DNS. These include detailed developer
      documentation and code examples.
<!-- TODO point to this -->
    </para>

  </chapter>

353 354
  <chapter id="installation">
    <title>Installation</title>
355

356
    <section id="build-requirements">
357
      <title>Building Requirements</title>
358 359 360 361 362 363

        <para>
          In addition to the run-time requirements, building BIND 10
          from source code requires various development include headers.
        </para>

364
        <note>
365
          <simpara>
366 367 368
            Some operating systems have split their distribution packages into
            a run-time and a development package.  You will need to install
            the development package versions, which include header files and
Michael Graff's avatar
Michael Graff committed
369
            libraries, to build BIND 10 from source code.
370
          </simpara>
371 372
        </note>

373 374
        <para>
          Building from source code requires the Boost
375 376 377
          build-time headers
          (<ulink url="http://www.boost.org/"/>).
          At least Boost version 1.35 is required.
378 379 380 381
  <!-- TODO: we don't check for this version -->
  <!-- NOTE: jreed has tested with 1.34, 1.38, and 1.41. -->
        </para>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
382
        <para>
383 384
          To build BIND 10, also install the Botan (at least version
          1.8) and the log4cplus (at least version 1.0.3)
385 386 387 388 389 390 391 392 393
          development include headers.
        </para>

<!--
TODO
Debian and Ubuntu:
 libgmp3-dev and libbz2-dev required for botan too
-->

394 395
<!-- NOTE: _sqlite3 is only needed at test time; it is already listed
as a dependency earlier -->
Jeremy C. Reed's avatar
Jeremy C. Reed committed
396

397 398
        <para>
          Building BIND 10 also requires a C++ compiler and
399
          standard development headers, make, and pkg-config.
400
          BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
401
          4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
402
        </para>
403 404 405 406 407 408 409

        <para>
          Visit the wiki at <ulink
          url="http://bind10.isc.org/wiki/SystemSpecificNotes" />
          for system-specific installation tips.
        </para>

410 411
    </section>

412 413
    <section id="quickstart">
      <title>Quick start</title>
414 415 416 417 418
      <note>
        <simpara>
          This quickly covers the standard steps for installing
          and deploying BIND 10 as an authoritative name server using
          its defaults. For troubleshooting, full customizations and further
Jeremy C. Reed's avatar
Jeremy C. Reed committed
419
          details, see the respective chapters in the BIND 10 guide.
420 421
        </simpara>
      </note>
422

423 424 425 426 427
      <para>
        To quickly get started with BIND 10, follow these steps.
      </para>

      <orderedlist>
428

429
        <listitem>
430
          <simpara>
431
            Install required run-time and build dependencies.
432
          </simpara>
433
        </listitem>
434

435
        <listitem>
436 437 438
          <simpara>
            Download the BIND 10 source tar file from
            <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
439 440
          </simpara>
        </listitem>
441

442 443 444 445 446
        <listitem>
          <para>Extract the tar file:
          <screen>$ <userinput>gzcat bind10-<replaceable>VERSION</replaceable>.tar.gz | tar -xvf -</userinput></screen>
          </para>
        </listitem>
447

448 449 450 451 452 453
        <listitem>
          <para>Go into the source and run configure:
            <screen>$ <userinput>cd bind10-<replaceable>VERSION</replaceable></userinput>
  $ <userinput>./configure</userinput></screen>
          </para>
        </listitem>
454

455 456 457 458 459
        <listitem>
          <para>Build it:
            <screen>$ <userinput>make</userinput></screen>
          </para>
        </listitem>
460

461 462 463 464 465
        <listitem>
          <para>Install it (to default /usr/local):
            <screen>$ <userinput>make install</userinput></screen>
          </para>
        </listitem>
466

467 468 469 470 471
        <listitem>
          <para>Start the server:
            <screen>$ <userinput>/usr/local/sbin/bind10</userinput></screen>
          </para>
        </listitem>
472

473
        <listitem>
474

475
         <para>Test it; for example:
476
            <screen>$ <userinput>dig @127.0.0.1 -c CH -t TXT authors.bind</userinput></screen>
477 478 479 480 481 482 483 484 485 486
         </para>
        </listitem>

        <listitem>
          <para>Load desired zone file(s), for example:
            <screen>$ <userinput>b10-loadzone <replaceable>your.zone.example.org</replaceable></userinput></screen>
          </para>
        </listitem>

        <listitem>
487 488
          <simpara>
            Test the new zone.
489 490
          </simpara>
        </listitem>
491

492
      </orderedlist>
493 494 495 496 497

    </section>

    <section id="install">
      <title>Installation from source</title>
498
      <para>
499 500
        BIND 10 is open source software written in C++ and Python.
        It is freely available in source code form from ISC via
501
        the Git code revision control system or as a downloadable
502 503
        tar file. It may also be available in pre-compiled ready-to-use
        packages from operating system vendors.
504 505
      </para>

506 507
      <section>
        <title>Download Tar File</title>
508 509 510 511
        <para>
          Downloading a release tar file is the recommended method to
          obtain the source code.
        </para>
512

513 514
        <para>
          The BIND 10 releases are available as tar file downloads from
515 516
          <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
          Periodic development snapshots may also be available.
517 518 519 520 521
        </para>
  <!-- TODO -->
      </section>

      <section>
522
        <title>Retrieve from Git</title>
523 524 525 526 527
        <para>
          Downloading this "bleeding edge" code is recommended only for
          developers or advanced users.  Using development code in a production
          environment is not recommended.
        </para>
528 529 530

        <note>
          <para>
531
            When using source code retrieved via Git additional
532
            software will be required:  automake (v1.11 or newer),
533
            libtoolize, and autoconf (2.59 or newer).
534 535 536 537
            These may need to be installed.
          </para>
        </note>

538 539 540
        <para>
          The latest development code, including temporary experiments
          and un-reviewed code, is available via the BIND 10 code revision
541
          control system. This is powered by Git and all the BIND 10
542
          development is public.
543
          The leading development is done in the <quote>master</quote>.
544 545
        </para>
        <para>
546
          The code can be checked out from
547
          <filename>git://git.bind10.isc.org/bind10</filename>;
548
          for example:
549

550
        <screen>$ <userinput>git clone git://git.bind10.isc.org/bind10</userinput></screen>
551
        </para>
552

553 554 555 556 557 558 559 560 561 562 563 564 565 566 567
        <para>
          When checking out the code from
          the code version control system, it doesn't include the
          generated configure script, Makefile.in files, nor the
          related configure files.
          They can be created by running <command>autoreconf</command>
          with the <option>--install</option> switch.
          This will run <command>autoconf</command>,
          <command>aclocal</command>,
          <command>libtoolize</command>,
          <command>autoheader</command>,
          <command>automake</command>,
          and related commands.
        </para>

568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585
      </section>


      <section>
        <title>Configure before the build</title>
        <para>
          BIND 10 uses the GNU Build System to discover build environment
          details.
          To generate the makefiles using the defaults, simply run:
          <screen>$ <userinput>./configure</userinput></screen>
        </para>
        <para>
          Run <command>./configure</command> with the <option>--help</option>
          switch to view the different options. The commonly-used options are:

          <variablelist>

          <varlistentry>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
586 587
            <term>--prefix</term>
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
588
              <simpara>Define the installation location (the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
589 590
                default is <filename>/usr/local/</filename>).
              </simpara>
591
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
592 593 594 595
          </varlistentry>

          <varlistentry>
            <term>--with-boost-include</term>
596
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
597
              <simpara>Define the path to find the Boost headers.
598
              </simpara>
599
            </listitem>
600 601 602
          </varlistentry>

          <varlistentry>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
603
            <term>--with-pythonpath</term>
604
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
605 606 607
              <simpara>Define the path to Python 3.1 if it is not in the
                standard execution path.
              </simpara>
608
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
609 610 611 612
          </varlistentry>

          <varlistentry>
            <term>--with-gtest</term>
613
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
614 615 616
              <simpara>Enable building the C++ Unit Tests using the
                Google Tests framework. Optionally this can define the
                path to the gtest header files and library.
617
              </simpara>
618
            </listitem>
619 620 621 622 623
          </varlistentry>

          </variablelist>

        </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
624
  <!-- TODO: lcov -->
625 626

        <para>
627
          For example, the following configures it to
628
    find the Boost headers, find the
629
    Python interpreter, and sets the installation location:
630

631
          <screen>$ <userinput>./configure \
632 633 634 635 636 637 638 639 640 641 642 643 644 645 646
      --with-boost-include=/usr/pkg/include \
      --with-pythonpath=/usr/pkg/bin/python3.1 \
      --prefix=/opt/bind10</userinput></screen>
        </para>

        <para>
          If the configure fails, it may be due to missing or old
          dependencies.
        </para>

      </section>

      <section>
        <title>Build</title>
        <para>
647 648
    After the configure step is complete, to build the executables
    from the C++ code and prepare the Python scripts, run:
649 650 651 652 653 654 655 656

          <screen>$ <userinput>make</userinput></screen>
        </para>
      </section>

      <section>
        <title>Install</title>
        <para>
Michael Graff's avatar
Michael Graff committed
657 658
          To install the BIND 10 executables, support files,
          and documentation, run:
659 660
          <screen>$ <userinput>make install</userinput></screen>
        </para>
Michael Graff's avatar
Michael Graff committed
661
        <note>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
662
          <para>The install step may require superuser privileges.</para>
Michael Graff's avatar
Michael Graff committed
663
        </note>
664 665 666 667 668 669 670 671 672

      </section>

  <!-- TODO: tests -->

      <section>
        <title>Install Hierarchy</title>
        <para>
          The following is the layout of the complete BIND 10 installation:
673 674 675 676 677 678 679 680 681
          <itemizedlist>
            <listitem>
              <simpara>
                <filename>bin/</filename> &mdash;
                general tools and diagnostic clients.
              </simpara>
            </listitem>
            <listitem>
            <simpara>
682
              <filename>etc/bind10-devel/</filename> &mdash;
683 684 685 686 687 688 689 690 691 692 693
              configuration files.
            </simpara>
            </listitem>
            <listitem>
              <simpara>
                <filename>lib/</filename> &mdash;
                libraries and python modules.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
694
                <filename>libexec/bind10-devel/</filename> &mdash;
695 696 697 698 699 700 701 702 703 704 705 706 707 708
                executables that a user wouldn't normally run directly and
                are not run independently.
                These are the BIND 10 modules which are daemons started by
                the <command>bind10</command> tool.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
                <filename>sbin/</filename> &mdash;
                commands used by the system administrator.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
709
                <filename>share/bind10-devel/</filename> &mdash;
710 711 712 713 714 715 716 717 718 719 720
                configuration specifications.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
                <filename>share/man/</filename> &mdash;
                manual pages (online documentation).
              </simpara>
            </listitem>
            <listitem>
              <simpara>
721
                <filename>var/bind10-devel/</filename> &mdash;
722 723 724 725 726
                data source and configuration databases.
              </simpara>
            </listitem>
          </itemizedlist>
        </para>
727 728 729 730 731 732 733 734 735 736
      </section>
    </section>

  <!--
      <section id="install.troubleshooting">
        <title>Troubleshooting</title>
        <para>
        </para>
      </section>
  -->
737

738
  </chapter>
739

740
  <chapter id="bind10">
Michael Graff's avatar
Michael Graff committed
741
    <title>Starting BIND10 with <command>bind10</command></title>
742
    <para>
743
      BIND 10 provides the <command>bind10</command> command which
Michael Graff's avatar
Michael Graff committed
744 745
      starts up the required processes.
      <command>bind10</command>
746
      will also restart some processes that exit unexpectedly.
Michael Graff's avatar
Michael Graff committed
747
      This is the only command needed to start the BIND 10 system.
748 749 750
    </para>

    <para>
751
      After starting the <command>b10-msgq</command> communications channel,
752
      <command>bind10</command> connects to it,
753 754
      runs the configuration manager, and reads its own configuration.
      Then it starts the other modules.
755 756 757
    </para>

    <para>
758 759
      The <command>b10-sockcreator</command>, <command>b10-msgq</command> and
      <command>b10-cfgmgr</command>
760
      services make up the core. The <command>b10-msgq</command> daemon
761
      provides the communication channel between every part of the system.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
762
      The <command>b10-cfgmgr</command> daemon is always needed by every
763 764
      module, if only to send information about themselves somewhere,
      but more importantly to ask about their own settings, and
765 766
      about other modules. The <command>b10-sockcreator</command> will
      allocate sockets for the rest of the system.
767 768 769 770 771
    </para>

    <para>
      In its default configuration, the <command>bind10</command>
      master process will also start up
Jeremy C. Reed's avatar
Jeremy C. Reed committed
772 773 774
      <command>b10-cmdctl</command> for administration tools to
      communicate with the system,
      <command>b10-auth</command> for authoritative DNS service,
775
      <command>b10-stats</command> for statistics collection,
Jeremy C. Reed's avatar
Jeremy C. Reed committed
776
      <command>b10-stats-httpd</command> for statistics reporting,
777 778
      <command>b10-xfrin</command> for inbound DNS zone transfers,
      <command>b10-xfrout</command> for outbound DNS zone transfers,
Jeremy C. Reed's avatar
Jeremy C. Reed committed
779
      and <command>b10-zonemgr</command> for secondary service.
780 781
    </para>

782
    <section id="start">
783 784 785
      <title>Starting BIND 10</title>
      <para>
        To start the BIND 10 service, simply run <command>bind10</command>.
786
        Run it with the <option>--verbose</option> switch to
787 788 789
        get additional debugging or diagnostic output.
      </para>
<!-- TODO: note it doesn't go into background -->
790 791 792 793 794 795 796 797 798 799

      <note>
        <para>
          If the setproctitle Python module is detected at start up,
          the process names for the Python-based daemons will be renamed
          to better identify them instead of just <quote>python</quote>.
          This is not needed on some operating systems.
        </para>
      </note>

800
    </section>
801 802 803 804 805 806 807 808 809 810 811 812 813 814
    <section id="bind10.config">
      <title>Configuration of started processes</title>
      <para>
        The processes to be started can be configured, with the exception
        of the <command>b10-sockcreator</command>, <command>b10-msgq</command>
        and <command>b10-cfgmgr</command>.
      </para>

      <para>
        The configuration is in the Boss/components section. Each element
        represents one component, which is an abstraction of a process
        (currently there's also one component which doesn't represent
        a process). If you didn't want to transfer out at all (your server
        is a slave only), you would just remove the corresponding component
Jeremy C. Reed's avatar
Jeremy C. Reed committed
815
        from the set, like this and the process would be stopped immediately
816
        (and not started on the next startup):
817
      <screen>&gt; <userinput>config remove Boss/components b10-xfrout</userinput>
818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858
&gt; <userinput>config commit</userinput></screen>
      </para>

      <para>
        To add a process to the set, let's say the resolver (which not started
        by default), you would do this:
        <screen>&gt; <userinput>config add Boss/components b10-resolver</userinput>
&gt; <userinput>config set Boss/components/b10-resolver/special resolver</userinput>
&gt; <userinput>config set Boss/components/b10-resolver/kind needed</userinput>
&gt; <userinput>config set Boss/components/b10-resolver/priority 10</userinput>
&gt; <userinput>config commit</userinput></screen></para>

      <para>
        Now, what it means. We add an entry called b10-resolver. It is both a
        name used to reference this component in the configuration and the
        name of the process to start. Then we set some parameters on how to
        start it.
      </para>

      <para>
        The special one is for components that need some kind of special care
        during startup or shutdown. Unless specified, the component is started
        in usual way. This is the list of components that need to be started
        in a special way, with the value of special used for them:
        <table>
          <tgroup cols='3' align='left'>
          <colspec colname='component'/>
          <colspec colname='special'/>
          <colspec colname='description'/>
          <thead><row><entry>Component</entry><entry>Special</entry><entry>Description</entry></row></thead>
          <tbody>
            <row><entry>b10-auth</entry><entry>auth</entry><entry>Authoritative server</entry></row>
            <row><entry>b10-resolver</entry><entry>resolver</entry><entry>The resolver</entry></row>
            <row><entry>b10-cmdctl</entry><entry>cmdctl</entry><entry>The command control (remote control interface)</entry></row>
            <!-- TODO Either add xfrin and xfrout as well or clean up the workarounds in boss before the release -->
          </tbody>
          </tgroup>
        </table>
      </para>

      <para>
859 860 861 862 863 864 865 866 867 868 869 870 871 872
        The kind specifies how a failure of the component should
        be handled.  If it is set to <quote>dispensable</quote>
        (the default unless you set something else), it will get
        started again if it fails. If it is set to <quote>needed</quote>
        and it fails at startup, the whole <command>bind10</command>
        shuts down and exits with error exit code. But if it fails
        some time later, it is just started again. If you set it
        to <quote>core</quote>, you indicate that the system is
        not usable without the component and if such component
        fails, the system shuts down no matter when the failure
        happened.  This is the behaviour of the core components
        (the ones you can't turn off), but you can declare any
        other components as core as well if you wish (but you can
        turn these off, they just can't fail).
873 874 875 876 877
      </para>

      <para>
        The priority defines order in which the components should start.
        The ones with higher number are started sooner than the ones with
878
        lower ones. If you don't set it, 0 (zero) is used as the priority.
879
        Usually, leaving it at the default is enough.
880 881 882 883
      </para>

      <para>
        There are other parameters we didn't use in our example.
884 885 886 887 888 889 890
        One of them is <quote>address</quote>. It is the address
        used by the component on the <command>b10-msgq</command>
        message bus. The special components already know their
        address, but the usual ones don't. The address is by
        convention the thing after <emphasis>b10-</emphasis>, with
        the first letter capital (eg. <command>b10-stats</command>
        would have <quote>Stats</quote> as its address).
891
<!-- TODO: this should be simplified so we don't even have to document it -->
892 893
      </para>

894 895 896 897 898
<!-- TODO: what does "The special components already know their
address, but the usual ones don't." mean? -->

<!-- TODO: document params when is enabled -->

899 900 901 902 903 904 905 906 907 908 909 910 911
      <para>
        The last one is process. It is the name of the process to be started.
        It defaults to the name of the component if not set, but you can use
        this to override it.
      </para>

      <!-- TODO Add parameters when they work, not implemented yet-->

      <note>
        <para>
          This system allows you to start the same component multiple times
          (by including it in the configuration with different names, but the
          same process setting). However, the rest of the system doesn't expect
912
          such a situation, so it would probably not do what you want. Such
913 914 915 916 917 918
          support is yet to be implemented.
        </para>
      </note>

      <note>
        <para>
919 920 921 922 923
          The configuration is quite powerful, but that includes
          a lot of space for mistakes. You could turn off the
          <command>b10-cmdctl</command>, but then you couldn't
          change it back the usual way, as it would require it to
          be running (you would have to find and edit the configuration
924 925
          directly).  Also, some modules might have dependencies:
          <command>b10-stats-httpd</command> needs
926
          <command>b10-stats</command>, <command>b10-xfrout</command>
927
          needs <command>b10-auth</command> to be running, etc.
928 929 930

<!-- TODO: should we define dependencies? -->

931 932 933 934 935
        </para>
        <para>
          In short, you should think twice before disabling something here.
        </para>
      </note>
Michal 'vorner' Vaner's avatar
Michal 'vorner' Vaner committed
936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953
      <para>
        It is possible to start some components multiple times (currently
        <command>b10-auth</command> and <command>b10-resolzer</command>).
        You might want to do that to gain more performance (each one uses only
        single core). Just put multiple entries under different names, like
        this, with the same config:
        <screen>&gt; <userinput>config add Boss/components b10-resolver-2</userinput>
&gt; <userinput>config set Boss/components/b10-resolver-2/special resolver</userinput>
&gt; <userinput>config set Boss/components/b10-resolver-2/kind needed</userinput>
&gt; <userinput>config commit</userinput></screen>
      </para>
      <para>
        However, this is work in progress and the support is not yet complete.
        For example, each resolver will have its own cache, each authoritative
        server will keep its own copy of in-memory data and there could be
        problems with locking the sqlite database, if used. The configuration
        might be changed to something more convenient in future.
      </para>
954
    </section>
955 956 957

  </chapter>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
958 959 960 961
  <chapter id="msgq">
    <title>Command channel</title>

      <para>
962
        The BIND 10 components use the <command>b10-msgq</command>
Michael Graff's avatar
Michael Graff committed
963
        message routing daemon to communicate with other BIND 10 components.
964
        The <command>b10-msgq</command> implements what is called the
Michael Graff's avatar
Michael Graff committed
965 966 967 968 969
        <quote>Command Channel</quote>.
        Processes intercommunicate by sending messages on the command
        channel.
        Example messages include shutdown, get configurations, and set
        configurations.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
970
        This Command Channel is not used for DNS message passing.
Michael Graff's avatar
Michael Graff committed
971 972
        It is used only to control and monitor the BIND 10 system.
      </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
973 974 975

      <para>
        Administrators do not communicate directly with the
976
        <command>b10-msgq</command> daemon.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
977
        By default, BIND 10 uses port 9912 for the
978
        <command>b10-msgq</command> service.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
979 980
        It listens on 127.0.0.1.
      </para>
981

Jeremy C. Reed's avatar
Jeremy C. Reed committed
982
<!-- TODO: this is broken, see Trac #111
Michael Graff's avatar
Michael Graff committed
983
      <para>
984
        To select an alternate port for the <command>b10-msgq</command> to
Michael Graff's avatar
Michael Graff committed
985
        use, run <command>bind10</command> specifying the option:
Jeremy C. Reed's avatar
Jeremy C. Reed committed
986
        <screen> $ <userinput>bind10 -TODO-msgq-port 9912</userinput></screen>
Michael Graff's avatar
Michael Graff committed
987
      </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
988
-->
Jeremy C. Reed's avatar
Jeremy C. Reed committed
989 990 991 992 993 994 995

<!-- TODO: upcoming plans:
Unix domain sockets
-->

  </chapter>

996 997 998 999
  <chapter id="cfgmgr">
    <title>Configuration manager</title>

      <para>
Michael Graff's avatar
Michael Graff committed
1000 1001 1002 1003 1004
         The configuration manager, <command>b10-cfgmgr</command>,
         handles all BIND 10 system configuration.  It provides
         persistent storage for configuration, and notifies running
         modules of configuration changes.
      </para>
1005 1006

      <para>
Michael Graff's avatar
Michael Graff committed
1007 1008
        The <command>b10-auth</command> and <command>b10-xfrin</command>
        daemons and other components receive their configurations
1009
        from the configuration manager over the <command>b10-msgq</command>
Michael Graff's avatar
Michael Graff committed
1010
        command channel.
1011 1012
      </para>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1013 1014 1015 1016
      <para>The administrator doesn't connect to it directly, but
        uses a user interface to communicate with the configuration
        manager via <command>b10-cmdctl</command>'s REST-ful interface.
        <command>b10-cmdctl</command> is covered in <xref linkend="cmdctl"/>.
1017 1018 1019
      </para>

<!-- TODO -->
Michael Graff's avatar
Michael Graff committed
1020 1021
      <note>
        <para>
1022
          The development prototype release only provides
Michael Graff's avatar
Michael Graff committed
1023 1024 1025 1026 1027 1028
          <command>bindctl</command> as a user interface to
          <command>b10-cmdctl</command>.
          Upcoming releases will provide another interactive command-line
          interface and a web-based interface.
        </para>
      </note>
1029 1030 1031 1032

      <para>
        The <command>b10-cfgmgr</command> daemon can send all
        specifications and all current settings to the
Michael Graff's avatar
Michael Graff committed
1033 1034
        <command>bindctl</command> client (via
        <command>b10-cmdctl</command>).
1035 1036
      </para>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054
      <para>
        <command>b10-cfgmgr</command> relays configurations received
        from <command>b10-cmdctl</command> to the appropriate modules.
      </para>
<!-- TODO:
        Configuration settings for itself are defined as ConfigManager.
TODO: show examples
-->

<!-- TODO:
config changes are actually commands to cfgmgr
-->

<!-- TODO: what about run time config to change this? -->
<!-- jelte: > config set cfgmgr/config_database <file> -->
<!-- TODO: what about command line switch to change this? -->
      <para>
        The stored configuration file is at
1055
        <filename>/usr/local/var/bind10-devel/b10-config.db</filename>.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1056
        (The full path is what was defined at build configure time for
1057 1058
        <option>--localstatedir</option>.
        The default is <filename>/usr/local/var/</filename>.)
Michael Graff's avatar
Michael Graff committed
1059 1060 1061 1062
        The format is loosely based on JSON and is directly parseable
        python, but this may change in a future version.
        This configuration data file is not manually edited by the
        administrator.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1063
      </para>
1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078

<!--

Well the specfiles have a more fixed format (they must contain specific
stuff), but those are also directly parseable python structures (and
'coincidentally', our data::element string representation is the same)

loosely based on json, tweaked to be directly parseable in python, but a
subset of that.
wiki page is http://bind10.isc.org/wiki/DataElementDesign

nope, spec files are written by module developers, and db should be done
through bindctl and friends

-->
1079 1080

    <para>
1081 1082 1083 1084 1085 1086 1087 1088 1089
      The configuration manager does not have any command line arguments.
      Normally it is not started manually, but is automatically
      started using the <command>bind10</command> master process
      (as covered in <xref linkend="bind10"/>).
    </para>

<!-- TODO: upcoming plans:
configuration for configuration manager itself. And perhaps we might
change the messaging protocol, but an admin should never see any of that
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1090 1091 1092 1093 1094 1095 1096
-->

<!-- TODO: show examples, test this -->
<!--
, so an admin can simply run bindctl,
do config show, and it shows all modules; config show >module> shows all
options for that module
1097 1098 1099 1100 1101 1102 1103
-->

  </chapter>

  <chapter id="cmdctl">
    <title>Remote control daemon</title>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1104 1105 1106 1107 1108 1109 1110 1111
    <para>
      <command>b10-cmdctl</command> is the gateway between
      administrators and the BIND 10 system.
      It is a HTTPS server that uses standard HTTP Digest
      Authentication for username and password validation.
      It provides a REST-ful interface for accessing and controlling
      BIND 10.
    </para>
1112 1113
<!-- TODO: copy examples from wiki, try with wget -->

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1114
    <para>
1115
      When <command>b10-cmdctl</command> starts, it firsts
1116 1117
      asks <command>b10-cfgmgr</command> about what modules are
      running and what their configuration is (over the
1118
      <command>b10-msgq</command> channel). Then it will start listening
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1119 1120 1121 1122 1123 1124 1125 1126 1127
      on HTTPS for clients &mdash; the user interface &mdash; such
      as <command>bindctl</command>.
    </para>

    <para>
      <command>b10-cmdctl</command> directly sends commands
      (received from the user interface) to the specified component.
      Configuration changes are actually commands to
      <command>b10-cfgmgr</command> so are sent there.
1128
    </para>
1129

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142
<!--
TODO:
"For bindctl to list a module's available configurations and
available commands, it communicates over the cmdctl REST interface.
cmdctl then asks cfgmgr over the msgq command channel. Then cfgmgr
asks the module for its specification and also cfgmgr looks in its
own configuration database for current values."

(05:32:03) jelte: i think cmdctl doesn't request it upon a incoming
GET, but rather requests it once and then listens in for updates,
but you might wanna check with likun
-->

1143 1144
<!-- TODO: replace /usr/local -->
<!-- TODO: permissions -->
1145 1146 1147
    <para>The HTTPS server requires a private key,
      such as a RSA PRIVATE KEY.
      The default location is at
1148
      <filename>/usr/local/etc/bind10-devel/cmdctl-keyfile.pem</filename>.
1149
      (A sample key is at
1150
      <filename>/usr/local/share/bind10-devel/cmdctl-keyfile.pem</filename>.)
1151
      It also uses a certificate located at
1152
      <filename>/usr/local/etc/bind10-devel/cmdctl-certfile.pem</filename>.
1153
      (A sample certificate is at
1154
      <filename>/usr/local/share/bind10-devel/cmdctl-certfile.pem</filename>.)
1155
      This may be a self-signed certificate or purchased from a
1156 1157
      certification authority.
    </para>
1158 1159

    <note><para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1160 1161 1162 1163 1164
      The HTTPS server doesn't support a certificate request from a
      client (at this time).
<!-- TODO: maybe allow request from server side -->
      The <command>b10-cmdctl</command> daemon does not provide a
      public service. If any client wants to control BIND 10, then
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1165
      a certificate needs to be first received from the BIND 10
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1166 1167
      administrator.
      The BIND 10 installation provides a sample PEM bundle that matches
1168 1169 1170
      the sample key and certificate.
    </para></note>
<!-- TODO: cross-ref -->