bind10-guide.xml 285 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

<!--
10
 - Copyright (C) 2010-2014  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>
33
      <year>2010-2013</year><holder>Internet Systems Consortium, Inc.</holder>
34 35
    </copyright>

36
    <abstract>
37 38
      <para>BIND 10 is a framework that features Domain Name System
      (DNS) suite and Dynamic Host Configuration Protocol (DHCP)
Jeremy C. Reed's avatar
Jeremy C. Reed committed
39 40
      servers with development managed by Internet Systems Consortium (ISC).
      It includes DNS libraries, modular components for controlling
41
      authoritative and recursive DNS servers, and experimental DHCPv4
42
      and DHCPv6 servers (codenamed Kea).
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
  <preface>
    <title>Preface</title>

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

62
      <para>BIND 10 is a sponsored development project, and would not
63 64
      be possible without the generous support of the sponsors.</para>

65 66
      <para><ulink url="http://jprs.co.jp/">JPRS</ulink> and
      <ulink url="http://cira.ca/">CIRA</ulink> are Patron Level
67 68
      sponsors.</para>

69
      <para><ulink url="https://www.afnic.fr/">AFNIC</ulink>,
70 71 72 73 74 75 76 77 78 79
      <ulink url="https://www.cnnic.net.cn/">CNNIC</ulink>,
      <ulink url="https://www.nic.cz/">CZ.NIC</ulink>,
      <ulink url="http://www.denic.de/">DENIC eG</ulink>,
      <ulink url="https://www.google.com/">Google</ulink>,
      <ulink url="https://www.ripe.net/">RIPE NCC</ulink>,
      <ulink url="https://registro.br/">Registro.br</ulink>,
      <ulink url="https://nzrs.net.nz/">.nz Registry Services</ulink>, and
      <ulink url="https://www.tcinet.ru/">Technical Center of Internet</ulink>
      are current sponsors.</para>

80
      <para><ulink url="https://www.afilias.info/">Afilias</ulink>,
81 82
      <ulink url="https://www.iis.se/">IIS.SE</ulink>,
      <ulink url="http://www.nominet.org.uk/">Nominet</ulink>, and
83
      <ulink url="https://www.sidn.nl/">SIDN</ulink> were founding
84 85 86 87
      sponsors of the project.</para>

<!-- DHCP sponsorship by Comcast -->

88 89
      <para>Support for BIND 10 development of the DHCPv4 and DHCPv6
      components is provided by
90
      <ulink url="http://www.comcast.com/">Comcast</ulink>.</para>
91 92 93 94 95

    </section>

  </preface>

96 97 98 99 100
  <chapter id="intro">
    <title>Introduction</title>
    <para>
      BIND is the popular implementation of a DNS server, developer
      interfaces, and DNS tools.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
101 102 103
      BIND 10 is a rewrite of BIND 9 and ISC DHCP.
      BIND 10 is written in C++ and Python and provides a modular
      environment for serving, maintaining, and developing DNS and DHCP.
104 105 106
      BIND 10 provides a EDNS0- and DNSSEC-capable authoritative
      DNS server and a caching recursive name server which also
      provides forwarding.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
107
      It also provides experimental DHCPv4 and DHCPv6 servers.
108 109
    </para>

110
    <para>
111
      This guide covers BIND 10 version &__VERSION__;.
112
    </para>
113

114
    <section>
115 116
      <title>Supported Platforms</title>
      <para>
117
  BIND 10 builds have been tested on (in no particular order)
118
  Debian GNU/Linux 6 and unstable, Ubuntu 9.10, NetBSD 5,
119 120
  Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3,
  MacOS 10.6 and 10.7, and OpenBSD 5.1.
121

122 123
  It has been tested on Sparc, i386, and amd64 hardware
  platforms.
124 125 126 127 128 129

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

130
    <section id="required-software">
131 132 133 134 135 136 137 138 139 140 141
      <title>Required Software at Run-time</title>

      <para>
        Running BIND 10 uses various extra software which may
        not be provided in some operating systems' default
        installations nor standard packages collections. You may
        need to install this required software separately.
        (For the build requirements, also see
        <xref linkend="build-requirements"/>.)
      </para>

142
      <para>
143 144
        BIND 10 requires at least Python 3.1
        (<ulink url="http://www.python.org/"/>).
