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

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

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

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

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

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

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

54
55
  </bookinfo>

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

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

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

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

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

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

<!-- DHCP sponsorship by Comcast -->

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

    </section>

  </preface>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

199
      <para>
200

201
        <itemizedlist>
202

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

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

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

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

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

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

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

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

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

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

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

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

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

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

315
    </section>
316

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

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

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

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

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

  </chapter>

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

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

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

      <orderedlist>

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

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

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

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

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

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

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

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

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

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

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

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

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

      </orderedlist>

    </section>

  </chapter>

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

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

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

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

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

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

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

609
        <note>
610
          <simpara>
611
612
613
            Some operating systems have split their distribution packages into
            a run-time and a development package.  You will need to install
            the development package versions, which include header files and
Michael Graff's avatar
Michael Graff committed
614
            libraries, to build BIND 10 from source code.
615
          </simpara>
616
617
        </note>

618
619
        <para>
          Building from source code requires the Boost
620
621
622
          build-time headers
          (<ulink url="http://www.boost.org/"/>).
          At least Boost version 1.35 is required.
623
624
625
626
  <!-- TODO: we don't check for this version -->
  <!-- NOTE: jreed has tested with 1.34, 1.38, and 1.41. -->
        </para>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
627
        <para>
628
629
          To build BIND 10, also install the Botan (at least version
          1.8) and the log4cplus (at least version 1.0.3)
630
631
632
633
634
635
636
637
638
          development include headers.
        </para>

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

639
640
<!-- NOTE: _sqlite3 is only needed at test time; it is already listed
as a dependency earlier -->
Jeremy C. Reed's avatar
Jeremy C. Reed committed
641

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

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

655
656
    </section>

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

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

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

      <section>
683
        <title>Retrieve from Git</title>
684
685
686
687
688
        <para>
          Downloading this "bleeding edge" code is recommended only for
          developers or advanced users.  Using development code in a production
          environment is not recommended.
        </para>
689
690
691

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

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

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

715
716
717
        <para>
          When checking out the code from
          the code version control system, it doesn't include the
718
719
          generated configure script, Makefile.in files, nor their
          related build files.
720
721
722
723
724
725
726
727
728
729
          They can be created by running <command>autoreconf</command>
          with the <option>--install</option> switch.
          This will run <command>autoconf</command>,
          <command>aclocal</command>,
          <command>libtoolize</command>,
          <command>autoheader</command>,
          <command>automake</command>,
          and related commands.
        </para>

730
731
732
      </section>


733
      <section id="configure">
734
735
736
737
738
739
740
741
742
        <title>Configure before the build</title>
        <para>
          BIND 10 uses the GNU Build System to discover build environment
          details.
          To generate the makefiles using the defaults, simply run:
          <screen>$ <userinput>./configure</userinput></screen>
        </para>
        <para>
          Run <command>./configure</command> with the <option>--help</option>
743
          switch to view the different options. Some commonly-used options are:
744
745
746
747

          <variablelist>

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

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

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

          <varlistentry>
            <term>--with-gtest</term>
775
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
776
777
778
              <simpara>Enable building the C++ Unit Tests using the
                Google Tests framework. Optionally this can define the
                path to the gtest header files and library.
779
              </simpara>
780
            </listitem>
781
782
          </varlistentry>

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

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

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

808
          <screen>$ <userinput>./configure \
809
810
811
812
813
814
815
816
817
818
      --with-boost-include=/usr/pkg/include \
      --with-pythonpath=/usr/pkg/bin/python3.1 \
      --prefix=/opt/bind10</userinput></screen>
        </para>

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

819

820
821
822
823
824
      </section>

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

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

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

  <!-- TODO: tests -->

    </section>

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

879
  </chapter>
880

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

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

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

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

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

<!-- TODO: user switch -->

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

      <note>
        <para>
          If the setproctitle Python module is detected at start up,
          the process names for the Python-based daemons will be renamed
          to better identify them instead of just <quote>python</quote>.
          This is not needed on some operating systems.
        </para>
      </note>

948
    </section>
949
950
951

  </chapter>

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

      <para>
956
        The BIND 10 components use the <command>b10-msgq</command>
Michael Graff's avatar
Michael Graff committed
957
        message routing daemon to communicate with other BIND 10 components.
958
        The <command>b10-msgq</command> implements what is called the
Michael Graff's avatar
Michael Graff committed
959
960
961
962
963
        <quote>Command Channel</quote>.
        Processes intercommunicate by sending messages on the command
        channel.
        Example messages include shutdown, get configurations, and set
        configurations.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
964
        This Command Channel is not used for DNS message passing.
Michael Graff's avatar
Michael Graff committed
965
966
        It is used only to control and monitor the BIND 10 system.
      </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
967
968
969

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

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

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

      <para>
