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

<!--
Jeremy C. Reed's avatar
Jeremy C. Reed committed
10
 - Copyright (C) 2010-2012  Internet Systems Consortium, Inc. ("ISC")
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 -
 - Permission to use, copy, modify, and/or distribute this software for any
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 -
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
-->

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

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

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

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

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

54
55
  </bookinfo>

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

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

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

    </section>

  </preface>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

169
      <para>
170

171
        <itemizedlist>
172

173
174
          <listitem>
            <simpara>
175
              <command>b10-msgq</command> &mdash;
176
              Message bus daemon.
177
178
              This process coordinates communication between all of the other
              BIND 10 processes.
179
180
            </simpara>
          </listitem>
181

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

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

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

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

215
216
217
218
219
220
221
222
          <listitem>
            <simpara>
              <command>b10-stats</command> &mdash;
              Statistics collection daemon.
              This process collects and reports statistics data.
            </simpara>
          </listitem>

223
224
225
          <listitem>
            <simpara>
              <command>b10-xfrin</command> &mdash;
226
              Incoming zone transfer service.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
227
              This process is used to transfer a new copy
228
              of a zone into BIND 10, when acting as a secondary server.
229
230
            </simpara>
          </listitem>
231

Jeremy C. Reed's avatar
Jeremy C. Reed committed
232
233
234
235
          <listitem>
            <simpara>
              <command>b10-xfrout</command> &mdash;
              Outgoing zone transfer service.
236
237
238
              This process is used to handle transfer requests to
              send a local zone to a remote secondary server,
              when acting as a master server.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
239
240
241
            </simpara>
          </listitem>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
242
243
244
245
          <listitem>
            <simpara>
              <command>b10-zonemgr</command> &mdash;
              Secondary manager.
246
              This process keeps track of timers and other
Jeremy C. Reed's avatar
Jeremy C. Reed committed
247
248
249
250
              necessary information for BIND 10 to act as a slave server.
            </simpara>
          </listitem>

251
252
        </itemizedlist>
      </para>
253
254

      <para>
255
256
        These are ran automatically by <command>bind10</command>
        and do not need to be run manually.
257
258
      </para>

259
    </section>
260

261
262
    <section id="managing_once_running">
      <title>Managing BIND 10</title>
263

264
      <para>
265
266
        Once BIND 10 is running, a few commands are used to interact
        directly with the system:
267
268
269
270
        <itemizedlist>
          <listitem>
            <simpara>
              <command>bindctl</command> &mdash;
271
272
273
              interactive administration interface.
              This is a command-line tool which allows an administrator
              to control BIND 10.
274
275
276
277
278
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <command>b10-loadzone</command> &mdash;
279
280
281
              zone file loader.
              This tool will load standard masterfile-format zone files into
              BIND 10.
282
283
            </simpara>
          </listitem>
284
285
286
287
288
          <listitem>
            <simpara>
              <command>b10-cmdctl-usermgr</command> &mdash;
              user access control.
              This tool allows an administrator to authorize additional users
289
              to manage BIND 10.
290
291
            </simpara>
          </listitem>
292
293
294
295
  <!-- TODO usermgr -->
        </itemizedlist>
      </para>
    </section>
296
297

    <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
298
      The tools and modules are covered in full detail in this guide.
299
300
301
<!-- TODO point to these -->
      In addition, manual pages are also provided in the default installation.
    </para>
302

303
304
305
306
307
308
309
310
311
312
313
314
<!--
bin/
  bindctl*
  host*
lib/
  libauth
  libdns
  libexceptions
  python3.1/site-packages/isc/{cc,config}
sbin/
  bind10
share/
315
  share/bind10/
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
    auth.spec
    b10-cmdctl.pem
    bob.spec
    passwd.csv
  man/
var/
  bind10/b10-config.db
-->

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

  </chapter>

335
336
  <chapter id="installation">
    <title>Installation</title>
337

338
    <section id="build-requirements">
339
      <title>Building Requirements</title>
340
341
342
343
344
345

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

346
        <note>
347
          <simpara>
348
349
350
            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
351
            libraries, to build BIND 10 from source code.
352
          </simpara>
353
354
        </note>

355
356
        <para>
          Building from source code requires the Boost
357
358
359
          build-time headers
          (<ulink url="http://www.boost.org/"/>).
          At least Boost version 1.35 is required.
360
361
362
363
  <!-- 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
364
        <para>
