bind10-guide.xml 73.5 KB
Newer Older
1
2
3
4
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash  "&#x2014;" >
5
6
<!ENTITY % version SYSTEM "version.ent">
%version;
7
]>
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

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

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

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

    <copyright>
33
      <year>2010-2011</year><holder>Internet Systems Consortium, Inc.</holder>
34
35
    </copyright>

36
    <abstract>
37
38
39
40
      <para>BIND 10 is a Domain Name System (DNS) suite managed by
	Internet Systems Consortium (ISC). It includes DNS libraries
	and modular components for controlling authoritative and
	recursive DNS servers.
41
      </para>
42
43
      <para>
        This is the reference guide for BIND 10 version &__VERSION__;.
44
45
46
47
	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>
48
49
50
51

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

52
53
54
55
56
57
58
  </bookinfo>

  <chapter id="intro">
    <title>Introduction</title>
    <para>
      BIND is the popular implementation of a DNS server, developer
      interfaces, and DNS tools.
59
60
      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.
61
62
    </para>

63
64
    <note>
      <para>
65
66
        This guide covers the experimental prototype of
        BIND 10 version &__VERSION__;.
67
68
      </para>
    </note>
69

70
71
    <note>
      <para>
72
        BIND 10 provides a EDNS0- and DNSSEC-capable
73
74
        authoritative DNS server and a caching recursive name server
        which also provides forwarding.
75
76
      </para>
    </note>
77

78
    <section>
79
80
      <title>Supported Platforms</title>
      <para>
81
  BIND 10 builds have been tested on Debian GNU/Linux 5,
82
  Ubuntu 9.10, NetBSD 5, Solaris 10, FreeBSD 7 and 8, and CentOS
83
  Linux 5.3.
84

85
86
  It has been tested on Sparc, i386, and amd64 hardware
  platforms.
87
88
89
90
91
92
93
94
95
96

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

    <section>
      <title>Required Software</title>
      <para>
        BIND 10 requires Python 3.1.  Later versions may work, but Python
97
        3.1 is the minimum version which will work.
98
99
      </para>

100
101
      <para>
	BIND 10 uses the Botan crypto library for C++. It requires
102
	at least Botan version 1.8.
103
      </para>
104

105
106
107
108
      <para>
	BIND 10 uses the log4cplus C++ logging library. It requires
	at least log4cplus version 1.0.3.
      </para>
109

110
111
112
113
114
115
116
117
      <para>
	The authoritative server requires SQLite 3.3.9 or newer.
	The <command>b10-xfrin</command>, <command>b10-xfrout</command>,
	and <command>b10-zonemgr</command> modules require the
	libpython3 library and the Python _sqlite3.so module.
      </para>
<!-- TODO: this will change ... -->

118
119
120
<!-- TODO: list where to get these from -->

      <note>
121
122
123
124
125
126
127
        <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>
128
    </section>
129

130
131
    <section id="starting_stopping">
      <title>Starting and Stopping the Server</title>
132

133
134
135
      <para>
        BIND 10 is modular.  Part of this modularity is
        accomplished using multiple cooperating processes which, together,
136
137
138
	provide the server functionality.  This is a change from
	the previous generation of BIND software, which used a
	single process.
139
140
141
      </para>

      <para>
142
143
144
145
146
147
148
	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:
149
      </para>
150

151
      <para>
152

153
        <itemizedlist>
154

155
156
          <listitem>
            <simpara>
157
              <command>b10-msgq</command> &mdash;
158
              Message bus daemon.
159
160
              This process coordinates communication between all of the other
              BIND 10 processes.
161
162
            </simpara>
          </listitem>
163

164
165
166
          <listitem>
            <simpara>
              <command>b10-auth</command> &mdash;
167
              Authoritative DNS server.
168
              This process serves DNS requests.
169
170
            </simpara>
          </listitem>
171

172
173
174
          <listitem>
            <simpara>
              <command>b10-cfgmgr</command> &mdash;
175
              Configuration manager.
176
              This process maintains all of the configuration for BIND 10.
177
178
            </simpara>
          </listitem>
179

180
181
182
          <listitem>
            <simpara>
              <command>b10-cmdctl</command> &mdash;
183
              Command and control service.
184
              This process allows external control of the BIND 10 system.
