bind10-guide.xml 226 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
      <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
42
      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
  <preface>
    <title>Preface</title>

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

Jeremy C. Reed's avatar
Jeremy C. Reed committed
62
63
<!-- TODO: acknowledge all sponsors and CNNIC and CZNIC too -->

64
65
66
67
68
69
70
71
      <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>

72
73
74
75
76
  <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
77
78
79
      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.
80
81
82
      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
83
      It also provides experimental DHCPv4 and DHCPv6 servers.
84
85
    </para>

86
    <para>
87
      This guide covers BIND 10 version &__VERSION__;.
88
    </para>
89

90
    <section>
91
92
      <title>Supported Platforms</title>
      <para>
93
  BIND 10 builds have been tested on (in no particular order)
94
  Debian GNU/Linux 6 and unstable, Ubuntu 9.10, NetBSD 5,
95
96
  Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3,
  MacOS 10.6 and 10.7, and OpenBSD 5.1.
97

98
99
  It has been tested on Sparc, i386, and amd64 hardware
  platforms.
100
101
102
103
104
105

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

106
    <section id="required-software">
107
108
109
110
111
112
113
114
115
116
117
      <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>

118
      <para>
119
120
        BIND 10 requires at least Python 3.1
        (<ulink url="http://www.python.org/"/>).
Jeremy C. Reed's avatar
Jeremy C. Reed committed
121
        It also works with Python 3.2.
122
123
124
125
126
127
      </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.
128
129
      </para>

130
      <para>
131
132
133
        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
134
<!-- TODO: It is recommended to use at least version .... -->
135
      </para>
136

137
      <para>
138
139
140
141
        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.
142
      </para>
143

144
      <para>
145
146
147
148
        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).
149
        Python modules need to be built for the corresponding Python 3.
150
151
      </para>
<!-- TODO: this will change ... -->
152
    </section>
153

154
155
    <section id="starting_stopping">
      <title>Starting and Stopping the Server</title>
156

157
158
159
      <para>
        BIND 10 is modular.  Part of this modularity is
        accomplished using multiple cooperating processes which, together,
160
161
162
        provide the server functionality.  This is a change from
        the previous generation of BIND software, which used a
        single process.
163
164
165
      </para>

      <para>
166
167
168
169
        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
170
171
        required processes and other processes when configured.
        The processes that may be started by the <command>bind10</command>
172
        command have names starting with "b10-", including:
173
      </para>
174

175
      <para>
176

177
        <itemizedlist>
178

179
180
181
          <listitem>
            <simpara>
              <command>b10-auth</command> &mdash;
182
              Authoritative DNS server.
183
              This process serves DNS requests.
184
185
            </simpara>
          </listitem>
186

187
188
189
          <listitem>
            <simpara>
              <command>b10-cfgmgr</command> &mdash;
190
              Configuration manager.
191
              This process maintains all of the configuration for BIND 10.
192
193
            </simpara>
          </listitem>
194

195
196
197
          <listitem>
            <simpara>
              <command>b10-cmdctl</command> &mdash;
198
              Command and control service.
199
              This process allows external control of the BIND 10 system.
200
201
            </simpara>
          </listitem>
202

203
204
205
206
207
208
209
210
211
212
          <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
213
214
215
216
217
218
219
220
221
          <listitem>
            <simpara>
              <command>b10-msgq</command> &mdash;
              Message bus daemon.
              This process coordinates communication between all of the other
              BIND 10 processes.
            </simpara>
          </listitem>

222
223
224
225
          <listitem>
            <simpara>
              <command>b10-resolver</command> &mdash;
              Recursive name server.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
226
227
              This process handles incoming DNS queries and provides
              answers from its cache or by recursively doing remote lookups.
228
229
230
            </simpara>
          </listitem>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
231
232
233
234
235
236
237
238
239
          <listitem>
            <simpara>
              <command>b10-sockcreator</command> &mdash;
              Socket creator daemon.
              This process creates sockets used by
              network-listening BIND 10 processes.
            </simpara>
          </listitem>

