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

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

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

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

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

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

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

54
55
  </bookinfo>

56
57
58
59
60
61
  <preface>
    <title>Preface</title>

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

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

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

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

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

<!-- DHCP sponsorship by Comcast -->

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

    </section>

  </preface>

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

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

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

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

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

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

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

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

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

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

161
      <para>
162
163
164
165
        The authoritative DNS server uses SQLite3
        (<ulink url="http://www.sqlite.org/"/>).
<!-- TODO: is this still required? -->
        It needs at least SQLite version 3.3.9.
166
      </para>
167

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

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

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

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

199
      <para>
200

201
        <itemizedlist>
202

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

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

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

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

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

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

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

265
266
267
268
269
270
271
272
          <listitem>
            <simpara>
              <command>b10-stats</command> &mdash;
              Statistics collection daemon.
              This process collects and reports statistics data.
            </simpara>
          </listitem>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
273
274
275
276
277
278
279
280
          <listitem>
            <simpara>
              <command>b10-stats-httpd</command> &mdash;
              HTTP server for statistics reporting.
              This process reports statistics data in XML format over HTTP.
            </simpara>
          </listitem>

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

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

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

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

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

315
    </section>
316

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

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

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

360
361
362
363
364
365
366
367
368
369
370
371
<!--
bin/
  bindctl*
  host*
lib/
  libauth
  libdns
  libexceptions
  python3.1/site-packages/isc/{cc,config}
sbin/
  bind10
share/
372
  share/bind10/
373
374
    auth.spec
    b10-cmdctl.pem
375
    init.spec
376
377
378
379
380
381
382
383
384
385
386
    passwd.csv
  man/
var/
  bind10/b10-config.db
-->

    <para>
      BIND 10 also provides libraries and programmer interfaces
      for C++ and Python for the message bus, configuration backend,
      and, of course, DNS. These include detailed developer
      documentation and code examples.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
387
<!-- TODO: DHCP also but no Python yet. -->
388
389
390
391
392
<!-- TODO point to this -->
    </para>

  </chapter>

393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
  <chapter id="quickstart">
    <title>Quick start</title>

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

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

      <orderedlist>

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

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

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

        <listitem>
          <para>Go into the source and run configure:
            <screen>$ <userinput>cd bind10-<replaceable>VERSION</replaceable></userinput>
  $ <userinput>./configure</userinput></screen>
          </para>
        </listitem>

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

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

446
447
448
449
450
451
452
        <listitem>
          <para>Create a user for yourself:
            <screen>$ <userinput>cd /usr/local/etc/bind10/</userinput></screen>
            <screen>$ <userinput>/usr/local/sbin/b10-cmdctl-usermgr</userinput></screen>
          </para>
        </listitem>

453
454
455
456
457
458
459
        <listitem>
          <para>Start the server (as root):
            <screen>$ <userinput>/usr/local/sbin/bind10</userinput></screen>
          </para>
        </listitem>

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

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

        <listitem>
          <para>Load desired zone file(s), for example:
484
            <screen>$ <userinput>b10-loadzone <replaceable>-c '{"database_file": "/usr/local/var/bind10/zone.sqlite3"}'</replaceable> <replaceable>your.zone.example.org</replaceable> <replaceable>your.zone.file</replaceable></userinput></screen>
485
          </para>
JINMEI Tatuya's avatar
JINMEI Tatuya committed
486
487
	  (If you use the sqlite3 data source with the default DB
	  file, you can omit the -c option).
488
489
490
491
492
493
494
495
496
497
498
499
500
501
        </listitem>

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

      </orderedlist>

    </section>

  </chapter>

502
503
  <chapter id="installation">
    <title>Installation</title>
504

505
506
507
508
    <section id="packages">
      <title>Packages</title>

      <para>
509
        Some operating systems or software package vendors may
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
        provide ready-to-use, pre-built software packages for
        the BIND 10 suite.
        Installing a pre-built package means you do not need to
        install build-only prerequisites and do not need to
        <emphasis>make</emphasis> the software.
      </para>

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

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

591
    <section id="build-requirements">
592
      <title>Building Requirements</title>
593
594

        <para>
595
596
          In addition to the run-time requirements (listed in
          <xref linkend="required-software"/>), building BIND 10
Jeremy C. Reed's avatar
Jeremy C. Reed committed
597
598
          from source code requires various development include headers and
          program development tools.
599
600
        </para>

601
        <note>
602
          <simpara>
603
604
605
            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
606
            libraries, to build BIND 10 from source code.
607
          </simpara>
608
609
        </note>

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

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

631
632
<!-- 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
633

634
635
        <para>
          Building BIND 10 also requires a C++ compiler and