Jeremy C. Reed's avatar
Jeremy C. Reed committed
145
        It also works with Python 3.2.
146 147 148 149 150 151
      </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.
152 153
      </para>

154
      <para>
155 156 157
        BIND 10 uses the log4cplus C++ logging library
        (<ulink url="http://log4cplus.sourceforge.net/"/>).
        It requires at least log4cplus version 1.0.3.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
158
<!-- TODO: It is recommended to use at least version .... -->
159
      </para>
160

161
      <para>
162 163 164 165
        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.
166
      </para>
167

168
      <para>
169 170 171 172
        The <command>b10-ddns</command>, <command>b10-xfrin</command>,
        <command>b10-xfrout</command>, and <command>b10-zonemgr</command>
        components require the libpython3 library and the Python
        _sqlite3.so module (which is included with Python).
173
        Python modules need to be built for the corresponding Python 3.
174 175
      </para>
<!-- TODO: this will change ... -->
176
    </section>
177

178 179
    <section id="starting_stopping">
      <title>Starting and Stopping the Server</title>
180

181 182 183
      <para>
        BIND 10 is modular.  Part of this modularity is
        accomplished using multiple cooperating processes which, together,
184 185 186
        provide the server functionality.  This is a change from
        the previous generation of BIND software, which used a
        single process.
187 188 189
      </para>

      <para>
190
        At first, running many different processes may seem confusing.
191 192 193 194 195 196
        However, these processes are started by running a single
	command, <command>bind10</command>.  This command starts
	a master process, <command>b10-init</command>, which will
	start other required processes and other processes when
	configured.  The processes that may be started have names
	starting with "b10-", including:
197
      </para>
198

199
      <para>
200

201
        <itemizedlist>
202

203 204 205
          <listitem>
            <simpara>
              <command>b10-auth</command> &mdash;
206
              Authoritative DNS server.
207
              This process serves DNS requests.
208 209
            </simpara>
          </listitem>
210

211 212 213
          <listitem>
            <simpara>
              <command>b10-cfgmgr</command> &mdash;
214
              Configuration manager.
215
              This process maintains all of the configuration for BIND 10.
216 217
            </simpara>
          </listitem>
218

219 220 221
          <listitem>
            <simpara>
              <command>b10-cmdctl</command> &mdash;
222
              Command and control service.
223
              This process allows external control of the BIND 10 system.
224 225
            </simpara>
          </listitem>
226

227 228 229 230 231 232 233 234 235 236
          <listitem>
            <simpara>
              <command>b10-ddns</command> &mdash;
              Dynamic DNS update service.
              This process is used to handle incoming DNS update
              requests to allow granted clients to update zones
	      for which BIND 10 is serving as a primary server.
            </simpara>
          </listitem>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
237 238 239 240 241 242 243 244 245
          <listitem>
            <simpara>
              <command>b10-msgq</command> &mdash;
              Message bus daemon.
              This process coordinates communication between all of the other
              BIND 10 processes.
            </simpara>
          </listitem>

246 247 248 249
          <listitem>
            <simpara>
              <command>b10-resolver</command> &mdash;
              Recursive name server.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
250 251
              This process handles incoming DNS queries and provides
              answers from its cache or by recursively doing remote lookups.
252
              (This is an experimental proof of concept.)
253 254 255
            </simpara>
          </listitem>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
256 257 258 259 260 261 262 263 264
          <listitem>
            <simpara>
              <command>b10-sockcreator</command> &mdash;
              Socket creator daemon.
              This process creates sockets used by
              network-listening BIND 10 processes.
            </simpara>
          </listitem>

265 266 267 268 269 270 271 272
          <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
273 274 275 276 277 278 279 280
          <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>

281 282 283
          <listitem>
            <simpara>
              <command>b10-xfrin</command> &mdash;
284
              Incoming zone transfer service.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
285
              This process is used to transfer a new copy
286
              of a zone into BIND 10, when acting as a secondary server.
287 288
            </simpara>
          </listitem>
289

Jeremy C. Reed's avatar
Jeremy C. Reed committed
290 291 292 293
          <listitem>
            <simpara>
              <command>b10-xfrout</command> &mdash;
              Outgoing zone transfer service.
294
              This process is used to handle transfer requests to