240
241
242
243
244
245
246
247
          <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
248
249
250
251
252
253
254
255
          <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>

256
257
258
          <listitem>
            <simpara>
              <command>b10-xfrin</command> &mdash;
259
              Incoming zone transfer service.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
260
              This process is used to transfer a new copy
261
              of a zone into BIND 10, when acting as a secondary server.
262
263
            </simpara>
          </listitem>
264

Jeremy C. Reed's avatar
Jeremy C. Reed committed
265
266
267
268
          <listitem>
            <simpara>
              <command>b10-xfrout</command> &mdash;
              Outgoing zone transfer service.
269
              This process is used to handle transfer requests to
Jeremy C. Reed's avatar
Jeremy C. Reed committed
270
              send a local zone to a remote secondary server.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
271
272
273
            </simpara>
          </listitem>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
274
275
276
          <listitem>
            <simpara>
              <command>b10-zonemgr</command> &mdash;
Jeremy C. Reed's avatar
Jeremy C. Reed committed
277
              Secondary zone manager.
278
              This process keeps track of timers and other
Jeremy C. Reed's avatar
Jeremy C. Reed committed
279
280
281
282
              necessary information for BIND 10 to act as a slave server.
            </simpara>
          </listitem>

283
284
        </itemizedlist>
      </para>
285
286

      <para>
287
        These do not need to be manually started independently.
288
289
      </para>

290
    </section>
291

292
293
    <section id="managing_once_running">
      <title>Managing BIND 10</title>
294

295
      <para>
296
297
        Once BIND 10 is running, a few commands are used to interact
        directly with the system:
298
299
300
301
        <itemizedlist>
          <listitem>
            <simpara>
              <command>bindctl</command> &mdash;
Jeremy C. Reed's avatar
Jeremy C. Reed committed
302
              Interactive administration interface.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
303
304
305
              This is a low-level command-line tool which allows
              a developer or an experienced administrator to control
              BIND 10.
306
307
308
309
310
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <command>b10-loadzone</command> &mdash;
Jeremy C. Reed's avatar
Jeremy C. Reed committed
311
              Zone file loader.
312
313
              This tool will load standard masterfile-format zone files into
              BIND 10.
314
315
            </simpara>
          </listitem>
316
317
318
          <listitem>
            <simpara>
              <command>b10-cmdctl-usermgr</command> &mdash;
Jeremy C. Reed's avatar
Jeremy C. Reed committed
319
              User access control.
320
              This tool allows an administrator to authorize additional users
321
              to manage BIND 10.
322
323
            </simpara>
          </listitem>
324
325
326
327
  <!-- TODO usermgr -->
        </itemizedlist>
      </para>
    </section>
328
329

    <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
330
      The tools and modules are covered in full detail in this guide.
331
332
333
<!-- TODO point to these -->
      In addition, manual pages are also provided in the default installation.
    </para>
334

335
336
337
338
339
340
341
342
343
344
345
346
<!--
bin/
  bindctl*
  host*
lib/
  libauth
  libdns
  libexceptions
  python3.1/site-packages/isc/{cc,config}
sbin/
  bind10
share/
347
  share/bind10/
348
349
350
351
352
353
354
355
356
357
358
359
360
361
    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.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
362
<!-- TODO: DHCP also but no Python yet. -->
363
364
365
366
367
<!-- TODO point to this -->
    </para>

  </chapter>

368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
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
  <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>
  $ <userinput>./configure</userinput></screen>
          </para>
        </listitem>

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

        <listitem>
          <para>Install it as root (to default /usr/local):
            <screen>$ <userinput>make install</userinput></screen>
          </para>
        </listitem>

        <listitem>
          <para>Start the server (as root):
            <screen>$ <userinput>/usr/local/sbin/bind10</userinput></screen>
          </para>
        </listitem>

        <listitem>
428
429
430
431
432
433
          <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
	    run): <screen>$ <userinput>bindctl</userinput></screen>
	    (Login with the provided default username and password.)
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
            <screen>