365
366
          To build BIND 10, also install the Botan (at least version
          1.8) and the log4cplus (at least version 1.0.3)
367
368
369
370
371
372
373
374
375
          development include headers.
        </para>

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

376
377
<!-- 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
378

379
380
        <para>
          Building BIND 10 also requires a C++ compiler and
381
          standard development headers, make, and pkg-config.
382
          BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
383
          4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
384
        </para>
385
386
387
388
389
390
391

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

392
393
    </section>

394
395
    <section id="quickstart">
      <title>Quick start</title>
396
397
398
399
400
      <note>
        <simpara>
          This quickly covers the standard steps for installing
          and deploying BIND 10 as an authoritative name server using
          its defaults. For troubleshooting, full customizations and further
Jeremy C. Reed's avatar
Jeremy C. Reed committed
401
          details, see the respective chapters in the BIND 10 guide.
402
403
        </simpara>
      </note>
404

405
406
407
408
409
      <para>
        To quickly get started with BIND 10, follow these steps.
      </para>

      <orderedlist>
410

411
        <listitem>
412
          <simpara>
413
            Install required run-time and build dependencies.
414
          </simpara>
415
        </listitem>
416

417
        <listitem>
418
419
420
          <simpara>
            Download the BIND 10 source tar file from
            <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
421
422
          </simpara>
        </listitem>
423

424
425
426
427
428
        <listitem>
          <para>Extract the tar file:
          <screen>$ <userinput>gzcat bind10-<replaceable>VERSION</replaceable>.tar.gz | tar -xvf -</userinput></screen>
          </para>
        </listitem>
429

430
431
432
433
434
435
        <listitem>
          <para>Go into the source and run configure:
            <screen>$ <userinput>cd bind10-<replaceable>VERSION</replaceable></userinput>
  $ <userinput>./configure</userinput></screen>
          </para>
        </listitem>
436

437
438
439
440
441
        <listitem>
          <para>Build it:
            <screen>$ <userinput>make</userinput></screen>
          </para>
        </listitem>
442

443
444
445
446
447
        <listitem>
          <para>Install it (to default /usr/local):
            <screen>$ <userinput>make install</userinput></screen>
          </para>
        </listitem>
448

449
450
451
452
453
        <listitem>
          <para>Start the server:
            <screen>$ <userinput>/usr/local/sbin/bind10</userinput></screen>
          </para>
        </listitem>
454

455
        <listitem>
456

457
         <para>Test it; for example:
458
            <screen>$ <userinput>dig @127.0.0.1 -c CH -t TXT authors.bind</userinput></screen>
459
460
461
462
463
464
465
466
467
468
         </para>
        </listitem>

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

        <listitem>
469
470
          <simpara>
            Test the new zone.
471
472
          </simpara>
        </listitem>
473

474
      </orderedlist>
475
476
477
478
479

    </section>

    <section id="install">
      <title>Installation from source</title>
480
      <para>
481
482
        BIND 10 is open source software written in C++ and Python.
        It is freely available in source code form from ISC via
483
        the Git code revision control system or as a downloadable
484
485
        tar file. It may also be available in pre-compiled ready-to-use
        packages from operating system vendors.
486
487
      </para>

488
489
      <section>
        <title>Download Tar File</title>
490
491
492
493
        <para>
          Downloading a release tar file is the recommended method to
          obtain the source code.
        </para>
494

495
496
        <para>
          The BIND 10 releases are available as tar file downloads from
497
498
          <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
          Periodic development snapshots may also be available.
499
500
501
502
503
        </para>
  <!-- TODO -->
      </section>

      <section>
504
        <title>Retrieve from Git</title>
505
506
507
508
509
        <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>
510
511
512

        <note>
          <para>
513
            When using source code retrieved via Git additional
514
            software will be required:  automake (v1.11 or newer),
515
            libtoolize, and autoconf (2.59 or newer).
516
517
518
519
            These may need to be installed.
          </para>
        </note>

520
521
522
        <para>
          The latest development code, including temporary experiments
          and un-reviewed code, is available via the BIND 10 code revision
523
          control system. This is powered by Git and all the BIND 10
524
          development is public.
525
          The leading development is done in the <quote>master</quote>.
526
527
        </para>
        <para>
528
          The code can be checked out from
529
          <filename>git://git.bind10.isc.org/bind10</filename>;
530
          for example:
531

532
        <screen>$ <userinput>git clone git://git.bind10.isc.org/bind10</userinput></screen>