Jeremy C. Reed's avatar
Jeremy C. Reed committed
295
              send a local zone to a remote secondary server.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
296 297 298
            </simpara>
          </listitem>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
299 300 301
          <listitem>
            <simpara>
              <command>b10-zonemgr</command> &mdash;
Jeremy C. Reed's avatar
Jeremy C. Reed committed
302
              Secondary zone manager.
303
              This process keeps track of timers and other
Jeremy C. Reed's avatar
Jeremy C. Reed committed
304 305 306 307
              necessary information for BIND 10 to act as a slave server.
            </simpara>
          </listitem>

308 309
        </itemizedlist>
      </para>
310 311

      <para>
312
        These do not need to be manually started independently.
313 314
      </para>

315
    </section>
316

317 318
    <section id="managing_once_running">
      <title>Managing BIND 10</title>
319

320
      <para>
321 322
        Once BIND 10 is running, a few commands are used to interact
        directly with the system:
323 324 325 326
        <itemizedlist>
          <listitem>
            <simpara>
              <command>bindctl</command> &mdash;
Jeremy C. Reed's avatar
Jeremy C. Reed committed
327
              Interactive administration interface.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
328 329 330
              This is a low-level command-line tool which allows
              a developer or an experienced administrator to control
              BIND 10.
331 332 333 334 335
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <command>b10-loadzone</command> &mdash;
Jeremy C. Reed's avatar
Jeremy C. Reed committed
336
              Zone file loader.
337 338
              This tool will load standard masterfile-format zone files into
              BIND 10.
339 340
            </simpara>
          </listitem>
341 342 343
          <listitem>
            <simpara>
              <command>b10-cmdctl-usermgr</command> &mdash;
Jeremy C. Reed's avatar
Jeremy C. Reed committed
344
              User access control.
345
              This tool allows an administrator to authorize additional users
346
              to manage BIND 10.
347 348
            </simpara>
          </listitem>
349 350 351 352
  <!-- TODO usermgr -->
        </itemizedlist>
      </para>
    </section>
353 354

    <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
355
      The tools and modules are covered in full detail in this guide.
356 357 358
<!-- TODO point to these -->
      In addition, manual pages are also provided in the default installation.
    </para>
359

360 361 362 363 364 365 366 367 368 369 370 371
<!--
bin/
  bindctl*
  host*
lib/
  libauth
  libdns
  libexceptions
  python3.1/site-packages/isc/{cc,config}
sbin/
  bind10
share/
372
  share/bind10/
373 374
    auth.spec
    b10-cmdctl.pem
375
    init.spec
376 377 378 379 380 381 382 383 384 385 386
    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.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
387
<!-- TODO: DHCP also but no Python yet. -->
388 389 390 391 392
<!-- TODO point to this -->
    </para>

  </chapter>

393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429
  <chapter id="quickstart">
    <title>Quick start</title>

    <para>
        This quickly covers the standard steps for installing
        and deploying BIND 10.
        For further details, full customizations, and troubleshooting,
        see the respective chapters in the BIND 10 guide.
    </para>

    <section id="quick-start-auth-dns">
      <title>Quick start guide for authoritative DNS service</title>

      <orderedlist>

        <listitem>
          <simpara>
            Install required run-time and build dependencies.
          </simpara>
        </listitem>

        <listitem>
          <simpara>
            Download the BIND 10 source tar file from
            <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
          </simpara>
        </listitem>

        <listitem>
          <para>Extract the tar file:
          <screen>$ <userinput>gzcat bind10-<replaceable>VERSION</replaceable>.tar.gz | tar -xvf -</userinput></screen>
          </para>
        </listitem>

        <listitem>
          <para>Go into the source and run configure:
            <screen>$ <userinput>cd bind10-<replaceable>VERSION</replaceable></userinput>
Mukund Sivaraman's avatar
Mukund Sivaraman committed
430
$ <userinput>./configure</userinput></screen>
431 432 433 434 435 436 437 438 439 440
          </para>
        </listitem>

        <listitem>
          <para>Build it:
            <screen>$ <userinput>make</userinput></screen>
          </para>
        </listitem>

        <listitem>
441 442
          <para>Install it as root (by default to prefix
          <filename>/usr/local/</filename>):
443 444 445 446
            <screen>$ <userinput>make install</userinput></screen>
          </para>
        </listitem>