&gt; <userinput>config add Boss/components b10-auth</userinput>
&gt; <userinput>config set Boss/components/b10-auth/special auth</userinput>
&gt; <userinput>config set Boss/components/b10-auth/kind needed</userinput>
&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:
452
            <screen>$ <userinput>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>
453
          </para>
JINMEI Tatuya's avatar
JINMEI Tatuya committed
454
455
	  (If you use the sqlite3 data source with the default DB
	  file, you can omit the -c option).
456
457
458
459
460
461
462
463
464
465
466
467
468
469
        </listitem>

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

      </orderedlist>

    </section>

  </chapter>

470
471
  <chapter id="installation">
    <title>Installation</title>
472

473
474
475
476
    <section id="packages">
      <title>Packages</title>

      <para>
477
        Some operating systems or software package vendors may
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
        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">
493
494
      <title>Install Hierarchy</title>
      <para>
495
496
        The following is the standard, common layout of the
        complete BIND 10 installation:
497
498
499
500
501
502
503
504
505
        <itemizedlist>
          <listitem>
           <simpara>
              <filename>bin/</filename> &mdash;
              general tools and diagnostic clients.
            </simpara>
          </listitem>
          <listitem>
          <simpara>
506
            <filename>etc/bind10/</filename> &mdash;
507
508
509
510
511
512
513
514
515
516
517
            configuration files.
          </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>lib/</filename> &mdash;
              libraries and python modules.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
518
              <filename>libexec/bind10/</filename> &mdash;
519
520
521
522
523
524
525
526
527
528
529
530
531
532
              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>
533
              <filename>share/bind10/</filename> &mdash;
534
535
536
537
538
              configuration specifications.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
539
              <filename>share/doc/bind10/</filename> &mdash;
540
541
542
543
544
545
546
547
548
549
550
              this guide and other supplementary documentation.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>share/man/</filename> &mdash;
              manual pages (online documentation).
            </simpara>
          </listitem>
          <listitem>
            <simpara>
551
              <filename>var/bind10/</filename> &mdash;
552
553
554
555
556
557
558
              data source and configuration databases.
            </simpara>
          </listitem>
        </itemizedlist>
      </para>
    </section>

559
    <section id="build-requirements">
560
      <title>Building Requirements</title>
561
562

        <para>
563
564
          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
565
566
          from source code requires various development include headers and
          program development tools.
567
568
        </para>

569
        <note>
570
          <simpara>
571
572
573
            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
574
            libraries, to build BIND 10 from source code.
575
          </simpara>
576
577
        </note>

578
579
        <para>
          Building from source code requires the Boost
580
581
582
          build-time headers
          (<ulink url="http://www.boost.org/"/>).
          At least Boost version 1.35 is required.
583
584
585
586
  <!-- 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
587
        <para>
588
589
          To build BIND 10, also install the Botan (at least version
          1.8) and the log4cplus (at least version 1.0.3)
590
591
592
593
594
595
596
597
598
          development include headers.
        </para>

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

599
600
<!-- 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
601

602
603
        <para>
          Building BIND 10 also requires a C++ compiler and
604
          standard development headers, make, and pkg-config.
605
          BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
606
          4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
607
        </para>
608
609

        <para>
610
          Visit the user-contributed wiki at <ulink
611
612
613
614
          url="http://bind10.isc.org/wiki/SystemSpecificNotes" />
          for system-specific installation tips.
        </para>

615
616
    </section>

617
618
    <section id="install">
      <title>Installation from source</title>
619
      <para>
620
        BIND 10 is open source software written in C++ and Python.
621
622
623
624
        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.)
625
626
      </para>

627
628
      <section>
        <title>Download Tar File</title>
629
630
631
632
        <para>
          Downloading a release tar file is the recommended method to
          obtain the source code.
        </para>
633

634
635
        <para>
          The BIND 10 releases are available as tar file downloads from
636
637
          <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
          Periodic development snapshots may also be available.
638
639
640
641
642
        </para>
  <!-- TODO -->
      </section>

      <section>
