bind10-guide.xml 292 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>
29
30
    <title>Kea Guide</title>
    <subtitle>Administrator Reference for Kea</subtitle>
31
32

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

36
    <abstract>
37
      <para>
38
39
        Kea is an open source implementation of the Dynamic Host Configuration
        Protocol (DHCP) servers, developed and maintained by Internet Systems
40
        Consortium (ISC).
41
      </para>
42
43

      <!-- TODO: The VERSION needs to be updated -->
44
      <para>
45
        This is the reference guide for Kea version &__VERSION__;.
46
47
        The most up-to-date version of this document (in PDF, HTML,
        and plain text formats), along with other documents for
48
        Kea, can be found at <ulink url="http://kea.isc.org/docs"/>.
49
        </para> </abstract>
50

51
      <releaseinfo>This is the reference guide for Kea version
52
53
        &__VERSION__;.</releaseinfo>

54
55
  </bookinfo>

56
  <!-- todo: Preface is now empty, but leave it around now
57
58
59
  <preface>
    <title>Preface</title>
  </preface>
60
-->
61
62
63
  <chapter id="intro">
    <title>Introduction</title>
    <para>
64
65
      Kea is the next generation of DHCP servers developed by ISC.
      It supports both DHCPv4 and DHCPv6 protocols along with their
66
67
68
69
70
71
      extensions (e.g. prefix delegation). It also supports the dynamic
      updates to DNS.
    </para>

    <para>
      Kea has been initially developed as a part of the BIND 10 framework
72
73
      (<ulink url="http://bind10.isc.org"/>). In early 2014, ISC
      made the decision to discontinue active development of BIND 10 and
74
      continue development of Kea as standalone DHCP servers. As a result,
75
76
77
78
79
      the components and libraries related to the BIND10 framework and DNS
      are going to be removed from the Kea source tree over time.
      In order to remove the dependency on Python 3, the BIND 10 framework
      will be replaced by the server startup and configuration mechanisms
      written in C++.
80
81
    </para>

82
83
84
85
86
87
88
89
90
91
92
93
    <note>
      <simpara>Kea has been implemented in BIND 10 framework and to certain extent
      it still depends on various BIND 10 libraries. It also requires the BIND 10
      framework to run, because BIND 10 configuration mechanisms are used to
      configure Kea. As a result, this document still refers to BIND 10 in many
      paragraphs. The term "BIND 10" in the context of this document means
      "BIND 10 libraries and applications which are necessary for Kea to run
      and configure". The term "Kea" means "the collection of binaries and libraries
      which, as a whole, implement the DHCP protocols.
      </simpara>
    </note>

94
    <para>
95
      This guide covers Kea version &__VERSION__;.
96
    </para>
97

98
    <section>
99
      <!-- todo: revisit (maybe extend) the list of supported platforms -->
100
101
      <title>Supported Platforms</title>
      <para>
102
103
104
105
        Kea builds have been tested on (in no particular order)
        Debian GNU/Linux 6 and unstable, Ubuntu 9.10, NetBSD 5,
        Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3,
        MacOS 10.6 and 10.7, and OpenBSD 5.1.
106

107
108
        It has been tested on Sparc, i386, and amd64 hardware
        platforms.
109

110
        It is planned for Kea to build, install and run on
111
112
113
114
        Windows and standard Unix-type platforms.
      </para>
    </section>

115
    <section id="required-software">
116
117
118
      <title>Required Software at Run-time</title>

      <para>
119
        Running Kea uses various extra software which may
120
121
122
123
124
125
126
        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>

127
      <para>
128
129
130
        Kea was developed as a collection of applications within
        BIND 10 framework and it still relies on the remaining parts
        of this framework. In particular, the servers' configuration
131
        and startup are still facilitated by the modules which originate
132
133
134
135
136
137
        in BIND 10. These modules require at least Python 3.1 to run.
        They also work with Python 3.2
        (<ulink url="http://www.python.org/"/>)). The dependency
        on Python will be removed once a replacing configuration
        and startup mechanisms are developed for Kea. At this point
        Kea will be written in pure C++.