447 448 449 450 451 452 453
        <listitem>
          <para>Change directory to the install prefix (by default
          <filename>/usr/local/</filename>):
            <screen>$ <userinput>cd /usr/local/</userinput></screen>
          </para>
        </listitem>

454 455
        <listitem>
          <para>Create a user for yourself:
456
            <screen>$ <userinput>sbin/b10-cmdctl-usermgr add root</userinput></screen>
457
	  and enter a newly chosen password when prompted.
458 459 460
          </para>
        </listitem>

461 462
        <listitem>
          <para>Start the server (as root):
463
            <screen>$ <userinput>sbin/bind10</userinput></screen>
464 465 466 467
          </para>
        </listitem>

        <listitem>
468 469 470 471
          <para>DNS and DHCP components are not started in the default
	    configuration.  In another console, enable the authoritative
	    DNS service (by using the <command>bindctl</command> utility
	    to configure the <command>b10-auth</command> component to
472
	    run): <screen>$ <userinput>bin/bindctl</userinput></screen>
473
	    (Login with the username and password you used above to create a user.)
474
            <screen>
Jelte Jansen's avatar
Jelte Jansen committed
475 476 477
&gt; <userinput>config add Init/components b10-auth</userinput>
&gt; <userinput>config set Init/components/b10-auth/special auth</userinput>
&gt; <userinput>config set Init/components/b10-auth/kind needed</userinput>
478 479 480 481 482 483 484 485 486 487 488 489 490 491
&gt; <userinput>config commit</userinput>
&gt; <userinput>quit</userinput>
            </screen>
          </para>
        </listitem>

        <listitem>
         <para>Test it; for example:
            <screen>$ <userinput>dig @127.0.0.1 -c CH -t TXT version.bind</userinput></screen>
         </para>
        </listitem>

        <listitem>
          <para>Load desired zone file(s), for example:
492
            <screen>$ <userinput>bin/b10-loadzone <replaceable>-c '{"database_file": "/usr/local/var/bind10/zone.sqlite3"}'</replaceable> <replaceable>your.zone.example.org</replaceable> <replaceable>your.zone.file</replaceable></userinput></screen>
493
          </para>
JINMEI Tatuya's avatar
JINMEI Tatuya committed
494 495
	  (If you use the sqlite3 data source with the default DB
	  file, you can omit the -c option).
496 497 498 499 500 501 502 503 504 505 506 507 508 509
        </listitem>

        <listitem>
          <simpara>
            Test the new zone.
          </simpara>
        </listitem>

      </orderedlist>

    </section>

  </chapter>

510 511
  <chapter id="installation">
    <title>Installation</title>
512

513 514 515 516
    <section id="packages">
      <title>Packages</title>

      <para>
517
        Some operating systems or software package vendors may
518 519 520 521 522 523 524 525 526 527 528 529 530 531 532
        provide ready-to-use, pre-built software packages for
        the BIND 10 suite.
        Installing a pre-built package means you do not need to
        install build-only prerequisites and do not need to
        <emphasis>make</emphasis> the software.
      </para>

      <para>
        FreeBSD ports, NetBSD pkgsrc, and Debian
        <emphasis>testing</emphasis> package collections provide
        all the prerequisite packages.
      </para>
    </section>

    <section id="install-hierarchy">
533 534
      <title>Install Hierarchy</title>
      <para>
535 536
        The following is the standard, common layout of the
        complete BIND 10 installation:
537 538 539 540 541 542 543 544 545
        <itemizedlist>
          <listitem>
           <simpara>
              <filename>bin/</filename> &mdash;
              general tools and diagnostic clients.
            </simpara>
          </listitem>
          <listitem>
          <simpara>
546
            <filename>etc/bind10/</filename> &mdash;
547 548 549 550 551 552 553 554 555 556 557
            configuration files.
          </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>lib/</filename> &mdash;
              libraries and python modules.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
558
              <filename>libexec/bind10/</filename> &mdash;
559 560 561
              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
562
              the <command>b10-init</command> master process.
563 564 565 566 567 568 569 570 571 572
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>sbin/</filename> &mdash;
              commands used by the system administrator.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
573
              <filename>share/bind10/</filename> &mdash;
574 575 576 577 578
              configuration specifications.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