643
        <title>Retrieve from Git</title>
644
645
646
647
648
        <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>
649
650
651

        <note>
          <para>
652
            When using source code retrieved via Git, additional
653
            software will be required:  automake (v1.11 or newer),
654
            libtoolize, and autoconf (2.59 or newer).
655
656
657
658
            These may need to be installed.
          </para>
        </note>

659
        <para>
660
661
          The latest development code (and temporary experiments
          and un-reviewed code) is available via the BIND 10 code revision
662
          control system. This is powered by Git and all the BIND 10
663
          development is public.
664
665
          The leading development is done in the <quote>master</quote>
          branch.
666
667
        </para>
        <para>
668
          The code can be checked out from
669
          <filename>git://git.bind10.isc.org/bind10</filename>;
670
          for example:
671

672
        <screen>$ <userinput>git clone git://git.bind10.isc.org/bind10</userinput></screen>
673
        </para>
674

675
676
677
        <para>
          When checking out the code from
          the code version control system, it doesn't include the
678
679
          generated configure script, Makefile.in files, nor their
          related build files.
680
681
682
683
684
685
686
687
688
689
          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>

690
691
692
      </section>


693
      <section id="configure">
694
695
696
697
698
699
700
701
702
        <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>
703
          switch to view the different options. Some commonly-used options are:
704
705
706
707

          <variablelist>

          <varlistentry>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
708
709
            <term>--prefix</term>
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
710
              <simpara>Define the installation location (the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
711
712
                default is <filename>/usr/local/</filename>).
              </simpara>
713
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
714
715
716
717
          </varlistentry>

          <varlistentry>
            <term>--with-boost-include</term>
718
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
719
              <simpara>Define the path to find the Boost headers.
720
              </simpara>
721
            </listitem>
722
723
724
          </varlistentry>

          <varlistentry>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
725
            <term>--with-pythonpath</term>
726
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
727
728
729
              <simpara>Define the path to Python 3.1 if it is not in the
                standard execution path.
              </simpara>
730
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
731
732
733
734
          </varlistentry>

          <varlistentry>
            <term>--with-gtest</term>
735
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
736
737
738
              <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.
739
              </simpara>
740
            </listitem>
741
742
          </varlistentry>

743
744
745
746
747
748
749
750
751
          <varlistentry>
            <term>--with-dhcp-mysql</term>
            <listitem>
              <simpara>Enable MySQL support for BIND 10 DHCP. For notes on configuring
              and building DHCP with MySQL see <xref linkend="dhcp-install-configure">.</xref>
              </simpara>
            </listitem>
          </varlistentry>

752
753
754
          </variablelist>

        </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
755
  <!-- TODO: lcov -->
756
757

        <para>
758
          For example, the following configures it to
759
    find the Boost headers, find the
760
    Python interpreter, and sets the installation location:
761

762
          <screen>$ <userinput>./configure \
763
764
765
766
767
768
769
770
771
772
      --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>

773

774
775
776
777
778
      </section>

      <section>
        <title>Build</title>
        <para>
779
780
    After the configure step is complete, to build the executables
    from the C++ code and prepare the Python scripts, run:
781
782
783
784
785
786
787
788

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

      <section>
        <title>Install</title>
        <para>
Michael Graff's avatar
Michael Graff committed
789
790
          To install the BIND 10 executables, support files,
          and documentation, run:
791
792
          <screen>$ <userinput>make install</userinput></screen>
        </para>
Michael Graff's avatar
Michael Graff committed
793
        <note>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
794
          <para>The install step may require superuser privileges.</para>
Michael Graff's avatar
Michael Graff committed
795
        </note>
796
        <para>
797
798
799
800
	  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
801
802
	  cache configuration file for your OS):
	  <screen>$ <userinput>ldconfig</userinput></screen>
803
804
805
806
807
808
809
810
811
812
813
        </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>
814
815
816
817
818
819
820
821
822
823
824
825
826
      </section>

  <!-- TODO: tests -->

    </section>

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