185
186
            </simpara>
          </listitem>
187

188
189
190
191
192
193
194
195
196
          <listitem>
            <simpara>
              <command>b10-resolver</command> &mdash;
              Recursive name server.
              This process handles incoming queries.
<!-- TODO: -->
            </simpara>
          </listitem>

197
198
199
200
201
202
203
204
          <listitem>
            <simpara>
              <command>b10-stats</command> &mdash;
              Statistics collection daemon.
              This process collects and reports statistics data.
            </simpara>
          </listitem>

205
206
207
          <listitem>
            <simpara>
              <command>b10-xfrin</command> &mdash;
208
              Incoming zone transfer service.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
209
              This process is used to transfer a new copy
210
              of a zone into BIND 10, when acting as a secondary server.
211
212
            </simpara>
          </listitem>
213

Jeremy C. Reed's avatar
Jeremy C. Reed committed
214
215
216
217
218
219
220
221
222
223
          <listitem>
            <simpara>
              <command>b10-xfrout</command> &mdash;
              Outgoing zone transfer service.
	      This process is used to handle transfer requests to
	      send a local zone to a remote secondary server,
	      when acting as a master server.
            </simpara>
          </listitem>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
224
225
226
227
228
229
230
231
232
          <listitem>
            <simpara>
              <command>b10-zonemgr</command> &mdash;
              Secondary manager.
	      This process keeps track of timers and other
              necessary information for BIND 10 to act as a slave server.
            </simpara>
          </listitem>

233
234
        </itemizedlist>
      </para>
235
236
237
238
239
240

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

241
    </section>
242

243
244
    <section id="managing_once_running">
      <title>Managing BIND 10</title>
245

246
      <para>
247
248
	Once BIND 10 is running, a few commands are used to interact
	directly with the system:
249
250
251
252
        <itemizedlist>
          <listitem>
            <simpara>
              <command>bindctl</command> &mdash;
253
254
255
              interactive administration interface.
              This is a command-line tool which allows an administrator
              to control BIND 10.
256
257
258
259
260
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <command>b10-loadzone</command> &mdash;
261
262
263
              zone file loader.
              This tool will load standard masterfile-format zone files into
              BIND 10.
264
265
            </simpara>
          </listitem>
266
267
268
269
270
          <listitem>
            <simpara>
              <command>b10-cmdctl-usermgr</command> &mdash;
              user access control.
              This tool allows an administrator to authorize additional users
271
              to manage BIND 10.
272
273
            </simpara>
          </listitem>
274
275
276
277
  <!-- TODO usermgr -->
        </itemizedlist>
      </para>
    </section>
278
279

    <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
280
      The tools and modules are covered in full detail in this guide.
281
282
283
<!-- TODO point to these -->
      In addition, manual pages are also provided in the default installation.
    </para>
284

285
286
287
288
289
290
291
292
293
294
295
296
<!--
bin/
  bindctl*
  host*
lib/
  libauth
  libdns
  libexceptions
  python3.1/site-packages/isc/{cc,config}
sbin/
  bind10
share/
297
  share/bind10/
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
    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>

317
318
  <chapter id="installation">
    <title>Installation</title>
319

320
321
    <section>
      <title>Building Requirements</title>
322
323
324
325
326
327

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

328
        <note>
329
          <simpara>
330
331
332
            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
333
            libraries, to build BIND 10 from source code.
334
          </simpara>
335
336
        </note>

337
338
        <para>
          Building from source code requires the Boost
339
          build-time headers. At least Boost version 1.35 is required.
340
341
342
343
  <!-- 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
344
        <para>
345
346
347
348
349
350
351
352
353
354
355
356
357
	  To build BIND 10, also install the Botan (at least version
	  1.8) and the log4cplus (at least version 1.0.3)
          development include headers.
        </para>

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

        <para>
<!-- TODO: is this needed at build time? test time? -->
358
359
	  The Python Library and Python _sqlite3 module are required to
          enable the Xfrout and Xfrin support.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
360
361
362
363
364
365
366
        </para>

        <note><simpara>
          The Python related libraries and modules need to be built
          for Python 3.1.
        </simpara></note>

367
368
        <para>
          Building BIND 10 also requires a C++ compiler and
369
          standard development headers, make, and pkg-config.