636
          standard development headers, make, and pkg-config.
637
          BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
638
          4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
639
        </para>
640
641

        <para>
642
          Visit the user-contributed wiki at <ulink
643
644
645
646
          url="http://bind10.isc.org/wiki/SystemSpecificNotes" />
          for system-specific installation tips.
        </para>

647
648
    </section>

649
650
    <section id="install">
      <title>Installation from source</title>
651
      <para>
652
        BIND 10 is open source software written in C++ and Python.
653
654
655
656
        It is freely available in source code form from ISC as a
        downloadable tar file or via BIND 10's Git code revision control
        service. (It may also be available in pre-compiled ready-to-use
        packages from operating system vendors.)
657
658
      </para>

659
660
      <section>
        <title>Download Tar File</title>
661
662
663
664
        <para>
          Downloading a release tar file is the recommended method to
          obtain the source code.
        </para>
665

666
667
        <para>
          The BIND 10 releases are available as tar file downloads from
668
669
          <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
          Periodic development snapshots may also be available.
670
671
672
673
674
        </para>
  <!-- TODO -->
      </section>

      <section>
675
        <title>Retrieve from Git</title>
676
677
678
679
680
        <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>
681
682
683

        <note>
          <para>
684
            When using source code retrieved via Git, additional
685
            software will be required:  automake (v1.11 or newer),
686
            libtoolize, and autoconf (2.59 or newer).
687
688
689
690
            These may need to be installed.
          </para>
        </note>

691
        <para>
692
693
          The latest development code (and temporary experiments
          and un-reviewed code) is available via the BIND 10 code revision
694
          control system. This is powered by Git and all the BIND 10
695
          development is public.
696
697
          The leading development is done in the <quote>master</quote>
          branch.
698
699
        </para>
        <para>
700
          The code can be checked out from
701
          <filename>git://git.bind10.isc.org/bind10</filename>;
702
          for example:
703

704
        <screen>$ <userinput>git clone git://git.bind10.isc.org/bind10</userinput></screen>
705
        </para>
706

707
708
709
        <para>
          When checking out the code from
          the code version control system, it doesn't include the
710
711
          generated configure script, Makefile.in files, nor their
          related build files.
712
713
714
715
716
717
718
719
720
721
          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>

722
723
724
      </section>


725
      <section id="configure">
726
727
728
729
730
731
732
733
734
        <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>
735
          switch to view the different options. Some commonly-used options are:
736
737
738
739

          <variablelist>

          <varlistentry>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
740
741
            <term>--prefix</term>
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
742
              <simpara>Define the installation location (the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
743
744
                default is <filename>/usr/local/</filename>).
              </simpara>
745
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
746
747
748
749
          </varlistentry>

          <varlistentry>
            <term>--with-boost-include</term>
750
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
751
              <simpara>Define the path to find the Boost headers.
752
              </simpara>
753
            </listitem>
754
755
756
          </varlistentry>

          <varlistentry>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
757
            <term>--with-pythonpath</term>
758
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
759
760
761
              <simpara>Define the path to Python 3.1 if it is not in the
                standard execution path.
              </simpara>
762
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
763
764
765
766
          </varlistentry>

          <varlistentry>
            <term>--with-gtest</term>
767
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
768
769
770
              <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.
771
              </simpara>
772
            </listitem>
773
774
          </varlistentry>

775
776
777
778
779
780
781
782
783
784
          <varlistentry>
            <term>--without-werror</term>
            <listitem>
              <simpara>Disable the default use of the
		<option>-Werror</option> compiler flag so that
		compiler warnings aren't build failures.
              </simpara>
            </listitem>
          </varlistentry>

785
          </variablelist>
786
787
788
789
790
791
          <note>
            <para>
              For additional instructions concerning the building and installation of
              BIND 10 DHCP, see <xref linkend="dhcp-install-configure"/>.
            </para>
          </note>
792
        </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
793
  <!-- TODO: lcov -->
794
795

        <para>
796
          For example, the following configures it to
797
    find the Boost headers, find the
798
    Python interpreter, and sets the installation location:
799

800
          <screen>$ <userinput>./configure \
801
802
803
804
805
806
807
808
809
810
      --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>

811

812
813
814
815
816
      </section>

      <section>
        <title>Build</title>
        <para>
817
818
    After the configure step is complete, to build the executables
    from the C++ code and prepare the Python scripts, run:
819
820
821
822
823
824
825
826

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

      <section>
        <title>Install</title>
        <para>
Michael Graff's avatar
Michael Graff committed
827
828
          To install the BIND 10 executables, support files,
          and documentation, run:
829
830
          <screen>$ <userinput>make install</userinput></screen>
        </para>