579
              <filename>share/doc/bind10/</filename> &mdash;
580 581 582 583 584 585 586 587 588 589 590
              this guide and other supplementary documentation.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>share/man/</filename> &mdash;
              manual pages (online documentation).
            </simpara>
          </listitem>
          <listitem>
            <simpara>
591
              <filename>var/bind10/</filename> &mdash;
592 593 594 595 596 597 598
              data source and configuration databases.
            </simpara>
          </listitem>
        </itemizedlist>
      </para>
    </section>

599
    <section id="build-requirements">
600
      <title>Building Requirements</title>
601 602

        <para>
603 604
          In addition to the run-time requirements (listed in
          <xref linkend="required-software"/>), building BIND 10
Jeremy C. Reed's avatar
Jeremy C. Reed committed
605 606
          from source code requires various development include headers and
          program development tools.
607 608
        </para>

609
        <note>
610
          <simpara>
611 612 613
            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
614
            libraries, to build BIND 10 from source code.
615
          </simpara>
616 617
        </note>

618 619
        <para>
          Building from source code requires the Boost
620 621 622
          build-time headers
          (<ulink url="http://www.boost.org/"/>).
          At least Boost version 1.35 is required.
623 624 625 626
  <!-- 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
627
        <para>
628 629
          To build BIND 10, also install the Botan (at least version
          1.8) and the log4cplus (at least version 1.0.3)
630 631 632 633 634 635 636 637 638
          development include headers.
        </para>

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

639 640
<!-- 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
641

642 643
        <para>
          Building BIND 10 also requires a C++ compiler and
644
          standard development headers, make, and pkg-config.
645
          BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
646
          4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
647
        </para>
648 649

        <para>
650
          Visit the user-contributed wiki at <ulink
651 652 653 654
          url="http://bind10.isc.org/wiki/SystemSpecificNotes" />
          for system-specific installation tips.
        </para>

655 656
    </section>

657 658
    <section id="install">
      <title>Installation from source</title>
659
      <para>
660
        BIND 10 is open source software written in C++ and Python.
661 662 663 664
        It is freely available in source code form from ISC as a
        downloadable tar file or via BIND 10's Git code revision control
        service. (It may also be available in pre-compiled ready-to-use
        packages from operating system vendors.)
665 666
      </para>

667 668
      <section>
        <title>Download Tar File</title>
669 670 671 672
        <para>
          Downloading a release tar file is the recommended method to
          obtain the source code.
        </para>
673

674 675
        <para>
          The BIND 10 releases are available as tar file downloads from
676 677
          <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
          Periodic development snapshots may also be available.
678 679 680 681 682
        </para>
  <!-- TODO -->
      </section>

      <section>
683
        <title>Retrieve from Git</title>
684 685 686 687 688
        <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>
689 690 691

        <note>
          <para>
692
            When using source code retrieved via Git, additional
693
            software will be required:  automake (v1.11 or newer),
694
            libtoolize, and autoconf (2.59 or newer).
695 696 697 698
            These may need to be installed.
          </para>
        </note>

699
        <para>
700 701
          The latest development code (and temporary experiments
          and un-reviewed code) is available via the BIND 10 code revision
702
          control system. This is powered by Git and all the BIND 10
703
          development is public.
704 705
          The leading development is done in the <quote>master</quote>
          branch.
706 707
        </para>
        <para>
708
          The code can be checked out from
709
          <filename>git://git.bind10.isc.org/bind10</filename>;
710
          for example:
711

712
        <screen>$ <userinput>git clone git://git.bind10.isc.org/bind10</userinput></screen>
713
        </para>
714

715 716 717
        <para>
          When checking out the code from
          the code version control system, it doesn't include the
718 719
          generated configure script, Makefile.in files, nor their
          related build files.
720 721 722 723 724 725 726 727 728 729
          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>

730 731 732
      </section>


733
      <section id="configure">
734 735 736 737 738 739 740 741 742
        <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>
743
          switch to view the different options. Some commonly-used options are:
744 745 746 747

          <variablelist>

          <varlistentry>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
748 749
            <term>--prefix</term>
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
750
              <simpara>Define the installation location (the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
751 752
                default is <filename>/usr/local/</filename>).
              </simpara>
753
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
754 755 756 757
          </varlistentry>

          <varlistentry>
            <term>--with-boost-include</term>