533
        </para>
534

535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
        <para>
          When checking out the code from
          the code version control system, it doesn't include the
          generated configure script, Makefile.in files, nor the
          related configure files.
          They can be created by running <command>autoreconf</command>
          with the <option>--install</option> switch.
          This will run <command>autoconf</command>,
          <command>aclocal</command>,
          <command>libtoolize</command>,
          <command>autoheader</command>,
          <command>automake</command>,
          and related commands.
        </para>

550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
      </section>


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

          <variablelist>

          <varlistentry>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
568
569
            <term>--prefix</term>
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
570
              <simpara>Define the installation location (the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
571
572
                default is <filename>/usr/local/</filename>).
              </simpara>
573
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
574
575
576
577
          </varlistentry>

          <varlistentry>
            <term>--with-boost-include</term>
578
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
579
              <simpara>Define the path to find the Boost headers.
580
              </simpara>
581
            </listitem>
582
583
584
          </varlistentry>

          <varlistentry>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
585
            <term>--with-pythonpath</term>
586
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
587
588
589
              <simpara>Define the path to Python 3.1 if it is not in the
                standard execution path.
              </simpara>
590
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
591
592
593
594
          </varlistentry>

          <varlistentry>
            <term>--with-gtest</term>
595
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
596
597
598
              <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.
599
              </simpara>
600
            </listitem>
601
602
603
604
605
          </varlistentry>

          </variablelist>

        </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
606
  <!-- TODO: lcov -->
607
608

        <para>
609
          For example, the following configures it to
610
    find the Boost headers, find the
611
    Python interpreter, and sets the installation location:
612

613
          <screen>$ <userinput>./configure \
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
      --with-boost-include=/usr/pkg/include \
      --with-pythonpath=/usr/pkg/bin/python3.1 \
      --prefix=/opt/bind10</userinput></screen>
        </para>

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

      </section>

      <section>
        <title>Build</title>
        <para>
629
630
    After the configure step is complete, to build the executables
    from the C++ code and prepare the Python scripts, run:
631
632
633
634
635
636
637
638

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

      <section>
        <title>Install</title>
        <para>
Michael Graff's avatar
Michael Graff committed
639
640
          To install the BIND 10 executables, support files,
          and documentation, run:
641
642
          <screen>$ <userinput>make install</userinput></screen>
        </para>
Michael Graff's avatar
Michael Graff committed
643
        <note>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
644
          <para>The install step may require superuser privileges.</para>
Michael Graff's avatar
Michael Graff committed
645
        </note>
646
647
648
649
650
651
652
653
654

      </section>

  <!-- TODO: tests -->

      <section>
        <title>Install Hierarchy</title>
        <para>
          The following is the layout of the complete BIND 10 installation:
655
656
657
658
659
660
661
662
663
          <itemizedlist>
            <listitem>
              <simpara>
                <filename>bin/</filename> &mdash;
                general tools and diagnostic clients.
              </simpara>
            </listitem>
            <listitem>
            <simpara>
664
              <filename>etc/bind10-devel/</filename> &mdash;
665
666
667
668
669
670
671
672
673
674
675
              configuration files.
            </simpara>
            </listitem>
            <listitem>
              <simpara>
                <filename>lib/</filename> &mdash;
                libraries and python modules.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
676
                <filename>libexec/bind10-devel/</filename> &mdash;
677
678
679
680
681
682
683
684
685
686
687
688
689
690
                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>
691
                <filename>share/bind10-devel/</filename> &mdash;
692
693
694
695
696
697
698
699
700
701
702
                configuration specifications.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
                <filename>share/man/</filename> &mdash;
                manual pages (online documentation).
              </simpara>
            </listitem>
            <listitem>
              <simpara>
703
                <filename>var/bind10-devel/</filename> &mdash;
704
705
706
707
708
                data source and configuration databases.
              </simpara>
            </listitem>
          </itemizedlist>
        </para>
709
710
711
712
713
714
715
716
717
718
      </section>
    </section>

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

720
  </chapter>
721

722
  <chapter id="bind10">
Michael Graff's avatar
Michael Graff committed
723
    <title>Starting BIND10 with <command>bind10</command></title>
724
    <para>
725
      BIND 10 provides the <command>bind10</command> command which
Michael Graff's avatar
Michael Graff committed
726
727
      starts up the required processes.
      <command>bind10</command>
728
      will also restart some processes that exit unexpectedly.