828
  </chapter>
829

830
  <chapter id="bind10">
Jeremy C. Reed's avatar
Jeremy C. Reed committed
831
    <title>Starting BIND 10 with <command>bind10</command></title>
832
    <para>
833
      BIND 10 provides the <command>bind10</command> command which
Michael Graff's avatar
Michael Graff committed
834
835
      starts up the required processes.
      <command>bind10</command>
836
      will also restart some processes that exit unexpectedly.
Michael Graff's avatar
Michael Graff committed
837
      This is the only command needed to start the BIND 10 system.
838
839
840
    </para>

    <para>
841
      After starting the <command>b10-msgq</command> communications channel,
842
      <command>bind10</command> connects to it,
843
844
      runs the configuration manager, and reads its own configuration.
      Then it starts the other modules.
845
846
847
    </para>

    <para>
848
849
      The <command>b10-sockcreator</command>, <command>b10-msgq</command> and
      <command>b10-cfgmgr</command>
850
      services make up the core. The <command>b10-msgq</command> daemon
851
      provides the communication channel between every part of the system.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
852
      The <command>b10-cfgmgr</command> daemon is always needed by every
853
854
      module, if only to send information about themselves somewhere,
      but more importantly to ask about their own settings, and
855
856
857
      about other modules. The <command>b10-sockcreator</command> daemon
      helps allocate Internet addresses and ports as needed for BIND 10
      network services.
858
859
860
861
862
    </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
863
      <command>b10-cmdctl</command> for administration tools to
864
865
      communicate with the system, and
      <command>b10-stats</command> for statistics collection.
866
      The DNS and DHCP servers are not started by default.
867
868
      The configuration of components to start is covered in
      <xref linkend="bind10.components"/>.
869
870
    </para>

871
    <section id="start">
872
873
      <title>Starting BIND 10</title>
      <para>
874
875
876
877
878
        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.
879
        Run it with the <option>--verbose</option> switch to
880
881
        get additional debugging or diagnostic output.
      </para>
882
883
884
885

<!-- TODO: user switch -->

<!-- TODO:  example:  nohup /usr/local/sbin/bind10 1>bind10.log 2>&1 -->
886
887
888
889
890
891
892
893
894
895

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

896
    </section>
897
898
899

  </chapter>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
900
901
902
903
  <chapter id="msgq">
    <title>Command channel</title>

      <para>
904
        The BIND 10 components use the <command>b10-msgq</command>
Michael Graff's avatar
Michael Graff committed
905
        message routing daemon to communicate with other BIND 10 components.
906
        The <command>b10-msgq</command> implements what is called the
Michael Graff's avatar
Michael Graff committed
907
908
909
910
911
        <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
912
        This Command Channel is not used for DNS message passing.
Michael Graff's avatar
Michael Graff committed
913
914
        It is used only to control and monitor the BIND 10 system.
      </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
915
916
917

      <para>
        Administrators do not communicate directly with the
918
        <command>b10-msgq</command> daemon.
919
        By default, BIND 10 uses a UNIX domain socket file named
920
        <filename>/usr/local/var/bind10/msg_socket</filename>
921
        for this interprocess communication.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
922
      </para>
923

Jeremy C. Reed's avatar
Jeremy C. Reed committed
924
925
  </chapter>

926
927
928
929
  <chapter id="cfgmgr">
    <title>Configuration manager</title>

      <para>
Michael Graff's avatar
Michael Graff committed
930
931
932
933
934
         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>
935
936

      <para>
Michael Graff's avatar
Michael Graff committed
937
938
        The <command>b10-auth</command> and <command>b10-xfrin</command>
        daemons and other components receive their configurations
939
        from the configuration manager over the <command>b10-msgq</command>
Michael Graff's avatar
Michael Graff committed
940
        command channel.
941
942
      </para>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
943
944
945
946
      <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"/>.
947
948
949
      </para>

<!-- TODO -->
Michael Graff's avatar
Michael Graff committed
950
951
      <note>
        <para>
952
          The current release only provides