370
          BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
371
          4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
372
373
374
        </para>
    </section>

375
376
    <section id="quickstart">
      <title>Quick start</title>
377
378
379
380
381
      <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
382
          details, see the respective chapters in the BIND 10 guide.
383
384
        </simpara>
      </note>
385

386
387
388
389
390
      <para>
        To quickly get started with BIND 10, follow these steps.
      </para>

      <orderedlist>
391

392
        <listitem>
393
394
395
          <simpara>
            Install required build dependencies.
          </simpara>
396
        </listitem>
397

398
        <listitem>
399
400
401
          <simpara>
            Download the BIND 10 source tar file from
            <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
402
403
          </simpara>
        </listitem>
404

405
406
407
408
409
        <listitem>
          <para>Extract the tar file:
          <screen>$ <userinput>gzcat bind10-<replaceable>VERSION</replaceable>.tar.gz | tar -xvf -</userinput></screen>
          </para>
        </listitem>
410

411
412
413
414
415
416
        <listitem>
          <para>Go into the source and run configure:
            <screen>$ <userinput>cd bind10-<replaceable>VERSION</replaceable></userinput>
  $ <userinput>./configure</userinput></screen>
          </para>
        </listitem>
417

418
419
420
421
422
        <listitem>
          <para>Build it:
            <screen>$ <userinput>make</userinput></screen>
          </para>
        </listitem>
423

424
425
426
427
428
        <listitem>
          <para>Install it (to default /usr/local):
            <screen>$ <userinput>make install</userinput></screen>
          </para>
        </listitem>
429

430
431
432
433
434
        <listitem>
          <para>Start the server:
            <screen>$ <userinput>/usr/local/sbin/bind10</userinput></screen>
          </para>
        </listitem>
435

436
        <listitem>
437

438
         <para>Test it; for example:
439
            <screen>$ <userinput>dig @127.0.0.1 -c CH -t TXT authors.bind</userinput></screen>
440
441
442
443
444
445
446
447
448
449
         </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>
450
451
          <simpara>
            Test the new zone.
452
453
          </simpara>
        </listitem>
454

455
      </orderedlist>
456
457
458
459
460

    </section>

    <section id="install">
      <title>Installation from source</title>
461
      <para>
462
463
        BIND 10 is open source software written in C++ and Python.
        It is freely available in source code form from ISC via
464
        the Git code revision control system or as a downloadable
465
466
        tar file. It may also be available in pre-compiled ready-to-use
        packages from operating system vendors.
467
468
      </para>

469
470
      <section>
        <title>Download Tar File</title>
471
472
473
474
        <para>
          Downloading a release tar file is the recommended method to
          obtain the source code.
        </para>
475

476
477
        <para>
          The BIND 10 releases are available as tar file downloads from
478
479
          <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
          Periodic development snapshots may also be available.
480
481
482
483
484
        </para>
  <!-- TODO -->
      </section>

      <section>
485
        <title>Retrieve from Git</title>
486
487
488
489
490
        <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>
491
492
493

        <note>
          <para>
494
            When using source code retrieved via Git additional
495
            software will be required:  automake (v1.11 or newer),
496
            libtoolize, and autoconf (2.59 or newer).
497
498
499
500
            These may need to be installed.
          </para>
        </note>

501
502
503
        <para>
          The latest development code, including temporary experiments
          and un-reviewed code, is available via the BIND 10 code revision
504
          control system. This is powered by Git and all the BIND 10
505
          development is public.
506
          The leading development is done in the <quote>master</quote>.
507
508
        </para>
        <para>
509
510
511
          The code can be checked out from
          <filename>git://bind10.isc.org/bind10</filename>;
          for example:
512

513
        <screen>$ <userinput>git clone git://bind10.isc.org/bind10</userinput></screen>
514
        </para>
515

516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
        <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>

531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
      </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
549
550
            <term>--prefix</term>
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
551
              <simpara>Define the installation location (the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
552
553
                default is <filename>/usr/local/</filename>).
              </simpara>
554
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
555
556
557
558
          </varlistentry>

          <varlistentry>
            <term>--with-boost-include</term>
559
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
560
              <simpara>Define the path to find the Boost headers.
561
              </simpara>
562
            </listitem>