138
139
140
      </para>

      <para>
141
        Kea uses the Botan crypto library for C++
142
143
        (<ulink url="http://botan.randombit.net/"/>).
        It requires at least Botan version 1.8.
144
145
      </para>

146
      <para>
147
        Kea uses the log4cplus C++ logging library
148
149
        (<ulink url="http://log4cplus.sourceforge.net/"/>).
        It requires at least log4cplus version 1.0.3.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
150
<!-- TODO: It is recommended to use at least version .... -->
151
      </para>
152
    </section>
153

154
155
    <section id="starting_stopping">
      <title>Starting and Stopping the Server</title>
156
      <para>
157
        Kea is modular.  Part of this modularity is
158
        accomplished using multiple cooperating processes which, together,
159
        provide the server functionality.
160
161
      </para>

162
      <!-- todo: Rename processes here, once they are renamed in the source -->
163
      <para>
164
        At first, running many different processes may seem confusing.
165
166
167
168
169
170
        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:
171
      </para>
172

173
      <para>
174

175
        <itemizedlist>
176

177
178
179
          <listitem>
            <simpara>
              <command>b10-cfgmgr</command> &mdash;
180
              Configuration manager.
181
              This process maintains all of the configuration for BIND 10.
182
183
            </simpara>
          </listitem>
184

185
186
187
          <listitem>
            <simpara>
              <command>b10-cmdctl</command> &mdash;
188
              Command and control service.
189
              This process allows external control of the BIND 10 system.
190
191
            </simpara>
          </listitem>
192

193
194
          <listitem>
            <simpara>
195
196
197
              <command>b10-dhcp4</command> &mdash;
              DHCPv4 server process.
              This process responds to DHCPv4 queries from clients.
198
199
200
            </simpara>
          </listitem>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
201
202
          <listitem>
            <simpara>
203
204
205
206
207
208
209
210
211
212
213
214
215
              <command>b10-dhcp6</command> &mdash;
              DHCPv6 server process.
              This process responds to DHCPv6 queries from clients.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
              <command>b10-dhcp-ddns</command> &mdash;
              DHCP-DDNS process.
              This process acts as an intermediary between the DHCP servers
              and DNS server. It receives name update requests from the DHCP
              servers and sends DNS Update messages to the DNS servers.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
216
217
218
            </simpara>
          </listitem>

219
220
          <listitem>
            <simpara>
221
222
223
224
              <command>b10-msgq</command> &mdash;
              Message bus daemon.
              This process coordinates communication between all of the other
              BIND 10 processes.
225
226
227
            </simpara>
          </listitem>

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

237
238
239
240
241
242
243
244
          <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
245
246
247
248
249
250
251
252
          <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>

253
254
        </itemizedlist>
      </para>
255
256

      <para>
257
        These do not need to be manually started independently.
258
259
      </para>

260
    </section>
261

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

265
      <para>
266
267
        Once BIND 10 is running, a few commands are used to interact
        directly with the system:
268
269
270
271
        <itemizedlist>
          <listitem>
            <simpara>
              <command>bindctl</command> &mdash;
Jeremy C. Reed's avatar
Jeremy C. Reed committed
272
              Interactive administration interface.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
273
274
              This is a low-level command-line tool which allows
              a developer or an experienced administrator to control
275
              Kea.
276
277
            </simpara>
          </listitem>
278
279
280
          <listitem>
            <simpara>
              <command>b10-cmdctl-usermgr</command> &mdash;
Jeremy C. Reed's avatar
Jeremy C. Reed committed
281
              User access control.
282
              This tool allows an administrator to authorize additional users
283
              to manage Kea.
284
285
            </simpara>
          </listitem>
286
287
288
289
  <!-- TODO usermgr -->
        </itemizedlist>
      </para>
    </section>
290
291

    <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
292
      The tools and modules are covered in full detail in this guide.
293
294
295
<!-- TODO point to these -->
      In addition, manual pages are also provided in the default installation.
    </para>
296

297
298
299
300
301
302
303
304
305
306
307
308
<!--
bin/
  bindctl*
  host*