Michael Graff's avatar
Michael Graff committed
953
954
955
956
957
958
          <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>
959
960
961
962

      <para>
        The <command>b10-cfgmgr</command> daemon can send all
        specifications and all current settings to the
Michael Graff's avatar
Michael Graff committed
963
964
        <command>bindctl</command> client (via
        <command>b10-cmdctl</command>).
Jeremy C. Reed's avatar
Jeremy C. Reed committed
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
        <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
982
        <filename>/usr/local/var/bind10/b10-config.db</filename>.
983
        (The directory is what was defined at build configure time for
984
985
        <option>--localstatedir</option>.
        The default is <filename>/usr/local/var/</filename>.)
Michael Graff's avatar
Michael Graff committed
986
987
988
989
        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
990
      </para>
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005

<!--

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

-->
1006
1007

    <para>
1008
1009
1010
1011
1012
1013
1014
1015
1016
      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
1017
1018
1019
1020
1021
1022
1023
-->

<!-- 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
1024
1025
1026
1027
1028
1029
1030
-->

  </chapter>

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

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1031
1032
1033
1034
1035
1036
1037
1038
    <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>
1039
1040
<!-- TODO: copy examples from wiki, try with wget -->

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1041
    <para>
1042
      When <command>b10-cmdctl</command> starts, it firsts
1043
1044
      asks <command>b10-cfgmgr</command> about what modules are
      running and what their configuration is (over the
1045
      <command>b10-msgq</command> channel). Then it will start listening
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1046
1047
1048
1049
1050
1051
1052
1053
1054
      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.
1055
    </para>
1056

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
<!--
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
-->

1070
1071
<!-- TODO: replace /usr/local -->
<!-- TODO: permissions -->
1072
1073
1074
    <para>The HTTPS server requires a private key,
      such as a RSA PRIVATE KEY.
      The default location is at
1075
      <filename>/usr/local/etc/bind10/cmdctl-keyfile.pem</filename>.
1076
      (A sample key is at
1077
      <filename>/usr/local/share/bind10/cmdctl-keyfile.pem</filename>.)
1078
      It also uses a certificate located at
1079
      <filename>/usr/local/etc/bind10/cmdctl-certfile.pem</filename>.
1080
      (A sample certificate is at
1081
      <filename>/usr/local/share/bind10/cmdctl-certfile.pem</filename>.)
1082
      This may be a self-signed certificate or purchased from a
1083
1084
      certification authority.
    </para>
1085
1086

    <note><para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1087
1088
1089
1090
1091
      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
1092
      a certificate needs to be first received from the BIND 10
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1093
1094
      administrator.
      The BIND 10 installation provides a sample PEM bundle that matches
1095
1096
1097
      the sample key and certificate.
    </para></note>
<!-- TODO: cross-ref -->
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1098
1099
1100

<!-- TODO
openssl req -new -x509 -keyout server.pem -out server.pem -days 365 -nodes
1101
but that is a single file, maybe this should go back to that format?
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1102
-->
1103
1104
1105
1106
1107
1108
1109

<!--
    <para>
(08:20:56) shane: It is in theory possible to run without cmdctl.
(08:21:02) shane: I think we discussed this.
    </para>
-->
1110
1111
1112
1113
1114
1115
1116

<!-- TODO: Please check https://bind10.isc.org/wiki/cmd-ctrld -->


    <para>
      The <command>b10-cmdctl</command> daemon also requires
      the user account file located at
1117
      <filename>/usr/local/etc/bind10/cmdctl-accounts.csv</filename>.
1118
1119
1120
      This comma-delimited file lists the accounts with a user name,
      hashed password, and salt.
      (A sample file is at
1121
      <filename>/usr/local/share/bind10/cmdctl-accounts.csv</filename>.
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
      It contains the user named <quote>root</quote> with the password
      <quote>bind10</quote>.)
    </para>

    <para>
      The administrator may create a user account with the
      <command>b10-cmdctl-usermgr</command> tool.
    </para>
<!-- TODO: show example -->