Michael Graff's avatar
Michael Graff committed
729
      This is the only command needed to start the BIND 10 system.
730
731
732
    </para>

    <para>
733
      After starting the <command>b10-msgq</command> communications channel,
734
      <command>bind10</command> connects to it,
735
736
      runs the configuration manager, and reads its own configuration.
      Then it starts the other modules.
737
738
739
    </para>

    <para>
740
741
      The <command>b10-sockcreator</command>, <command>b10-msgq</command> and
      <command>b10-cfgmgr</command>
742
      services make up the core. The <command>b10-msgq</command> daemon
743
      provides the communication channel between every part of the system.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
744
      The <command>b10-cfgmgr</command> daemon is always needed by every
745
746
      module, if only to send information about themselves somewhere,
      but more importantly to ask about their own settings, and
747
748
      about other modules. The <command>b10-sockcreator</command> will
      allocate sockets for the rest of the system.
749
750
751
752
753
    </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
754
      <command>b10-cmdctl</command> for admins to communicate with the
755
      system, <command>b10-auth</command> for authoritative DNS service,
756
      <command>b10-stats</command> for statistics collection,
757
758
      <command>b10-xfrin</command> for inbound DNS zone transfers,
      <command>b10-xfrout</command> for outbound DNS zone transfers,
Jeremy C. Reed's avatar
Jeremy C. Reed committed
759
      and <command>b10-zonemgr</command> for secondary service.
760
761
    </para>

762
    <section id="start">
763
764
765
      <title>Starting BIND 10</title>
      <para>
        To start the BIND 10 service, simply run <command>bind10</command>.
766
        Run it with the <option>--verbose</option> switch to
767
768
769
        get additional debugging or diagnostic output.
      </para>
<!-- TODO: note it doesn't go into background -->
770
771
772
773
774
775
776
777
778
779

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

780
    </section>
781
782
783
784
785
786
787
788
789
790
791
792
793
794
    <section id="bind10.config">
      <title>Configuration of started processes</title>
      <para>
        The processes to be started can be configured, with the exception
        of the <command>b10-sockcreator</command>, <command>b10-msgq</command>
        and <command>b10-cfgmgr</command>.
      </para>

      <para>
        The configuration is in the Boss/components section. Each element
        represents one component, which is an abstraction of a process
        (currently there's also one component which doesn't represent
        a process). If you didn't want to transfer out at all (your server
        is a slave only), you would just remove the corresponding component
Jeremy C. Reed's avatar
Jeremy C. Reed committed
795
        from the set, like this and the process would be stopped immediately
796
        (and not started on the next startup):
797
      <screen>&gt; <userinput>config remove Boss/components b10-xfrout</userinput>
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
&gt; <userinput>config commit</userinput></screen>
      </para>

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

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

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

      <para>