lib/
  libauth
  libdns
  libexceptions
  python3.1/site-packages/isc/{cc,config}
sbin/
  bind10
share/
309
  share/bind10/
310
311
    auth.spec
    b10-cmdctl.pem
312
    init.spec
313
314
315
316
317
318
319
320
    passwd.csv
  man/
var/
  bind10/b10-config.db
-->

    <para>
      BIND 10 also provides libraries and programmer interfaces
321
322
      for C++ and Python for the message bus and configuration backend,
      and, of course, DHCP. These include detailed developer
323
324
325
326
327
328
      documentation and code examples.
<!-- TODO point to this -->
    </para>

  </chapter>

329
330
331
332
333
  <chapter id="quickstart">
    <title>Quick start</title>

    <para>
        This quickly covers the standard steps for installing
334
        and deploying Kea.
335
        For further details, full customizations, and troubleshooting,
336
        see the respective chapters in the Kea guide.
337
338
    </para>

339
340
    <section id="quick-start-dhcp6">
      <title>Quick start guide for DHCPv6 service</title>
341
342
343
344
345
346
347
348
349

      <orderedlist>

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

350
351
        <!-- We may need to replace it with the link to a downloadable tarball
        once we have it. -->
352
353
        <listitem>
          <simpara>
354
355
            Checkout the latest Kea revision from the Git repository:
            <screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput> </screen>
356
357
358
359
360
          </simpara>
        </listitem>

        <listitem>
          <para>Go into the source and run configure:
361
            <screen>$ <userinput>cd kea</userinput>
362
$ <userinput>autoreconf --install</userinput>
Mukund Sivaraman's avatar
Mukund Sivaraman committed
363
$ <userinput>./configure</userinput></screen>
364
365
366
367
368
369
370
371
372
373
          </para>
        </listitem>

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

        <listitem>
374
375
          <para>Install it as root (by default to prefix
          <filename>/usr/local/</filename>):
376
377
378
379
            <screen>$ <userinput>make install</userinput></screen>
          </para>
        </listitem>

380
381
382
383
384
385
386
        <listitem>
          <para>Change directory to the install prefix (by default
          <filename>/usr/local/</filename>):
            <screen>$ <userinput>cd /usr/local/</userinput></screen>
          </para>
        </listitem>

387
388
        <listitem>
          <para>Create a user for yourself:
389
            <screen>$ <userinput>sbin/b10-cmdctl-usermgr add root</userinput></screen>
390
	  and enter a newly chosen password when prompted.
391
392
393
          </para>
        </listitem>

394
395
        <listitem>
          <para>Start the server (as root):
396
            <screen>$ <userinput>sbin/bind10</userinput></screen>
397
398
399
400
          </para>
        </listitem>

        <listitem>
401
402
403
404
          <para>DHCP components are not started in the default
	    configuration.  In another console, enable the DHCPv6
	    service (by using the <command>bindctl</command> utility
	    to configure the <command>b10-dhcp6</command> component to
405
	    run): <screen>$ <userinput>bin/bindctl</userinput></screen>
406
	    (Login with the username and password you used above to create a user.)
407
            <screen>
408
409
410
&gt; <userinput>config add Init/components b10-dhcp6</userinput>
<!-- todo: Should the kind be needed or dispensable? -->
&gt; <userinput>config set Init/components/b10-dhcp6/kind dispensable</userinput>
411
412
413
414
415
416
417
&gt; <userinput>config commit</userinput>
&gt; <userinput>quit</userinput>
            </screen>
          </para>
        </listitem>

        <listitem>
418
419
420
421
422
         <para>Test it; for example, use the
         <ulink url="http://www.isc.org/downloads/DHCP/">ISC DHCP client</ulink>
         to send DHCPv6 queries to the server and verify that the client receives a
         configuration from the server:
            <screen>$ <userinput>dhclient -6</userinput></screen>
423
424
425
426
427
428
429
430
         </para>
        </listitem>
      </orderedlist>

    </section>

  </chapter>

431
432
  <chapter id="installation">
    <title>Installation</title>
433