758
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
759
              <simpara>Define the path to find the Boost headers.
760
              </simpara>
761
            </listitem>
762 763 764
          </varlistentry>

          <varlistentry>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
765
            <term>--with-pythonpath</term>
766
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
767 768 769
              <simpara>Define the path to Python 3.1 if it is not in the
                standard execution path.
              </simpara>
770
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
771 772 773 774
          </varlistentry>

          <varlistentry>
            <term>--with-gtest</term>
775
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
776 777 778
              <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.
779
              </simpara>
780
            </listitem>
781 782
          </varlistentry>

783 784 785 786 787 788 789 790 791 792
          <varlistentry>
            <term>--without-werror</term>
            <listitem>
              <simpara>Disable the default use of the
		<option>-Werror</option> compiler flag so that
		compiler warnings aren't build failures.
              </simpara>
            </listitem>
          </varlistentry>

793
          </variablelist>
794 795 796 797 798 799
          <note>
            <para>
              For additional instructions concerning the building and installation of
              BIND 10 DHCP, see <xref linkend="dhcp-install-configure"/>.
            </para>
          </note>
800
        </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
801
  <!-- TODO: lcov -->
802 803

        <para>
804
          For example, the following configures it to
805
    find the Boost headers, find the
806
    Python interpreter, and sets the installation location:
807

808
          <screen>$ <userinput>./configure \
809 810 811 812 813 814 815 816 817 818
      --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>

819

820 821 822 823 824
      </section>

      <section>
        <title>Build</title>
        <para>
825 826
    After the configure step is complete, to build the executables
    from the C++ code and prepare the Python scripts, run:
827 828 829 830 831 832 833 834

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

      <section>
        <title>Install</title>
        <para>
Michael Graff's avatar
Michael Graff committed
835 836
          To install the BIND 10 executables, support files,
          and documentation, run:
837 838
          <screen>$ <userinput>make install</userinput></screen>
        </para>
839
        <para>