839
840
841
842
843
844
845
846
847
848
849
850
851
852
        The kind specifies how a failure of the component should
        be handled.  If it is set to <quote>dispensable</quote>
        (the default unless you set something else), it will get
        started again if it fails. If it is set to <quote>needed</quote>
        and it fails at startup, the whole <command>bind10</command>
        shuts down and exits with error exit code. But if it fails
        some time later, it is just started again. If you set it
        to <quote>core</quote>, you indicate that the system is
        not usable without the component and if such component
        fails, the system shuts down no matter when the failure
        happened.  This is the behaviour of the core components
        (the ones you can't turn off), but you can declare any
        other components as core as well if you wish (but you can
        turn these off, they just can't fail).
853
854
855
856
857
      </para>

      <para>
        The priority defines order in which the components should start.
        The ones with higher number are started sooner than the ones with
858
        lower ones. If you don't set it, 0 (zero) is used as the priority.
859
        Usually, leaving it at the default is enough.
860
861
862
863
      </para>

      <para>
        There are other parameters we didn't use in our example.
864
865
866
867
868
869
870
        One of them is <quote>address</quote>. It is the address
        used by the component on the <command>b10-msgq</command>
        message bus. The special components already know their
        address, but the usual ones don't. The address is by
        convention the thing after <emphasis>b10-</emphasis>, with
        the first letter capital (eg. <command>b10-stats</command>
        would have <quote>Stats</quote> as its address).
871
<!-- TODO: this should be simplified so we don't even have to document it -->
872
873
      </para>

874
875
876
877
878
<!-- TODO: what does "The special components already know their
address, but the usual ones don't." mean? -->

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

879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
      <para>
        The last one is process. It is the name of the process to be started.
        It defaults to the name of the component if not set, but you can use
        this to override it.
      </para>

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

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

      <note>
        <para>
899
900
901
902
903
904
905
906
907
          The configuration is quite powerful, but that includes
          a lot of space for mistakes. You could turn off the
          <command>b10-cmdctl</command>, but then you couldn't
          change it back the usual way, as it would require it to
          be running (you would have to find and edit the configuration
          directly).  Also, some modules might have dependencies
          -- <command>b10-stats-httpd</command> need
          <command>b10-stats</command>, <command>b10-xfrout</command>
          needs the <command>b10-auth</command> to be running, etc.
908
909
910

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

911
912
913
914
915
        </para>
        <para>
          In short, you should think twice before disabling something here.
        </para>
      </note>
Michal 'vorner' Vaner's avatar
Michal 'vorner' Vaner committed
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
      <para>
        It is possible to start some components multiple times (currently
        <command>b10-auth</command> and <command>b10-resolzer</command>).
        You might want to do that to gain more performance (each one uses only
        single core). Just put multiple entries under different names, like
        this, with the same config:
        <screen>&gt; <userinput>config add Boss/components b10-resolver-2</userinput>
&gt; <userinput>config set Boss/components/b10-resolver-2/special resolver</userinput>
&gt; <userinput>config set Boss/components/b10-resolver-2/kind needed</userinput>
&gt; <userinput>config commit</userinput></screen>
      </para>
      <para>
        However, this is work in progress and the support is not yet complete.
        For example, each resolver will have its own cache, each authoritative
        server will keep its own copy of in-memory data and there could be
        problems with locking the sqlite database, if used. The configuration
        might be changed to something more convenient in future.
      </para>
934
    </section>
935
936
937

  </chapter>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
938
939
940
941
  <chapter id="msgq">
    <title>Command channel</title>

      <para>
942
        The BIND 10 components use the <command>b10-msgq</command>
Michael Graff's avatar
Michael Graff committed
943
        message routing daemon to communicate with other BIND 10 components.
944
        The <command>b10-msgq</command> implements what is called the
Michael Graff's avatar
Michael Graff committed
945
946
947
948
949
        <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
950
        This Command Channel is not used for DNS message passing.
Michael Graff's avatar
Michael Graff committed
951
952
        It is used only to control and monitor the BIND 10 system.
      </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
953
954
955

      <para>
        Administrators do not communicate directly with the
956
        <command>b10-msgq</command> daemon.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
957
        By default, BIND 10 uses port 9912 for the
958
        <command>b10-msgq</command> service.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
959
960
        It listens on 127.0.0.1.
      </para>
961

Jeremy C. Reed's avatar
Jeremy C. Reed committed
962
<!-- TODO: this is broken, see Trac #111
Michael Graff's avatar
Michael Graff committed
963
      <para>
964
        To select an alternate port for the <command>b10-msgq</command> to
Michael Graff's avatar
Michael Graff committed
965
        use, run <command>bind10</command> specifying the option:
Jeremy C. Reed's avatar
Jeremy C. Reed committed
966
        <screen> $ <userinput>bind10 -TODO-msgq-port 9912</userinput></screen>
Michael Graff's avatar
Michael Graff committed
967
      </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
968
-->
Jeremy C. Reed's avatar
Jeremy C. Reed committed
969
970
971
972
973
974
975

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

  </chapter>

976
977
978
979
  <chapter id="cfgmgr">
    <title>Configuration manager</title>

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

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

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

<!-- TODO -->
Michael Graff's avatar
Michael Graff committed
1000
1001
      <note>
        <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1002
          The development prototype release only provides the
Michael Graff's avatar
Michael Graff committed
1003
1004
1005
1006
1007
1008
          <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>
1009
1010
1011
1012

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

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
1034
      <para>
        <command>b10-cfgmgr</command> relays configurations received
        from <command>b10-cmdctl</command> to the appropriate modules.
      </para>
<!-- TODO:
        Configuration settings for itself are defined as ConfigManager.
TODO: show examples
-->

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

<!-- TODO: what about run time config to change this? -->
<!-- jelte: > config set cfgmgr/config_database <file> -->
<!-- TODO: what about command line switch to change this? -->
      <para>
        The stored configuration file is at
1035
        <filename>/usr/local/var/bind10-devel/b10-config.db</filename>.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1036
        (The full path is what was defined at build configure time for
1037
1038
        <option>--localstatedir</option>.
        The default is <filename>/usr/local/var/</filename>.)
Michael Graff's avatar
Michael Graff committed
1039
1040
1041
1042
        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
1043
      </para>
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058

<!--

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

-->
1059
1060

    <para>
1061
1062
1063
1064
1065
1066
1067
1068
1069
      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
1070
1071
1072
1073
1074
1075
1076
-->

<!-- 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
1077
1078
1079
1080
1081
1082
1083
-->

  </chapter>

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

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1084
1085
1086
1087
1088
1089
1090
1091
    <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>
1092
1093
<!-- TODO: copy examples from wiki, try with wget -->

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1094
    <para>
1095
      When <command>b10-cmdctl</command> starts, it firsts
1096
1097
      asks <command>b10-cfgmgr</command> about what modules are
      running and what their configuration is (over the
1098
      <command>b10-msgq</command> channel). Then it will start listening
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1099
1100
1101
1102
1103
1104
1105
1106
1107
      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.
1108
    </para>
1109

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
<!--
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
-->

1123
1124
<!-- TODO: replace /usr/local -->
<!-- TODO: permissions -->
1125
1126
1127
    <para>The HTTPS server requires a private key,
      such as a RSA PRIVATE KEY.
      The default location is at
1128
      <filename>/usr/local/etc/bind10-devel/cmdctl-keyfile.pem</filename>.
1129
      (A sample key is at
1130
      <filename>/usr/local/share/bind10-devel/cmdctl-keyfile.pem</filename>.)
1131
      It also uses a certificate located at
1132
      <filename>/usr/local/etc/bind10-devel/cmdctl-certfile.pem</filename>.
1133
      (A sample certificate is at
1134
      <filename>/usr/local/share/bind10-devel/cmdctl-certfile.pem</filename>.)
1135
      This may be a self-signed certificate or purchased from a
1136
1137
      certification authority.
    </para>
1138
1139

    <note><para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1140
1141
1142
1143
1144
      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
1145
      a certificate needs to be first received from the BIND 10
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1146
1147
      administrator.
      The BIND 10 installation provides a sample PEM bundle that matches
1148
1149
1150
      the sample key and certificate.
    </para></note>
<!-- TODO: cross-ref -->
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1151
1152
1153
1154
1155

<!-- TODO
openssl req -new -x509 -keyout server.pem -out server.pem -days 365 -nodes
but that is a single file, maybethis should go back to that format?
-->
1156
1157
1158
1159
1160
1161
1162

<!--
    <para>
(08:20:56) shane: It is in theory possible to run without cmdctl.
(08:21:02) shane: I think we discussed this.
    </para>
-->
1163
1164
1165
1166
1167
1168
1169

<!-- 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
1170
      <filename>/usr/local/etc/bind10-devel/cmdctl-accounts.csv</filename>.
1171
1172
1173
      This comma-delimited file lists the accounts with a user name,
      hashed password, and salt.
      (A sample file is at
1174
      <filename>/usr/local/share/bind10-devel/cmdctl-accounts.csv</filename>.
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
      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.
1190
1191
      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
1192
1193
1194
      line argument.
      Each HTTPS connection is stateless and timesout in 1200 seconds
      by default.  This can be
1195
      redefined by using the <option>--idle-timeout</option> command line argument.
1196
1197
    </para>

1198
    <section id="cmdctl.spec">
1199
      <title>Configuration specification for b10-cmdctl</title>
1200
      <para>
1201
1202
1203
1204
        The configuration items for <command>b10-cmdctl</command> are:
key_file
cert_file
accounts_file
1205
      </para>
1206
1207
<!-- TODO -->

1208
      <para>
1209
1210
        The control commands are:
print_settings
1211
1212
<!-- TODO: remove that -->

1213
shutdown
1214
      </para>
1215
<!-- TODO -->
1216
    </section>
1217
1218
1219

<!--
TODO
1220
1221
(12:21:30) jinmei: I'd like to have sample session using a command line www client such as wget
(12:21:33) jinmei: btw
1222
1223
-->

1224
1225
  </chapter>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1226
1227
1228
1229
  <chapter id="bindctl">
    <title>Control and configure user interface</title>

    <note><para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1230
      For this development prototype release, <command>bindctl</command>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
      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>

    <para>
      The <command>bindctl</command> tool provides an interactive
      prompt for configuring, controlling, and querying the BIND 10
      components.
1241
      It co