434
435
436
437
    <section id="packages">
      <title>Packages</title>

      <para>
438
        Some operating systems or software package vendors may
439
        provide ready-to-use, pre-built software packages for Kea.
440
441
442
443
444
445
446
447
448
449
450
451
452
        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">
453
454
      <title>Install Hierarchy</title>
      <para>
455
        The following is the standard, common layout of the
456
        complete Kea installation:
457
458
459
460
461
462
463
464
465
        <itemizedlist>
          <listitem>
           <simpara>
              <filename>bin/</filename> &mdash;
              general tools and diagnostic clients.
            </simpara>
          </listitem>
          <listitem>
          <simpara>
466
            <filename>etc/bind10/</filename> &mdash;
467
468
469
470
471
472
473
474
475
476
477
            configuration files.
          </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>lib/</filename> &mdash;
              libraries and python modules.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
478
              <filename>libexec/bind10/</filename> &mdash;
479
480
              executables that a user wouldn't normally run directly and
              are not run independently.
481
              These are the BIND 10 and Kea modules which are daemons started by
482
              the <command>b10-init</command> master process.
483
484
485
486
487
488
489
490
491
492
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>sbin/</filename> &mdash;
              commands used by the system administrator.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
493
              <filename>share/bind10/</filename> &mdash;
494
495
496
497
498
              configuration specifications.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
499
              <filename>share/doc/bind10/</filename> &mdash;
500
501
502
503
504
505
506
507
508
509
510
              this guide and other supplementary documentation.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <filename>share/man/</filename> &mdash;
              manual pages (online documentation).
            </simpara>
          </listitem>
          <listitem>
            <simpara>
511
              <filename>var/bind10/</filename> &mdash;
512
513
514
515
516
517
518
              data source and configuration databases.
            </simpara>
          </listitem>
        </itemizedlist>
      </para>
    </section>

519
    <section id="build-requirements">
520
      <title>Building Requirements</title>
521
522

        <para>
523
          In addition to the run-time requirements (listed in
524
          <xref linkend="required-software"/>), building Kea
Jeremy C. Reed's avatar
Jeremy C. Reed committed
525
526
          from source code requires various development include headers and
          program development tools.
527
528
        </para>

529
        <note>
530
          <simpara>
531
532
533
            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
534
            libraries, to build Kea from source code.
535
          </simpara>
536
537
        </note>

538
539
        <para>
          Building from source code requires the Boost
540
541
542
          build-time headers
          (<ulink url="http://www.boost.org/"/>).
          At least Boost version 1.35 is required.
543
544
545
546
  <!-- 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
547
        <para>
548
          To build Kea, also install the Botan (at least version
549
          1.8) and the log4cplus (at least version 1.0.3)
550
551
552
553
554
555
556
557
558
          development include headers.
        </para>

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

559
560
<!-- 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
561

562
        <para>
563
          Building Kea also requires a C++ compiler and
564
          standard development headers, make, and pkg-config.
565
          Kea builds have been tested with GCC g++ 3.4.3, 4.1.2,
566
          4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
567
        </para>
568
569

        <para>
570
          Visit the user-contributed wiki at <ulink
571
          url="http://kea.isc.org/wiki/SystemSpecificNotes" />
572
573
574
          for system-specific installation tips.
        </para>

575
576
    </section>

577
578
    <section id="install">
      <title>Installation from source</title>
579
      <para>
580
581
        Kea is open source software written in C++ (some components of the
        BIND 10 framework are written in Python).
582
        It is freely available in source code form from ISC as a
583
        downloadable tar file or via Kea Git code revision control
584
585
        service. (It may also be available in pre-compiled ready-to-use
        packages from operating system vendors.)
586
587
      </para>

588
      <section>
589

590
        <title>Download Tar File</title>
591
        <para>
592
593
594
          Kea 0.8 is available as a part of BIND10 1.2 release, which is
          a final release of BIND10 from ISC. This release can be downloaded
          from: <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
595
596
597
598
        </para>
      </section>

      <section>
599
        <title>Retrieve from Git</title>
600
601
602
603
604
        <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>