563
564
565
          </varlistentry>

          <varlistentry>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
566
            <term>--with-pythonpath</term>
567
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
568
569
570
              <simpara>Define the path to Python 3.1 if it is not in the
                standard execution path.
              </simpara>
571
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
572
573
574
575
          </varlistentry>

          <varlistentry>
            <term>--with-gtest</term>
576
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
577
578
579
              <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.
580
              </simpara>
581
            </listitem>
582
583
584
585
586
          </varlistentry>

          </variablelist>

        </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
587
  <!-- TODO: lcov -->
588
589

        <para>
590
          For example, the following configures it to
591
    find the Boost headers, find the
592
    Python interpreter, and sets the installation location:
593

594
          <screen>$ <userinput>./configure \
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
      --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>
610
611
    After the configure step is complete, to build the executables
    from the C++ code and prepare the Python scripts, run:
612
613
614
615
616
617
618
619

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

      <section>
        <title>Install</title>
        <para>
Michael Graff's avatar
Michael Graff committed
620
621
          To install the BIND 10 executables, support files,
          and documentation, run:
622
623
          <screen>$ <userinput>make install</userinput></screen>
        </para>
Michael Graff's avatar
Michael Graff committed
624
        <note>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
625
          <para>The install step may require superuser privileges.</para>
Michael Graff's avatar
Michael Graff committed
626
        </note>
627
628
629
630
631
632
633
634
635

      </section>

  <!-- TODO: tests -->

      <section>
        <title>Install Hierarchy</title>
        <para>
          The following is the layout of the complete BIND 10 installation:
636
637
638
639
640
641
642
643
644
          <itemizedlist>
            <listitem>
              <simpara>
                <filename>bin/</filename> &mdash;
                general tools and diagnostic clients.
              </simpara>
            </listitem>
            <listitem>
            <simpara>
645
              <filename>etc/bind10-devel/</filename> &mdash;
646
647
648
649
650
651
652
653
654
655
656
              configuration files.
            </simpara>
            </listitem>
            <listitem>
              <simpara>
                <filename>lib/</filename> &mdash;
                libraries and python modules.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
657
                <filename>libexec/bind10-devel/</filename> &mdash;
658
659
660
661
662
663
664
665
666
667
668
669
670
671
                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>
672
                <filename>share/bind10-devel/</filename> &mdash;
673
674
675
676
677
678
679
680
681
682
683
                configuration specifications.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
                <filename>share/man/</filename> &mdash;
                manual pages (online documentation).
              </simpara>
            </listitem>
            <listitem>
              <simpara>
684
                <filename>var/bind10-devel/</filename> &mdash;
685
686
687
688
689
                data source and configuration databases.
              </simpara>
            </listitem>
          </itemizedlist>
        </para>
690
691
692
693
694
695
696
697
698
699
      </section>
    </section>

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

701
  </chapter>
702

703
  <chapter id="bind10">
Michael Graff's avatar
Michael Graff committed
704
    <title>Starting BIND10 with <command>bind10</command></title>
705
    <para>
706
      BIND 10 provides the <command>bind10</command> command which
Michael Graff's avatar
Michael Graff committed
707
708
709
710
      starts up the required processes.
      <command>bind10</command>
      will also restart processes that exit unexpectedly.
      This is the only command needed to start the BIND 10 system.
711
712
713
    </para>

    <para>
714
      After starting the <command>b10-msgq</command> communications channel,
715
      <command>bind10</command> connects to it,
716
717
      runs the configuration manager, and reads its own configuration.
      Then it starts the other modules.
718
719
720
    </para>

    <para>
721
722
      The <command>b10-msgq</command> and <command>b10-cfgmgr</command>
      services make up the core. The <command>b10-msgq</command> daemon
723
      provides the communication channel between every part of the system.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
724
      The <command>b10-cfgmgr</command> daemon is always needed by every
725
726
727
      module, if only to send information about themselves somewhere,
      but more importantly to ask about their own settings, and
      about other modules.
728
      The <command>bind10</command> master process will also start up
Jeremy C. Reed's avatar
Jeremy C. Reed committed
729
      <command>b10-cmdctl</command> for admins to communicate with the
730
731
      system, <command>b10-auth</command> for authoritative DNS service or
      <command>b10-resolver</command> for recursive name service,