Michael Graff's avatar
Michael Graff committed
982
983
984
985
986
         The configuration manager, <command>b10-cfgmgr</command>,
         handles all BIND 10 system configuration.  It provides
         persistent storage for configuration, and notifies running
         modules of configuration changes.
      </para>
987
988

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

Jeremy C. Reed's avatar
Jeremy C. Reed committed
995
996
997
998
      <para>The administrator doesn't connect to it directly, but
        uses a user interface to communicate with the configuration
        manager via <command>b10-cmdctl</command>'s REST-ful interface.
        <command>b10-cmdctl</command> is covered in <xref linkend="cmdctl"/>.
999
1000
1001
      </para>

<!-- TODO -->
Michael Graff's avatar
Michael Graff committed
1002
1003
      <note>
        <para>
1004
          The current release only provides
Michael Graff's avatar
Michael Graff committed
1005
1006
1007
1008
1009
1010
          <command>bindctl</command> as a user interface to
          <command>b10-cmdctl</command>.
          Upcoming releases will provide another interactive command-line
          interface and a web-based interface.
        </para>
      </note>
1011
1012
1013
1014

      <para>
        The <command>b10-cfgmgr</command> daemon can send all
        specifications and all current settings to the
Michael Graff's avatar
Michael Graff committed
1015
1016
        <command>bindctl</command> client (via
        <command>b10-cmdctl</command>).
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
        <command>b10-cfgmgr</command> relays configurations received
        from <command>b10-cmdctl</command> to the appropriate modules.
      </para>
<!-- TODO:
        Configuration settings for itself are defined as ConfigManager.
TODO: show examples
-->

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

<!-- TODO: what about run time config to change this? -->
<!-- jelte: > config set cfgmgr/config_database <file> -->
<!-- TODO: what about command line switch to change this? -->
      <para>
        The stored configuration file is at
1034
        <filename>/usr/local/var/bind10/b10-config.db</filename>.
1035
        (The directory is what was defined at build configure time for
1036
1037
        <option>--localstatedir</option>.
        The default is <filename>/usr/local/var/</filename>.)
Michael Graff's avatar
Michael Graff committed
1038
1039
1040
1041
        The format is loosely based on JSON and is directly parseable
        python, but this may change in a future version.
        This configuration data file is not manually edited by the
        administrator.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1042
      </para>
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057

<!--

Well the specfiles have a more fixed format (they must contain specific
stuff), but those are also directly parseable python structures (and
'coincidentally', our data::element string representation is the same)

loosely based on json, tweaked to be directly parseable in python, but a
subset of that.
wiki page is http://bind10.isc.org/wiki/DataElementDesign

nope, spec files are written by module developers, and db should be done
through bindctl and friends

-->
1058
1059

    <para>
1060
1061
      The configuration manager does not have any command line arguments.
      Normally it is not started manually, but is automatically
1062
      started using the <command>b10-init</command> master process
1063
1064
1065
1066
1067
1068
      (as covered in <xref linkend="bind10"/>).
    </para>

<!-- TODO: upcoming plans:
configuration for configuration manager itself. And perhaps we might
change the messaging protocol, but an admin should never see any of that
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1069
1070
1071
1072
1073
1074
1075
-->

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

  </chapter>

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

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

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

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

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

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

<!-- TODO
openssl req -new -x509 -keyout server.pem -out server.pem -days 365 -nodes
1153
but that is a single file, maybe this should go back to that format?
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1154
-->
1155
1156
1157
1158
1159
1160
1161

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

<!-- 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
1169
      <filename>/usr/local/etc/bind10/cmdctl-accounts.csv</filename>.
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
      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.
1185
1186
      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
1187
      line argument.
1188
      Each HTTPS connection is stateless and times out in 1200 seconds
1189
      by default.  This can be
1190
      redefined by using the <option>--idle-timeout</option> command line argument.
1191
1192
    </para>

1193
    <section id="cmdctl.spec">
1194
      <title>Configuration specification for b10-cmdctl</title>
1195
      <para>
1196
        The configuration items for <command>b10-cmdctl</command> are:
1197
1198
        <varname>accounts_file</varname> which defines the path to the
        user accounts database (the default is
1199
        <filename>/usr/local/etc/bind10/cmdctl-accounts.csv</filename>);
1200
1201
        <varname>cert_file</varname> which defines the path to the
        PEM certificate file (the default is
1202
        <filename>/usr/local/etc/bind10/cmdctl-certfile.pem</filename>);
1203
1204
1205
        and
	<varname>key_file</varname> which defines the path to the
	PEM private key file (the default is
1206
        <filename>/usr/local/etc/bind10/cmdctl-keyfile.pem</filename>).
1207
      </para>
1208

1209
    </section>
1210
1211
1212

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

1216
1217
  </chapter>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1218
1219
1220
1221
  <chapter id="bindctl">
    <title>Control and configure user interface</title>

    <note><para>