Michael Graff's avatar
Michael Graff committed
831
        <note>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
832
          <para>The install step may require superuser privileges.</para>
Michael Graff's avatar
Michael Graff committed
833
        </note>
834
        <para>
835
836
837
838
	  If required, run <command>ldconfig</command> as root with
	  <filename>/usr/local/lib</filename> (or with ${prefix}/lib if
	  configured with --prefix) in
	  <filename>/etc/ld.so.conf</filename> (or the relevant linker
839
840
	  cache configuration file for your OS):
	  <screen>$ <userinput>ldconfig</userinput></screen>
841
842
843
844
845
846
847
848
849
850
851
        </para>
        <note>
          <para>
	    If you do not run <command>ldconfig</command> where it is
	    required, you may see errors like the following:
            <screen>
	      program: error while loading shared libraries: libb10-something.so.1:
	      cannot open shared object file: No such file or directory
	    </screen>
	  </para>
        </note>
852
853
854
855
856
857
858
859
860
861
862
863
864
      </section>

  <!-- TODO: tests -->

    </section>

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

866
  </chapter>
867

868
  <chapter id="bind10">
Jeremy C. Reed's avatar
Jeremy C. Reed committed
869
    <title>Starting BIND 10 with <command>bind10</command></title>
870
    <para>
871
872
873
      BIND 10 is started with the <command>bind10</command> command.
      It runs the <command>b10-init</command> daemon which
      starts up the required processes, and
874
      will also restart some processes that exit unexpectedly.
875
876
      <command>bind10</command> is the only command needed to start
      the BIND 10 system.
877
878
879
    </para>

    <para>
880
      After starting the <command>b10-msgq</command> communications channel,
881
      <command>b10-init</command> connects to it,
882
883
      runs the configuration manager, and reads its own configuration.
      Then it starts the other modules.
884
885
886
    </para>

    <para>
887
888
      The <command>b10-sockcreator</command>, <command>b10-msgq</command> and
      <command>b10-cfgmgr</command>
889
      services make up the core. The <command>b10-msgq</command> daemon
890
      provides the communication channel between every part of the system.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
891
      The <command>b10-cfgmgr</command> daemon is always needed by every
892
893
      module, if only to send information about themselves somewhere,
      but more importantly to ask about their own settings, and
894
895
896
      about other modules. The <command>b10-sockcreator</command> daemon
      helps allocate Internet addresses and ports as needed for BIND 10
      network services.
897
898
899
    </para>

    <para>
900
      In its default configuration, the <command>b10-init</command>
901
      master process will also start up
Jeremy C. Reed's avatar
Jeremy C. Reed committed
902
      <command>b10-cmdctl</command> for administration tools to
903
904
      communicate with the system, and
      <command>b10-stats</command> for statistics collection.
905
      The DNS and DHCP servers are not started by default.
906
907
      The configuration of components to start is covered in
      <xref linkend="bind10.components"/>.
908
909
    </para>

910
    <section id="start">
911
912
      <title>Starting BIND 10</title>
      <para>
913
914
915
916
917
        To start the BIND 10 service, simply run <command>bind10</command>
        as root.
        It will run in the foreground and your shell prompt will not
        be available. It will output various log messages as it starts up
        and is used.
918
        Run it with the <option>--verbose</option> switch to
919
920
        get additional debugging or diagnostic output.
      </para>
921
922
923
924

<!-- TODO: user switch -->

<!-- TODO:  example:  nohup /usr/local/sbin/bind10 1>bind10.log 2>&1 -->
925
926
927
928
929
930
931
932
933
934

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

935
    </section>
936
937
938

  </chapter>

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

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

      <para>
        Administrators do not communicate directly with the
957
        <command>b10-msgq</command> daemon.
958
        By default, BIND 10 uses a UNIX domain socket file named
959
        <filename>/usr/local/var/bind10/msg_socket</filename>
960
        for this interprocess communication.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
961
      </para>
962

Jeremy C. Reed's avatar
Jeremy C. Reed committed
963
964
  </chapter>

965
966
967
968
  <chapter id="cfgmgr">
    <title>Configuration manager</title>

      <para>
Michael Graff's avatar
Michael Graff committed
969
970
971
972
973
         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>
974
975

      <para>
Michael Graff's avatar
Michael Graff committed
976
977
        The <command>b10-auth</command> and <command>b10-xfrin</command>
        daemons and other components receive their configurations
978
        from the configuration manager over the <command>b10-msgq</command>
Michael Graff's avatar
Michael Graff committed
979
        command channel.
980
981
      </para>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
982
983
984
985
      <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"/>.
986
987
988
      </para>

<!-- TODO -->
Michael Graff's avatar
Michael Graff committed
989
990
      <note>
        <para>