840 841 842
          Please don't use any form of parallel or job server options
          (such as GNU make's <command>-j</command> option) when
          performing this step. Doing so may cause errors.
843
        </para>
Michael Graff's avatar
Michael Graff committed
844
        <note>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
845
          <para>The install step may require superuser privileges.</para>
Michael Graff's avatar
Michael Graff committed
846
        </note>
847
        <para>
848 849 850 851
	  If required, run <command>ldconfig</command> as root with
	  <filename>/usr/local/lib</filename> (or with ${prefix}/lib if
	  configured with --prefix) in
	  <filename>/etc/ld.so.conf</filename> (or the relevant linker
852 853
	  cache configuration file for your OS):
	  <screen>$ <userinput>ldconfig</userinput></screen>
854 855 856 857 858 859 860 861 862 863 864
        </para>
        <note>
          <para>
	    If you do not run <command>ldconfig</command> where it is
	    required, you may see errors like the following:
            <screen>
	      program: error while loading shared libraries: libb10-something.so.1:
	      cannot open shared object file: No such file or directory
	    </screen>
	  </para>
        </note>
865 866 867 868 869 870 871 872 873 874 875 876 877
      </section>

  <!-- TODO: tests -->

    </section>

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

879
  </chapter>
880

881
  <chapter id="bind10">
Jeremy C. Reed's avatar
Jeremy C. Reed committed
882
    <title>Starting BIND 10 with <command>bind10</command></title>
883
    <para>
884 885 886
      BIND 10 is started with the <command>bind10</command> command.
      It runs the <command>b10-init</command> daemon which
      starts up the required processes, and
887
      will also restart some processes that exit unexpectedly.
888 889
      <command>bind10</command> is the only command needed to start
      the BIND 10 system.
890 891 892
    </para>

    <para>
893
      After starting the <command>b10-msgq</command> communications channel,
894
      <command>b10-init</command> connects to it,
895 896
      runs the configuration manager, and reads its own configuration.
      Then it starts the other modules.
897 898 899
    </para>

    <para>
900 901
      The <command>b10-sockcreator</command>, <command>b10-msgq</command> and
      <command>b10-cfgmgr</command>
902
      services make up the core. The <command>b10-msgq</command> daemon
903
      provides the communication channel between every part of the system.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
904
      The <command>b10-cfgmgr</command> daemon is always needed by every
905 906
      module, if only to send information about themselves somewhere,
      but more importantly to ask about their own settings, and
907 908 909
      about other modules. The <command>b10-sockcreator</command> daemon
      helps allocate Internet addresses and ports as needed for BIND 10
      network services.
910 911 912
    </para>

    <para>
913
      In its default configuration, the <command>b10-init</command>
914
      master process will also start up
Jeremy C. Reed's avatar
Jeremy C. Reed committed
915
      <command>b10-cmdctl</command> for administration tools to
916 917
      communicate with the system, and
      <command>b10-stats</command> for statistics collection.
918
      The DNS and DHCP servers are not started by default.
919 920
      The configuration of components to start is covered in
      <xref linkend="bind10.components"/>.
921 922
    </para>

923
    <section id="start">
924 925
      <title>Starting BIND 10</title>
      <para>
926 927 928 929 930
        To start the BIND 10 service, simply run <command>bind10</command>
        as root.
        It will run in the foreground and your shell prompt will not
        be available. It will output various log messages as it starts up
        and is used.
931
        Run it with the <option>--verbose</option> switch to
932 933
        get additional debugging or diagnostic output.
      </para>
934 935 936 937

<!-- TODO: user switch -->

<!-- TODO:  example:  nohup /usr/local/sbin/bind10 1>bind10.log 2>&1 -->
938 939 940 941 942 943 944 945 946 947

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

948
    </section>
949 950 951

  </chapter>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
952 953 954 955
  <chapter id="msgq">
    <title>Command channel</title>

      <para>
956
        The BIND 10 components use the <command>b10-msgq</command>
Michael Graff's avatar
Michael Graff committed
957
        message routing daemon to communicate with other BIND 10 components.
958
        The <command>b10-msgq</command> implements what is called the
Michael Graff's avatar
Michael Graff committed
959 960 961 962 963
        <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
964
        This Command Channel is not used for DNS message passing.
Michael Graff's avatar
Michael Graff committed
965 966
        It is used only to control and monitor the BIND 10 system.
      </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
967 968 969

      <para>
        Administrators do not communicate directly with the
970
        <command>b10-msgq</command> daemon.
971
        By default, BIND 10 uses a UNIX domain socket file named
972
        <filename>/usr/local/var/bind10/msg_socket</filename>
973
        for this interprocess communication.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
974
      </para>
975

Jeremy C. Reed's avatar
Jeremy C. Reed committed
976 977
  </chapter>

978 979 980 981
  <chapter id="cfgmgr">
    <title>Configuration manager</title>

      <para>
Michael Graff's avatar
Michael Graff committed
982 983 984 985 986
         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>
987 988

      <para>
Michael Graff's avatar
Michael Graff committed
989 990
        The <command>b10-auth</command> and <command>b10-xfrin</command>
        daemons and other components receive their configurations
991
        from the configuration manager over the <command>b10-msgq</command>
Michael Graff's avatar
Michael Graff committed
992
        command channel.
993 994
      </para>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
995 996 997 998
      <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"/>.
999 1000 1001
      </para>

<!-- TODO -->
Michael Graff's avatar
Michael Graff committed
1002 1003
      <note>
        <para>
1004
          The current release only provides
Michael Graff's avatar
Michael Graff committed
1005 1006 1007 1008 1009 1010
          <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>
1011 1012 1013 1014

      <para>
        The <command>b10-cfgmgr</command> daemon can send all
        specifications and all current settings to the
Michael Graff's avatar
Michael Graff committed
1015 1016
        <command>bindctl</command> client (via
        <command>b10-cmdctl</command>).
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033
        <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
1034
        <filename>/usr/local/var/bind10/b10-config.db</filename>.
1035
        (The directory is what was defined at build configure time for
1036 1037
        <option>--localstatedir</option>.
        The default is <filename>/usr/local/var/</filename>.)
Michael Graff's avatar
Michael Graff committed
1038 1039 1040 1041
        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
1042
      </para>
1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057

<!--

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

-->
1058 1059

    <para>
1060 1061
      The configuration manager does not have any command line arguments.
      Normally it is not started manually, but is automatically
1062
      started using the <command>b10-init</command> master process
1063 1064 1065 1066 1067 1068
      (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
1069 1070 1071