605
606
607

        <note>
          <para>
608
            When using source code retrieved via Git, additional
609
            software will be required:  automake (v1.11 or newer),
610
            libtoolize, and autoconf (2.59 or newer).
611
612
613
614
            These may need to be installed.
          </para>
        </note>

615
        <para>
616
          The latest development code (and temporary experiments
617
618
          and un-reviewed code) is available via the Kea code revision
          control system. This is powered by Git and all the Kea
619
          development is public.
620
621
          The leading development is done in the <quote>master</quote>
          branch.
622
623
        </para>
        <para>
624
          The code can be checked out from
625
          <filename>git://git.kea.isc.org/kea</filename>;
626
          for example:
627

628
        <screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput></screen>
629
        </para>
630

631
632
633
        <para>
          When checking out the code from
          the code version control system, it doesn't include the
634
635
          generated configure script, Makefile.in files, nor their
          related build files.
636
637
638
639
640
641
642
643
644
645
          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>

646
647
648
      </section>


649
      <section id="configure">
650
651
        <title>Configure before the build</title>
        <para>
652
          Kea uses the GNU Build System to discover build environment
653
654
655
656
657
658
          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>
659
          switch to view the different options. Some commonly-used options are:
660
661
662
663

          <variablelist>

          <varlistentry>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
664
665
            <term>--prefix</term>
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
666
              <simpara>Define the installation location (the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
667
668
                default is <filename>/usr/local/</filename>).
              </simpara>
669
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
670
671
672
673
          </varlistentry>

          <varlistentry>
            <term>--with-boost-include</term>
674
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
675
              <simpara>Define the path to find the Boost headers.
676
              </simpara>
677
            </listitem>
678
679
680
          </varlistentry>

          <varlistentry>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
681
            <term>--with-pythonpath</term>
682
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
683
684
685
              <simpara>Define the path to Python 3.1 if it is not in the
                standard execution path.
              </simpara>
686
            </listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
687
688
689
690
          </varlistentry>

          <varlistentry>
            <term>--with-gtest</term>
691
            <listitem>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
692
693
694
              <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.
695
              </simpara>
696
            </listitem>
697
698
          </varlistentry>

699
700
701
702
703
704
705
706
707
708
          <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>

709
          </variablelist>
710
711
712
          <note>
            <para>
              For additional instructions concerning the building and installation of
713
              Kea, see <xref linkend="dhcp-install-configure"/>.
714
715
            </para>
          </note>
716
        </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
717
  <!-- TODO: lcov -->
718
719

        <para>
720
          For example, the following configures it to
721
    find the Boost headers, find the
722
    Python interpreter, and sets the installation location:
723

724
          <screen>$ <userinput>./configure \
725
726
727
728
729
730
731
732
733
734
      --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>

735

736
737
738
739
740
      </section>

      <section>
        <title>Build</title>
        <para>
741
742
    After the configure step is complete, to build the executables
    from the C++ code and prepare the Python scripts, run:
743
744
745
746
747
748
749
750

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

      <section>
        <title>Install</title>
        <para>
751
          To install the Kea executables, support files,
Michael Graff's avatar
Michael Graff committed
752
          and documentation, run:
753
754
          <screen>$ <userinput>make install</userinput></screen>
        </para>
755
        <para>
756
757
758
          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.
759
        </para>
Michael Graff's avatar
Michael Graff committed
760
        <note>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
761
          <para>The install step may require superuser privileges.</para>
Michael Graff's avatar
Michael Graff committed
762
        </note>
763
        <para>
764
765
766
767
	  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
768
769
	  cache configuration file for your OS):
	  <screen>$ <userinput>ldconfig</userinput></screen>
770
771
772
773
774
775
        </para>
        <note>
          <para>
	    If you do not run <command>ldconfig</command> where it is
	    required, you may see errors like the following:
            <screen>
776
	      program: error while loading shared libraries: libkea-something.so.1:
777
778
779
780
	      cannot open shared object file: No such file or directory
	    </screen>
	  </para>
        </note>
781
782
783
784
785
786
787
788
789
790
791
792
793
      </section>

  <!-- TODO: tests -->

    </section>

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