991
          The current release only provides
Michael Graff's avatar
Michael Graff committed
992
993
994
995
996
997
          <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>
998
999
1000
1001

      <para>
        The <command>b10-cfgmgr</command> daemon can send all
        specifications and all current settings to the
Michael Graff's avatar
Michael Graff committed
1002
1003
        <command>bindctl</command> client (via
        <command>b10-cmdctl</command>).
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
        <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
1021
        <filename>/usr/local/var/bind10/b10-config.db</filename>.
1022
        (The directory is what was defined at build configure time for
1023
1024
        <option>--localstatedir</option>.
        The default is <filename>/usr/local/var/</filename>.)
Michael Graff's avatar
Michael Graff committed
1025
1026
1027
1028
        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
1029
      </para>
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044

<!--

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

-->
1045
1046

    <para>
1047
1048
      The configuration manager does not have any command line arguments.
      Normally it is not started manually, but is automatically
1049
      started using the <command>b10-init</command> master process
1050
1051
1052
1053
1054
1055
      (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
1056
1057
1058
1059
1060
1061
1062
-->

<!-- 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
1063
1064
1065
1066
1067
1068
1069
-->

  </chapter>

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

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1070
1071
1072
1073
1074
1075
1076
1077
    <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>
1078
1079
<!-- TODO: copy examples from wiki, try with wget -->

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1080
    <para>
1081
      When <command>b10-cmdctl</command> starts, it firsts
1082
1083
      asks <command>b10-cfgmgr</command> about what modules are
      running and what their configuration is (over the
1084
      <command>b10-msgq</command> channel). Then it will start listening
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1085
1086
1087
1088
1089
1090
1091
1092
1093
      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.
1094
    </para>
1095

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
<!--
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
-->

1109
1110
<!-- TODO: replace /usr/local -->
<!-- TODO: permissions -->
1111
1112
1113
    <para>The HTTPS server requires a private key,
      such as a RSA PRIVATE KEY.
      The default location is at
1114
      <filename>/usr/local/etc/bind10/cmdctl-keyfile.pem</filename>.
1115
      (A sample key is at
1116
      <filename>/usr/local/share/bind10/cmdctl-keyfile.pem</filename>.)
1117
      It also uses a certificate located at
1118
      <filename>/usr/local/etc/bind10/cmdctl-certfile.pem</filename>.
1119
      (A sample certificate is at
1120
      <filename>/usr/local/share/bind10/cmdctl-certfile.pem</filename>.)
1121
      This may be a self-signed certificate or purchased from a
1122
1123
      certification authority.
    </para>
1124
1125

    <note><para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1126
1127
1128
1129
1130
      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
1131
      a certificate needs to be first received from the BIND 10
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1132
1133
      administrator.
      The BIND 10 installation provides a sample PEM bundle that matches
1134
1135
1136
      the sample key and certificate.
    </para></note>
<!-- TODO: cross-ref -->
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1137
1138
1139

<!-- TODO
openssl req -new -x509 -keyout server.pem -out server.pem -days 365 -nodes
1140
but that is a single file, maybe this should go back to that format?
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1141
-->
1142
1143
1144
1145
1146
1147
1148

<!--
    <para>
(08:20:56) shane: It is in theory possible to run without cmdctl.
(08:21:02) shane: I think we discussed this.
    </para>
-->
1149
1150
1151
1152
1153
1154
1155

<!-- 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
1156
      <filename>/usr/local/etc/bind10/cmdctl-accounts.csv</filename>.
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
      This comma-delimited file lists the accounts with a user name,
      hashed password, and salt.
    </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.
1172
1173
      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
1174
      line argument.
1175
      Each HTTPS connection is stateless and times out in 1200 seconds
1176
      by default.  This can be
1177
      redefined by using the <option>--idle-timeout</option> command line argument.
1178
1179
    </para>

1180
    <section id="cmdctl.spec">
1181
      <title>Configuration specification for b10-cmdctl</title>
1182
      <para>
1183
        The configuration items for <command>b10-cmdctl</command> are:
1184
1185
        <varname>accounts_file</varname> which defines the path to the
        user accounts database (the default is
1186
        <filename>/usr/local/etc/bind10/cmdctl-accounts.csv</filename>);
1187
1188
        <varname>cert_file</varname> which defines the path to the
        PEM certificate file (the default is
1189
        <filename>/usr/local/etc/bind10/cmdctl-certfile.pem</filename>);
1190
1191
1192
        and
	<varname>key_file</varname> which defines the path to the
	PEM private key file (the default is
1193
        <filename>/usr/local/etc/bind10/cmdctl-keyfile.pem</filename>).
1194
      </para>
1195