732
      <command>b10-stats</command> for statistics collection,
733
734
      <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
735
      and <command>b10-zonemgr</command> for secondary service.
736
737
    </para>

738
    <section id="start">
739
740
741
      <title>Starting BIND 10</title>
      <para>
        To start the BIND 10 service, simply run <command>bind10</command>.
742
        Run it with the <option>--verbose</option> switch to
743
744
745
        get additional debugging or diagnostic output.
      </para>
<!-- TODO: note it doesn't go into background -->
746
747
748
749
750
751
752
753
754
755

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

756
    </section>
757
758
759

  </chapter>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
760
761
762
763
  <chapter id="msgq">
    <title>Command channel</title>

      <para>
764
        The BIND 10 components use the <command>b10-msgq</command>
Michael Graff's avatar
Michael Graff committed
765
        message routing daemon to communicate with other BIND 10 components.
766
        The <command>b10-msgq</command> implements what is called the
Michael Graff's avatar
Michael Graff committed
767
768
769
770
771
        <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
772
        This Command Channel is not used for DNS message passing.
Michael Graff's avatar
Michael Graff committed
773
774
        It is used only to control and monitor the BIND 10 system.
      </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
775
776
777

      <para>
        Administrators do not communicate directly with the
778
        <command>b10-msgq</command> daemon.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
779
        By default, BIND 10 uses port 9912 for the
780
        <command>b10-msgq</command> service.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
781
782
        It listens on 127.0.0.1.
      </para>
783

Jeremy C. Reed's avatar
Jeremy C. Reed committed
784
<!-- TODO: this is broken, see Trac #111
Michael Graff's avatar
Michael Graff committed
785
      <para>
786
        To select an alternate port for the <command>b10-msgq</command> to
Michael Graff's avatar
Michael Graff committed
787
        use, run <command>bind10</command> specifying the option:
Jeremy C. Reed's avatar
Jeremy C. Reed committed
788
        <screen> $ <userinput>bind10 -TODO-msgq-port 9912</userinput></screen>
Michael Graff's avatar
Michael Graff committed
789
      </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
790
-->
Jeremy C. Reed's avatar
Jeremy C. Reed committed
791
792
793
794
795
796
797

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

  </chapter>

798
799
800
801
  <chapter id="cfgmgr">
    <title>Configuration manager</title>

      <para>
Michael Graff's avatar
Michael Graff committed
802
803
804
805
806
         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>
807
808

      <para>
Michael Graff's avatar
Michael Graff committed
809
810
        The <command>b10-auth</command> and <command>b10-xfrin</command>
        daemons and other components receive their configurations
811
        from the configuration manager over the <command>b10-msgq</command>
Michael Graff's avatar
Michael Graff committed
812
        command channel.
813
814
      </para>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
815
816
817
818
      <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"/>.
819
820
821
      </para>

<!-- TODO -->
Michael Graff's avatar
Michael Graff committed
822
823
      <note>
        <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
824
          The development prototype release only provides the
Michael Graff's avatar
Michael Graff committed
825
826
827
828
829
830
          <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>
831
832
833
834

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

Jeremy C. Reed's avatar
Jeremy C. Reed committed
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
      <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
857
        <filename>/usr/local/var/bind10-devel/b10-config.db</filename>.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
858
        (The full path is what was defined at build configure time for
859
860
        <option>--localstatedir</option>.
        The default is <filename>/usr/local/var/</filename>.)
Michael Graff's avatar
Michael Graff committed
861
862
863
864
        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
865
      </para>
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880

<!--

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

-->
881
882

    <para>
883
884
885
886
887
888
889
890
891
      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
892
893
894
895
896
897
898
-->

<!-- 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
899
900
901
902
903
904
905
-->

  </chapter>

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

Jeremy C. Reed's avatar
Jeremy C. Reed committed
906
907
908
909
910
911
912
913
    <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>
914
915
<!-- TODO: copy examples from wiki, try with wget -->

Jeremy C. Reed's avatar
Jeremy C. Reed committed
916
    <para>
917
      When <command>b10-cmdctl</command> starts, it firsts
918
919
      asks <command>b10-cfgmgr</command> about what modules are
      running and what their configuration is (over the
920
      <command>b10-msgq</command> channel). Then it will start listening