795
  </chapter>
796

797
  <chapter id="bind10">
798
    <title>Starting Kea with <command>bind10</command></title>
799
    <para>
800
      Kea is started with the <command>bind10</command> command.
801
802
      It runs the <command>b10-init</command> daemon which
      starts up the required processes, and
803
      will also restart some processes that exit unexpectedly.
804
      <command>bind10</command> is the only command needed to start Kea.
805
806
807
    </para>

    <para>
808
      After starting the <command>b10-msgq</command> communications channel,
809
      <command>b10-init</command> connects to it,
810
811
      runs the configuration manager, and reads its own configuration.
      Then it starts the other modules.
812
813
814
    </para>

    <para>
815
816
      The <command>b10-sockcreator</command>, <command>b10-msgq</command> and
      <command>b10-cfgmgr</command>
817
      services make up the core. The <command>b10-msgq</command> daemon
818
      provides the communication channel between every part of the system.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
819
      The <command>b10-cfgmgr</command> daemon is always needed by every
820
821
      module, if only to send information about themselves somewhere,
      but more importantly to ask about their own settings, and
822
      about other modules. The <command>b10-sockcreator</command> daemon
823
824
      can allocate Internet addresses and ports needed by network services
      but is currently unused by DHCP servers.
825
826
827
    </para>

    <para>
828
      In its default configuration, the <command>b10-init</command>
829
      master process will also start up
Jeremy C. Reed's avatar
Jeremy C. Reed committed
830
      <command>b10-cmdctl</command> for administration tools to
831
832
      communicate with the system, and
      <command>b10-stats</command> for statistics collection.
833
      The DHCP servers are not started by default.
834
      The configuration of components to start is covered in
835
      <xref linkend="kea.components"/>.
836
837
    </para>

838
    <section id="start">
839
      <title>Starting Kea</title>
840
      <para>
841
842
843
844
845
        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.
846
        Run it with the <option>--verbose</option> switch to
847
848
        get additional debugging or diagnostic output.
      </para>
849
850
851
852

<!-- TODO: user switch -->

<!-- TODO:  example:  nohup /usr/local/sbin/bind10 1>bind10.log 2>&1 -->
853
854
855
856
857
858
859
860
861
862

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

863
    </section>
864
865
866

  </chapter>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
867
868
869
870
  <chapter id="msgq">
    <title>Command channel</title>

      <para>
871
        The BIND 10 components use the <command>b10-msgq</command>
872
        message routing daemon to communicate with Kea components.
873
        The <command>b10-msgq</command> implements what is called the
Michael Graff's avatar
Michael Graff committed
874
875
876
877
878
        <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
879
        This Command Channel is not used for DNS message passing.
Michael Graff's avatar
Michael Graff committed
880
881
        It is used only to control and monitor the BIND 10 system.
      </para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
882
883
884

      <para>
        Administrators do not communicate directly with the
885
        <command>b10-msgq</command> daemon.
886
        By default, BIND 10 uses a UNIX domain socket file named
887
        <filename>/usr/local/var/bind10/msg_socket</filename>
888
        for this interprocess communication.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
889
      </para>
890

Jeremy C. Reed's avatar
Jeremy C. Reed committed
891
892
  </chapter>

893
894
895
896
  <chapter id="cfgmgr">
    <title>Configuration manager</title>

      <para>
Michael Graff's avatar
Michael Graff committed
897
         The configuration manager, <command>b10-cfgmgr</command>,
898
         handles all system configuration.  It provides
Michael Graff's avatar
Michael Graff committed
899
900
901
         persistent storage for configuration, and notifies running
         modules of configuration changes.
      </para>
902
903

      <para>
904
905
        The <command>b10-dhcp6</command>, <command>b10-dhcp4</command> and
        <command>b10-dhcp-ddns</command> daemons receive their configurations
906
        from the configuration manager over the <command>b10-msgq</command>
Michael Graff's avatar
Michael Graff committed
907
        command channel.
908
909
      </para>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
910
911
912
913
      <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"/>.