<!-- TODO: does cmdctl need to be restarted to change cert or key
or accounts database -->

    <para>
      By default the HTTPS server listens on the localhost port 8080.
1137
1138
      The port can be set by using the <option>--port</option> command line option.
      The address to listen on can be set using the <option>--address</option> command
1139
      line argument.
1140
      Each HTTPS connection is stateless and times out in 1200 seconds
1141
      by default.  This can be
1142
      redefined by using the <option>--idle-timeout</option> command line argument.
1143
1144
    </para>

1145
    <section id="cmdctl.spec">
1146
      <title>Configuration specification for b10-cmdctl</title>
1147
      <para>
1148
        The configuration items for <command>b10-cmdctl</command> are:
1149
1150
        <varname>accounts_file</varname> which defines the path to the
        user accounts database (the default is
1151
        <filename>/usr/local/etc/bind10/cmdctl-accounts.csv</filename>);
1152
1153
        <varname>cert_file</varname> which defines the path to the
        PEM certificate file (the default is
1154
        <filename>/usr/local/etc/bind10/cmdctl-certfile.pem</filename>);
1155
1156
1157
        and
	<varname>key_file</varname> which defines the path to the
	PEM private key file (the default is
1158
        <filename>/usr/local/etc/bind10/cmdctl-keyfile.pem</filename>).
1159
      </para>
1160

1161
    </section>
1162
1163
1164

<!--
TODO
1165
(12:21:30) jinmei: I'd like to have sample session using a command line www client such as wget
1166
1167
-->

1168
1169
  </chapter>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1170
1171
1172
1173
  <chapter id="bindctl">
    <title>Control and configure user interface</title>

    <note><para>
1174
      For the current release, <command>bindctl</command>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1175
1176
1177
1178
1179
1180
      is the only user interface. It is expected that upcoming
      releases will provide another interactive command-line
      interface and a web-based interface for controlling and
      configuring BIND 10.
    </para></note>

Jelte Jansen's avatar
Jelte Jansen committed
1181
1182
1183
1184
1185
1186
1187
1188
    <note><para>
      <command>bindctl</command> has an internal command history, as
      well as tab-completion for most of the commands and arguments.
      However, these are only enabled if the python readline module
      is available on the system. If not, neither of these
      features will be supported.
    </para></note>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1189
1190
1191
1192
    <para>
      The <command>bindctl</command> tool provides an interactive
      prompt for configuring, controlling, and querying the BIND 10
      components.
1193
      It communicates directly with a REST-ful interface over HTTPS
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1194
1195
1196
1197
      provided by <command>b10-cmdctl</command>. It doesn't
      communicate to any other components directly.
    </para>

1198
1199
1200
1201
    <section id="bindctl_commandline_options">
        <title>bindctl command-line options</title>
        <variablelist>
          <varlistentry>
1202
            <term>-a <replaceable>&lt;address&gt;</replaceable>, --address=<replaceable>&lt;address&gt;</replaceable></term>
1203
1204
            <listitem>
              <simpara>
1205
1206
                  IP address that BIND 10's <command>b10-cmdctl</command>
                  module is listening on. By default, this is 127.0.0.1.
1207
1208
1209
1210
              </simpara>
            </listitem>
          </varlistentry>
          <varlistentry>
1211
            <term>-c <replaceable>&lt;certificate file&gt;</replaceable>, --certificate-chain=<replaceable>&lt;certificate file&gt;</replaceable></term>
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
            <listitem>
              <simpara>
                  PEM-formatted server certificate file. When this option is
                  given, <command>bindctl</command> will verify the server
                  certificate using the given file as the root of the
                  certificate chain. If not specified, <command>bindctl
                  </command> does not validate the certificate.
              </simpara>
            </listitem>
          </varlistentry>
          <varlistentry>
1223
            <term>--csv-file-dir=<replaceable>&lt;csv file&gt;</replaceable></term>
1224
1225
1226
            <listitem>
              <simpara>
                  <command>bindctl</command> stores the username and