Jeremy C. Reed's avatar
Jeremy C. Reed committed
921
922
923
924
925
926
927
928
929
      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.
930
    </para>
931

Jeremy C. Reed's avatar
Jeremy C. Reed committed
932
933
934
935
936
937
938
939
940
941
942
943
944
<!--
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
-->

945
946
<!-- TODO: replace /usr/local -->
<!-- TODO: permissions -->
947
948
949
    <para>The HTTPS server requires a private key,
      such as a RSA PRIVATE KEY.
      The default location is at
950
      <filename>/usr/local/etc/bind10-devel/cmdctl-keyfile.pem</filename>.
951
      (A sample key is at
952
      <filename>/usr/local/share/bind10-devel/cmdctl-keyfile.pem</filename>.)
953
      It also uses a certificate located at
954
      <filename>/usr/local/etc/bind10-devel/cmdctl-certfile.pem</filename>.
955
      (A sample certificate is at
956
      <filename>/usr/local/share/bind10-devel/cmdctl-certfile.pem</filename>.)
957
      This may be a self-signed certificate or purchased from a
958
959
      certification authority.
    </para>
960
961

    <note><para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
962
963
964
965
966
      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
967
      a certificate needs to be first received from the BIND 10
Jeremy C. Reed's avatar
Jeremy C. Reed committed
968
969
      administrator.
      The BIND 10 installation provides a sample PEM bundle that matches
970
971
972
      the sample key and certificate.
    </para></note>
<!-- TODO: cross-ref -->
Jeremy C. Reed's avatar
Jeremy C. Reed committed
973
974
975
976
977

<!-- 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?
-->
978
979
980
981
982
983
984

<!--
    <para>
(08:20:56) shane: It is in theory possible to run without cmdctl.
(08:21:02) shane: I think we discussed this.
    </para>
-->
985
986
987
988
989
990
991

<!-- 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
992
      <filename>/usr/local/etc/bind10-devel/cmdctl-accounts.csv</filename>.