914
915
916
      </para>

<!-- TODO -->
Michael Graff's avatar
Michael Graff committed
917
918
      <note>
        <para>
919
920
          In future releases of Kea, the architecture which originates in
          the BIND 10 project will be replaced by the new mechanisms to start
921
922
          and configure Kea. The new mechanisms will use a file based
          configuration.
Michael Graff's avatar
Michael Graff committed
923
924
        </para>
      </note>
925
926
927
928

      <para>
        The <command>b10-cfgmgr</command> daemon can send all
        specifications and all current settings to the
Michael Graff's avatar
Michael Graff committed
929
930
        <command>bindctl</command> client (via
        <command>b10-cmdctl</command>).
Jeremy C. Reed's avatar
Jeremy C. Reed committed
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
        <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
948
        <filename>/usr/local/var/bind10/b10-config.db</filename>.
949
        (The directory is what was defined at build configure time for
950
951
        <option>--localstatedir</option>.
        The default is <filename>/usr/local/var/</filename>.)
Michael Graff's avatar
Michael Graff committed
952
953
954
955
        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
956
      </para>
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971

<!--

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

-->
972
973

    <para>
974
975
      The configuration manager does not have any command line arguments.
      Normally it is not started manually, but is automatically
976
      started using the <command>b10-init</command> master process
977
978
979
980
981
982
      (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
983
984
985
986
987
988
989
-->

<!-- 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
990
991
992
993
994
995
996
-->

  </chapter>

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

Jeremy C. Reed's avatar
Jeremy C. Reed committed
997
998
999
1000
1001
1002
1003
1004
    <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>
1005
1006
<!-- TODO: copy examples from wiki, try with wget -->

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1007
    <para>
1008
      When <command>b10-cmdctl</command> starts, it firsts
1009
1010
      asks <command>b10-cfgmgr</command> about what modules are
      running and what their configuration is (over the
1011
      <command>b10-msgq</command> channel). Then it will start listening
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1012
1013
1014
1015
1016
1017
1018
1019
1020
      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.
1021
    </para>
1022

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
<!--
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
-->

1036
1037
<!-- TODO: replace /usr/local -->
<!-- TODO: permissions -->
1038
1039
1040
    <para>The HTTPS server requires a private key,
      such as a RSA PRIVATE KEY.
      The default location is at
1041
      <filename>/usr/local/etc/bind10/cmdctl-keyfile.pem</filename>.
1042
      (A sample key is at
1043
      <filename>/usr/local/share/bind10/cmdctl-keyfile.pem</filename>.)
1044
      It also uses a certificate located at
1045
      <filename>/usr/local/etc/bind10/cmdctl-certfile.pem</filename>.
1046
      (A sample certificate is at
1047
      <filename>/usr/local/share/bind10/cmdctl-certfile.pem</filename>.)
1048
      This may be a self-signed certificate or purchased from a
1049
1050
      certification authority.
    </para>
1051
1052

    <note><para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1053
1054
1055
1056
1057
      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
1058
      a certificate needs to be first received from the BIND 10
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1059
      administrator.
1060
      The Kea installation provides a sample PEM bundle that matches
1061
1062
1063
      the sample key and certificate.
    </para></note>
<!-- TODO: cross-ref -->
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1064
1065
1066

<!-- TODO
openssl req -new -x509 -keyout server.pem -out server.pem -days 365 -nodes
1067
but that is a single file, maybe this should go back to that format?
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1068
-->
1069
1070
1071
1072
1073
1074
1075

<!--
    <para>
(08:20:56) shane: It is in theory possible to run without cmdctl.
(08:21:02) shane: I think we discussed this.
    </para>
-->
1076
1077
1078
1079
1080
1081
1082

<!-- 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
1083
      <filename>/usr/local/etc/bind10/cmdctl-accounts.csv</filename>.
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
      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.
1099
1100
      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
1101
      line argument.
1102
      Each HTTPS connection is stateless and times out in 1200 seconds
1103
      by default.  This can be
1104
      redefined by using the <option>--idle-timeout</option> command line argument.
1105
1106
    </para>