993
994
995
      This comma-delimited file lists the accounts with a user name,
      hashed password, and salt.
      (A sample file is at
996
      <filename>/usr/local/share/bind10-devel/cmdctl-accounts.csv</filename>.
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
      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.
1012
1013
      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
1014
1015
1016
      line argument.
      Each HTTPS connection is stateless and timesout in 1200 seconds
      by default.  This can be
1017
      redefined by using the <option>--idle-timeout</option> command line argument.
1018
1019
    </para>

1020
    <section id="cmdctl.spec">
1021
      <title>Configuration specification for b10-cmdctl</title>
1022
      <para>
1023
1024
1025
1026
        The configuration items for <command>b10-cmdctl</command> are:
key_file
cert_file
accounts_file
1027
      </para>
1028
1029
<!-- TODO -->

1030
      <para>
1031
1032
        The control commands are:
print_settings
1033
1034
<!-- TODO: remove that -->

1035
shutdown
1036
      </para>
1037
<!-- TODO -->
1038
    </section>
1039
1040
1041

<!--
TODO
1042
1043
(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
1044
1045
-->

1046
1047
  </chapter>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1048
1049
1050
1051
  <chapter id="bindctl">
    <title>Control and configure user interface</title>

    <note><para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1052
      For this development prototype release, <command>bindctl</command>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
      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.
1063
      It communicates directly with a REST-ful interface over HTTPS
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
      provided by <command>b10-cmdctl</command>. It doesn't
      communicate to any other components directly.
    </para>

<!-- TODO: explain and show interface -->

    <para>
      Configuration changes are actually commands to
      <command>b10-cfgmgr</command>. So when <command>bindctl</command>
      sends a configuration, it is sent to <command>b10-cmdctl</command>
      (over a HTTPS connection); then <command>b10-cmdctl</command>
1075
      sends the command (over a <command>b10-msgq</command> command
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1076
      channel) to <command>b10-cfgmgr</command> which then stores
1077
      the details and relays (over a <command>b10-msgq</command> command
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1078
1079
1080
1081
1082
1083
1084
1085
      channel) the configuration on to the specified module.
    </para>

    <para>
    </para>

  </chapter>

1086
1087
  <chapter id="authserver">
    <title>Authoritative Server</title>
1088

1089
    <para>
1090
1091
1092
1093
      The <command>b10-auth</command> is the authoritative DNS server.
      It supports EDNS0 and DNSSEC. It supports IPv6.
      Normally it is started by the <command>bind10</command> master
      process.
1094
1095
    </para>

1096
    <section>
1097
      <title>Server Configurations</title>
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108

<!-- TODO: offers command line options but not used
since we used bind10 -->

      <para>
        <command>b10-auth</command> is configured via the
        <command>b10-cfgmgr</command> configuration manager.
        The module name is <quote>Auth</quote>.
        The configuration data item is:

        <variablelist>
1109

1110
1111
          <varlistentry>
            <term>database_file</term>
1112
            <listitem>
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
              <simpara>This is an optional string to define the path to find
                 the SQLite3 database file.
<!-- TODO: -->
Note: Later the DNS server will use various data source backends.
This may be a temporary setting until then.
              </simpara>
            </listitem>
          </varlistentry>

        </variablelist>

      </para>

1126
      <para>
1127
1128
1129
1130
1131
1132
1133

        The configuration command is:

        <variablelist>

          <varlistentry>
            <term>shutdown</term>
1134
            <listitem>
1135
1136
1137
1138
1139
1140
1141
1142
              <simpara>Stop the authoritative DNS server.
              </simpara>
<!-- TODO: what happens when this is sent, will bind10 restart? -->
            </listitem>
          </varlistentry>

        </variablelist>

1143
      </para>
1144
1145
1146

<!-- TODO: examples of setting or running above? -->

1147
    </section>
1148

1149
    <section>
1150
      <title>Data Source Backends</title>
1151
1152

      <note><para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1153
        For the development prototype release, <command>b10-auth</command>
1154
1155
        supports a SQLite3 data source backend and in-memory data source
        backend.
1156
        Upcoming versions will be able to use multiple different
1157
        data sources, such as MySQL and Berkeley DB.
1158
1159
1160
      </para></note>


1161
      <para>
1162
        By default, the SQLite3 backend uses the data file located at
1163
        <filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>.
1164
1165
1166
        (The full path is what was defined at build configure time for
        <option>--localstatedir</option>.
        The default is <filename>/usr/local/var/</filename>.)
1167
1168
  This data file location may be changed by defining the
  <quote>database_file</quote> configuration.
1169
      </para>
1170

1171
    </section>
1172

1173
    <section>
1174
      <title>Loading Master Zones Files</title>
1175

1176
      <para>
1177
1178
1179
1180
        RFC 1035 style DNS master zone files may imported
        into a BIND 10 data source by using the
        <command>b10-loadzone</command> utility.
      </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1181

1182
1183
1184
      <para>
        <command>b10-loadzone</command> supports the following
        special directives (control entries):
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1185

1186
1187
1188
1189
        <variablelist>

          <varlistentry>
            <term>$INCLUDE</term>
1190
            <listitem>
1191
1192
1193
1194
1195
1196
1197
              <simpara>Loads an additional zone file. This may be recursive.
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>$ORIGIN</term>
1198
            <listitem>
1199
1200
1201
1202
1203
1204
1205
              <simpara>Defines the relative domain name.
              </simpara>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>$TTL</term>
1206
            <listitem>
1207
1208
1209
1210
1211
1212
1213
              <simpara>Defines the time-to-live value used for following
                records that don't include a TTL.
              </simpara>
            </listitem>
          </varlistentry>

        </variablelist>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1214

1215
      </para>
1216
1217
1218
1219
1220
1221
1222
1223

      <para>
        The <option>-o</option> argument may be used to define the
        default origin for loaded zone file records.
      </para>

      <note>
      <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1224
1225
        In the development prototype release, only the SQLite3 back
        end is used.
1226
        By default, it stores the zone data in
1227
        <filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1228
        unless the <option>-d</option> switch is used to set the
1229
1230
1231
1232
1233
1234
1235
        database filename.
        Multiple zones are stored in a single SQLite3 zone database.
      </para>
      </note>

      <para>
        If you reload a zone already existing in the database,
Jeremy C. Reed's avatar
typo    
Jeremy C. Reed committed
1236
        all records from that prior zone disappear and a whole new set
1237
1238
1239
1240