userguide.xml 34.3 KB
Newer Older
1
2
3
4
5
6
<?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;" >
]>
<book>
7
8
  <?xml-stylesheet href="userguide.css" type="text/css"?>

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
  <bookinfo>
    <title>BIND 10 User Guide</title>
    <subtitle>Administrator Reference for BIND 10</subtitle>

    <copyright>
      <year>2010</year><holder>Internet Systems Consortium, Inc.</holder>
    </copyright>

<!--    <abstract><para>This is the definitive reference and user's guide for BIND 10</para></abstract> -->

  </bookinfo>

  <chapter id="intro">
    <title>Introduction</title>
    <para>
      BIND is the popular implementation of a DNS server, developer
      interfaces, and DNS tools.
26
27
      BIND 10 is a rewrite of BIND 9.  BIND 10 is written in C++ and Python
      and provides a modular environment for serving and maintaining DNS.
28
29
    </para>

30
31
32
33
34
35
    <note>
      <para>
        This guide covers the experimental prototype version of
        BIND 10.
      </para>
    </note>
36

37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
    <note>
      <para>
        BIND 10, at this time, does not provide an recursive
        DNS server. It does provide a EDNS0- and DNSSEC-capable
        authoritative DNS server.
      </para>
    </note>
    
    <para>
      BIND 10 is modular.  Part of this modularity is
      accomplished using multiple cooperating processes which, together,
      provide DNS functionality.  This is a change from the previous generation
      of BIND software, which used a single process.
    </para>
    
52
    <para>
53
54
55
56
57
58
      At first, running many different processes may seem confusing.  However,
      these processes are started, stopped, and maintained by a single command,
      <command>bind10</command>.  Additionally, most processes started by
      the <command>bind10</command> command have names starting with "b10-",
      with one exception, <command>msgq</command>.
    </para>
59

60
61
62
63
64
65
66
67
68
69
70
71
    <section id="starting_stopping">
      <title>Starting and Stopping the Server</title>
      
      <para>
        Starting and stopping the server is performed by a single command,
        <command>bind10</command>.  This command starts a master process
        which will start other processes as needed.
      </para>
      
      <para>
        Most of these are run automatically by a single command,
        <command>bind10</command> and should not be run manually.
72

73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
        <itemizedlist>
          <listitem>
            <simpara>
              <command>msgq</command> &mdash;
              message bus daemon
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <command>b10-auth</command> &mdash;
              authoritative DNS server
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <command>b10-cfgmgr</command> &mdash;
              configuration manager
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <command>b10-cmdctl</command> &mdash;
              REST-ful communication service
            </simpara>
          </listitem>
98

99
100
101
102
103
104
          <listitem>
            <simpara>
              <command>b10-xfrin</command> &mdash;
              Incoming zone transfer service
            </simpara>
          </listitem>
105

106
107
108
        </itemizedlist>
      </para>
    </section>
109

110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
    <section id="managing_once_running">
      <title>Managing BIND 10</title>
      
      <para>
        Once BIND 10 is running, two commands are used to interact directly with
        the system:
        <itemizedlist>
          <listitem>
            <simpara>
              <command>bindctl</command> &mdash;
              interactive administration interface
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <command>b10-loadzone</command> &mdash;
              tool to load standard master zone files
            </simpara>
          </listitem>
  <!-- TODO usermgr -->
        </itemizedlist>
      </para>
    </section>
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171

    <para>
      The tools and modules are covered in full detail in this users guide.
<!-- TODO point to these -->
      In addition, manual pages are also provided in the default installation.
    </para>
      
<!--
bin/
  bindctl*
  host*
lib/
  libauth
  libdns
  libexceptions
  python3.1/site-packages/isc/{cc,config}
sbin/
  bind10
share/
  share/bind10/                                       <
    auth.spec
    b10-cmdctl.pem
    bob.spec
    passwd.csv
  man/
var/
  bind10/b10-config.db
-->

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

  </chapter>

172
173
  <chapter id="installation">
    <title>Installation</title>
174

175
    <section>
176
      <title>Required Software</title>
177
      <para>
178
179
180
181
        BIND 10 requires Python 3.1.
      </para>

      <para>
182
        Building from source code requires the Boost
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
        build-time headers. At least Boost version 1.34 is required.
<!-- TODO: we don't check for this version -->
<!-- NOTE: jreed has tested with 1.34, 1.38, and 1.41. -->
      </para>

      <para>
	If the Boost System Library is detected at configure time,
	BIND 10 will be built using an alternative method for
	networking I/O using Boost ASIO support.  This provides
	asynchrony support; with ASIO the Authoritative DNS server
	can handle other queries while the processing of a TCP
	transaction stalls.
        This dependency is not required unless you need
        <!-- TODO: want --> this feature as TCP transport support is
        provided using alternative code.
198
      </para>
199

200
      <note><para>
201
202
203
204
205
206
207
208
209
210
211
212
213
        For the Y1 prototype release, the only supported data source
        backend is SQLite3. The authoritative server requires
        SQLite 3.3.9 or newer,
        and the XFRin module requires the Python _sqlite3.so module.
      </para></note>
<!-- TODO: this will change ... -->

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

      <note><para>
        Some operating systems do not provide these dependencies
	in their default installation nor standard packages
	collections.
214
215
        You may need to install them separately.
      </para></note>
216

217
      <para>
218
219
        Building BIND 10 also requires a C++ compiler and
        standard development headers.
220
221
        BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
        4.2.1, 4.3.2, and 4.4.1.
222
      </para>
223

224
    </section>
225

226
    <section>
227
228
      <title>Supported Platforms</title>
      <para>
229
230
231
232
233
234
235
	BIND 10 builds have been tested on Debian GNU/Linux 5,
	Ubuntu 9.10, NetBSD 5, Solaris 10, FreeBSD 7, and CentOS
	Linux 5.3.

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

236
237
238
        It is planned for BIND 10 to build, install and run on
        Windows and standard Unix-type platforms.
      </para>
239
240
241
242
    </section>
    
    <section id="quickstart">
      <title>Quick start</title>
243
      <para>
244
245
246
247
        This quickly covers the standard steps for installing
        and deploying BIND 10 as an authoritative nameserver using
        its defaults. For troubleshooting, full customizations and further
        details, see the respective chapters in the BIND 10 user guide.
248
      </para>
249

250
251
252
253
254
255
256
      <note>
        <simpara>
          The Y1 prototype of the b10-auth server listens on
          0.0.0.0 (all interfaces) port 5300. (This is not the standard
          domain service port.)
        </simpara>
      </note>
257

258
259
260
261
262
263
      <itemizedlist>
    
        <listitem>
          <simpara>Install required dependencies: Python 3.1, SQLite3
            library, and Boost development headers.</simpara>
        </listitem>
264

265
266
267
268
        <listitem>
          <simpara>Download the BIND 10 source tarball. <!-- TODO: from -->
          </simpara>
        </listitem>
269

270
271
272
273
274
        <listitem>
          <para>Extract the tar file:
          <screen>$ <userinput>gzcat bind10-<replaceable>VERSION</replaceable>.tar.gz | tar -xvf -</userinput></screen>
          </para>
        </listitem>
275

276
277
278
279
280
281
        <listitem>
          <para>Go into the source and run configure:
            <screen>$ <userinput>cd bind10-<replaceable>VERSION</replaceable></userinput>
  $ <userinput>./configure</userinput></screen>
          </para>
        </listitem>
282

283
284
285
286
287
        <listitem>
          <para>Build it:
            <screen>$ <userinput>make</userinput></screen>
          </para>
        </listitem>
288

289
290
291
292
293
        <listitem>
          <para>Install it (to default /usr/local):
            <screen>$ <userinput>make install</userinput></screen>
          </para>
        </listitem>
294

295
296
297
298
299
        <listitem>
          <para>Start the server:
            <screen>$ <userinput>/usr/local/sbin/bind10</userinput></screen>
          </para>
        </listitem>
300

301
        <listitem>
302

303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
         <para>Test it; for example:
            <screen>$ <userinput>dig @127.0.0.1 -p 5300 -c CH -t TXT authors.bind</userinput></screen>
         </para>
        </listitem>

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

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

319
320
321
322
323
324
      </itemizedlist>

    </section>

    <section id="install">
      <title>Installation from source</title>
325
      <para>
326
327
328
329
330
        BIND 10 is open source software written in C++ and Python.
        It is freely available in source code form from ISC via
        the Subversion code revision control system or as a downloadable
        tar file. It may also be available in pre-compiled ready-to-use
        packages from operating system vendors.
331
332
      </para>

333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
      <section>
        <title>Download Tar File</title>
        <para>The BIND 10 development snapshots and releases
          are available as tarball downloads.
        </para>
  <!-- TODO -->
      </section>

      <section>
        <title>Retrieve from Subversion</title>
        <para>
          The latest development code, including temporary experiments
          and un-reviewed code, is available via the BIND 10 code revision
          control system. This is powered by Subversion and all the BIND 10
          development is public.
          The leading development is done in the <quote>trunk</quote>
          and the first year prototype containing reviewed code is in
          <filename>branches/Y1</filename>.
        </para>
        <para>
          The code can be checked out from <filename>svn://bind10.isc.org/svn/bind10</filename>; for example to check out the trunk:
354

355
356
        <screen>$ <userinput>svn co svn://bind10.isc.org/svn/bind10/trunk</userinput></screen>
        </para>
357

358
359
360
361
362
363
        <para>
          You do not need to retrieve the source code from subversion
          unless you are testing latest code which is not provided in the
          source tarball or you are a developer.
          Most users will just use the source tar file.
        </para>
364

365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
        <section>
          <title>Generate configuration files</title>
          <para>
          When checking out the code from
          the code version control system, it doesn't include the
          generated configure script, Makefile.in files, nor the
          related configure files.
          They can be created by running <command>autoreconf</command>
          with the <option>--install</option> switch.
          This will run <command>autoconf</command>, <command>aclocal</command>,
          <command>libtoolize</command>, <command>autoheader</command>,
          <command>automake</command>, and related commands &mdash;
          and provide needed build files.
        </para>
        <para>
          This requires <command>autoconf</command> version 2.59 or newer
          and <command>automake</command> version 1.10 or better.
          (For working Python 3.1 tests, <command>automake</command>
          version 1.11 or better is needed or use the
          <option>--with-pythonpath</option> configure option described
          below).
        </para>
        <note><para>
          Some operating systems do not provide these in their
          default installation nor standard packages collections.
          You may need to install them separately.
        </para></note>
        </section>
      </section>


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

          <variablelist>

          <varlistentry>
            <term>--with-boostlib</term>
            <listitem> 
              <simpara>Define the path to find the Boost system library.
              </simpara>
            </listitem> 
          </varlistentry>

          <varlistentry>
            <term>--without-boostlib</term> or
            <term>--with-boostlib=no</term>
            <listitem> 
              <simpara>Disable the Boost ASIO support.</simpara>
            </listitem> 
          </varlistentry>

          <varlistentry>
            <term>--with-pythonpath</term>
            <listitem> 
              <simpara>Define the path to Python 3.1 if it is not in the
                standard execution path.
              </simpara>
            </listitem> 
          </varlistentry>

          <varlistentry>
            <term>--with-boost-include</term>
            <listitem> 
              <simpara>Define the path to find the Boost headers.
              </simpara>
            </listitem> 
          </varlistentry>

          <varlistentry>
            <term>--prefix</term>
            <listitem>
  	    <simpara>Define the the installation location (the
  	      default is <filename>/usr/local/</filename>).
              </simpara>
            </listitem> 
          </varlistentry>

          </variablelist>

        </para>
  <!-- TODO: gtest, lcov -->

        <para>
          For example, the following configures it to build
  	with BOOST ASIO support, find the Boost headers, find the
  	Python interpreter, and sets the installation location:

          <screen>$ <userinput>./configure --with-boostlib=/usr/pkg/lib \
      --with-boost-include=/usr/pkg/include \
      --with-pythonpath=/usr/pkg/bin/python3.1 \
      --prefix=/opt/bind10</userinput></screen>
        </para>

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

      </section>

      <section>
        <title>Build</title>
        <para>
  	After the configure step is complete, to build the executables
  	from the C++ code and prepare the Python scripts, run:

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

      <section>
        <title>Install</title>
        <para>
  	To install the BIND 10 executables, support files,
  	and documentation, run:
          <screen>$ <userinput>make install</userinput></screen>
        </para>
        <note><para>The install step may require superuser
        privileges.</para></note>

      </section>

  <!-- TODO: tests -->

      <section>
        <title>Install Hierarchy</title>
        <para>
          The following is the layout of the complete BIND 10 installation:
        <itemizedlist>
        <listitem>
        <simpara><filename>bin/</filename> &mdash; general tools and
        diagnostic clients.</simpara>
        </listitem>
        <listitem>
        <simpara><filename>etc/bind10/</filename> &mdash; configuration files.
        </simpara>
  <!-- TODO: create the etc/bind10/ directory? -->
        </listitem>
        <listitem>
        <simpara><filename>lib/</filename> &mdash; libraries and
        python modules.</simpara>
        </listitem>
        <listitem>
        <simpara><filename>libexec/bind10/</filename> &mdash; executables that
        a user wouldn't normally run directly. Nor would they be used
        independently. These are the BIND 10 modules which are daemons
        started by the <command>bind10</command> tool.
        </simpara>
        </listitem>
        <listitem>
        <simpara><filename>sbin/</filename> &mdash; commands used by
        the system administrator.
        </simpara>
        </listitem>
        <listitem>
        <simpara><filename>share/bind10/</filename> &mdash; configuration
          specifications.
        </simpara>
        </listitem>
        <listitem>
        <simpara><filename>share/man/</filename> &mdash; manual pages (online
          documentation).
        </simpara>
        </listitem>
        <listitem>
        <simpara><filename>var/bind10/</filename> &mdash; data source and
          configuration databases.
  <!-- TODO: move the sqlite3 database there -->
        </simpara>
        </listitem>
        </itemizedlist>
546
      </para>
547
548
549
550
551
552
553
554
555
556
      </section>
    </section>

  <!--
      <section id="install.troubleshooting">
        <title>Troubleshooting</title>
        <para>
        </para>
      </section>
  -->
557
558
  
  </chapter>
559

560
561
  <chapter id="bind10">
    <title>Starting BIND10 with bind10</title>
562
563
564
565
566
567
568
569
570
571
572
573
574
575
    <para>
      BIND 10 provides the <command>bind10</command> command which 
      starts up the required daemons to provide the message
      communication bus, configurations, <!-- TODO: security, -->
      and the DNS server(s).
      Also known as BoB or the Boss of BIND, <command>bind10</command>
      will also restart processes that exit.
    </para>

    <para>
      After starting the <command>msgq</command> communications channel,
      <command>bind10</command> connects to it, 
      runs the configuration manager, and reads its own configuration.
      Then it starts the other modules.
576
577
578
579
580
581
    </para>

    <para>
      The <command>msgq</command> and <command>b10-cfgmgr</command>
      services make up the core. The <command>msgq</command> daemon
      provides the communication channel between every part of the system.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
582
      The <command>b10-cfgmgr</command> daemon is always needed by every
583
584
585
      module, if only to send information about themselves somewhere,
      but more importantly to ask about their own settings, and
      about other modules.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
586
587
588
589
590
      The <command>bind10</command> master process will also startup
      <command>b10-cmdctl</command> for admins to communicate with the
      system, <command>b10-auth</command> for Authoritative DNS service,
      and <command>b10-xfrin</command> for inbound DNS zone transfers.
      (These are covered in upcoming chapters.)
591
592
    </para>

593
    <section id="start">
594
595
596
      <title>Starting BIND 10</title>
      <para>
        To start the BIND 10 service, simply run <command>bind10</command>.
597
        Run it with the <option>--verbose</option> switch to
598
599
600
        get additional debugging or diagnostic output.
      </para>
<!-- TODO: note it doesn't go into background -->
601
    </section>
602
603
604

  </chapter>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
  <chapter id="msgq">
    <title>Command channel</title>

      <para>
        The BIND 10 components use the <command>msgq</command>
        message routing daemon to intercommunicate.
        This is called the <quote>Command Channel</quote>.
        The members of the channel subscribe to listen to certain
        messages and are programmed to handle received messages.
	Example messages include shutdown, get configurations, and set
	configurations.
      </para>

      <note><simpara>
        This Command Channel is not used for DNS message passing.
      </simpara></note>

      <para>
        Administrators do not communicate directly with the
        <command>msgq</command> daemon. The only configuration is
        to choose the port number it listens on.
        By default, BIND 10 uses port 9912 for the
        <command>msgq</command> service.
        It listens on 127.0.0.1.
      </para>

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

  </chapter>

637
638
639
640
641
642
643
644
645
646
  <chapter id="cfgmgr">
    <title>Configuration manager</title>

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

      <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
647
648
649
650
	The <command>b10-auth</command> and <command>b10-xfrin</command>
	daemons and other components receive their configurations
	from the configuration manager over the <command>msgq</command>
	command channel.
651
652
      </para>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
653
654
655
656
      <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"/>.
657
658
659
660
661
      </para>

<!-- TODO -->
      <note><para>
	The Y1 prototype release only provides the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
662
663
	<command>bindctl</command> as a user interface to
        <command>b10-cmdctl</command>.
664
665
666
667
668
669
670
671
672
673
674
        Upcoming releases will provide another interactive command-line
        interface and a web-based interface.
      </para></note>

      <para>
        The <command>b10-cfgmgr</command> daemon can send all
        specifications and all current settings to the
	<command>bindctl</command> client (via
	<command>b10-cmdctl</command>).
      </para>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
      <para>
        <command>b10-cfgmgr</command> relays configurations received
        from <command>b10-cmdctl</command> to the appropriate modules.
      </para>
<!-- TODO:
        Configuration settings for itself are defined as ConfigManager.
TODO: show examples
-->

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

<!-- TODO: what about run time config to change this? -->
<!-- jelte: > config set cfgmgr/config_database <file> -->
<!-- TODO: what about command line switch to change this? -->
      <para>
        The stored configuration file is at
        <filename>/usr/local/var/bind10/b10-config.db</filename>.
        (The full path is what was defined at build configure time for
695
696
        <option>--localstatedir</option>.
        The default is <filename>/usr/local/var/</filename>.)
Jeremy C. Reed's avatar
Jeremy C. Reed committed
697
698
699
700
701
	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.
      </para>
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716

<!--

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

-->
717
718

    <para>
719
720
721
722
723
724
725
726
727
      The configuration manager does not have any command line arguments.
      Normally it is not started manually, but is automatically
      started using the <command>bind10</command> master process
      (as covered in <xref linkend="bind10"/>).
    </para>

<!-- TODO: upcoming plans:
configuration for configuration manager itself. And perhaps we might
change the messaging protocol, but an admin should never see any of that
Jeremy C. Reed's avatar
Jeremy C. Reed committed
728
729
730
731
732
733
734
-->

<!-- 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
735
736
737
738
739
740
741
-->

  </chapter>

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

Jeremy C. Reed's avatar
Jeremy C. Reed committed
742
743
744
745
746
747
748
749
    <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>
750
751
<!-- TODO: copy examples from wiki, try with wget -->

Jeremy C. Reed's avatar
Jeremy C. Reed committed
752
    <para>
753
      When <command>b10-cmdctl</command> starts, it firsts
754
755
      asks <command>b10-cfgmgr</command> about what modules are
      running and what their configuration is (over the
756
      <command>msgq</command> channel). Then it will start listening
Jeremy C. Reed's avatar
Jeremy C. Reed committed
757
758
759
760
761
762
763
764
765
      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.
766
    </para>
767

Jeremy C. Reed's avatar
Jeremy C. Reed committed
768
769
770
771
772
773
774
775
776
777
778
779
780
<!--
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
-->

781
782
<!-- TODO: replace /usr/local -->
<!-- TODO: permissions -->
783
784
785
786
787
788
789
790
791
792
793
    <para>The HTTPS server requires a private key,
      such as a RSA PRIVATE KEY.
      The default location is at
      <filename>/usr/local/etc/bind10/cmdctl-keyfile.pem</filename>.
      (A sample key is at
      <filename>/usr/local/share/bind10/cmdctl-keyfile.pem</filename>.)
      It also uses a certificate located at
      <filename>/usr/local/etc/bind10/cmdctl-certfile.pem</filename>.
      (A sample certificate is at
      <filename>/usr/local/share/bind10/cmdctl-certfile.pem</filename>.)
      This may be a self-signed certificate or purchased from a
794
795
      certification authority.
    </para>
796
797

    <note><para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
798
799
800
801
802
803
804
805
      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
      a certificate needs to be first recieved from the BIND 10
      administrator.
      The BIND 10 installation provides a sample PEM bundle that matches
806
807
808
      the sample key and certificate.
    </para></note>
<!-- TODO: cross-ref -->
Jeremy C. Reed's avatar
Jeremy C. Reed committed
809
810
811
812
813

<!-- TODO
openssl req -new -x509 -keyout server.pem -out server.pem -days 365 -nodes
but that is a single file, maybethis should go back to that format?
-->
814
815
816
817
818
819
820

<!--
    <para>
(08:20:56) shane: It is in theory possible to run without cmdctl.
(08:21:02) shane: I think we discussed this.
    </para>
-->
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847

<!-- 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
      <filename>/usr/local/etc/bind10/cmdctl-accounts.csv</filename>.
      This comma-delimited file lists the accounts with a user name,
      hashed password, and salt.
      (A sample file is at
      <filename>/usr/local/share/bind10/cmdctl-accounts.csv</filename>.
      It contains the user named <quote>root</quote> with the password
      <quote>bind10</quote>.)
    </para>

    <para>
      The administrator may create a user account with the
      <command>b10-cmdctl-usermgr</command> tool.
    </para>
<!-- TODO: show example -->

<!-- TODO: does cmdctl need to be restarted to change cert or key
or accounts database -->

    <para>
      By default the HTTPS server listens on the localhost port 8080.
848
849
      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
850
851
852
      line argument.
      Each HTTPS connection is stateless and timesout in 1200 seconds
      by default.  This can be
853
      redefined by using the <option>--idle-timeout</option> command line argument.
854
855
    </para>

856
    <section id="cmdctl.spec">
857
      <title>Configuration specification for b10-cmdctl</title>
858
      <para>
859
860
861
862
        The configuration items for <command>b10-cmdctl</command> are:
key_file
cert_file
accounts_file
863
      </para>
864
865
<!-- TODO -->

866
      <para>
867
868
869
        The control commands are:
print_settings
shutdown
870
      </para>
871
<!-- TODO -->
872
    </section>
873
874
875

<!--
TODO
876
877
(12:21:30) jinmei: I'd like to have sample session using a command line www client such as wget
(12:21:33) jinmei: btw
878
879
-->

880
881
  </chapter>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
  <chapter id="bindctl">
    <title>Control and configure user interface</title>

    <note><para>
      For the Y1 prototype release, <command>bindctl</command>
      is the only user interface. It is expected that upcoming
      releases will provide another interactive command-line
      interface and a web-based interface for controlling and
      configuring BIND 10.
    </para></note>

    <para>
      The <command>bindctl</command> tool provides an interactive
      prompt for configuring, controlling, and querying the BIND 10
      components.
897
      It communicates directly with a REST-ful interface over HTTPS
Jeremy C. Reed's avatar
Jeremy C. Reed committed
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
      provided by <command>b10-cmdctl</command>. It doesn't
      communicate to any other components directly.
    </para>

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

    <para>
      Configuration changes are actually commands to
      <command>b10-cfgmgr</command>. So when <command>bindctl</command>
      sends a configuration, it is sent to <command>b10-cmdctl</command>
      (over a HTTPS connection); then <command>b10-cmdctl</command>
      sends the command (over a <command>msgq</command> command
      channel) to <command>b10-cfgmgr</command> which then stores
      the details and relays (over a <command>msgq</command> command
      channel) the configuration on to the specified module.
    </para>

    <para>
    </para>

  </chapter>

920
921
  <chapter id="authserver">
    <title>Authoritative Server</title>
922

923
    <para>
924
925
926
927
      The <command>b10-auth</command> is the authoritative DNS server.
      It supports EDNS0 and DNSSEC. It supports IPv6.
      Normally it is started by the <command>bind10</command> master
      process.
928
929
    </para>

930
931
932
933
934
    <note><simpara>
      The Y1 prototype release listens on all interfaces and the non-standard
      port 5300.
    </simpara></note>

935
    <section>
936
      <title>Server Configurations</title>
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964

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

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

        <variablelist>
    
          <varlistentry>
            <term>database_file</term>
            <listitem> 
              <simpara>This is an optional string to define the path to find
                 the SQLite3 database file.
<!-- TODO: -->
Note: Later the DNS server will use various data source backends.
This may be a temporary setting until then.
              </simpara>
            </listitem>
          </varlistentry>

        </variablelist>

      </para>

965
      <para>
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981

        The configuration command is:

        <variablelist>

          <varlistentry>
            <term>shutdown</term>
            <listitem> 
              <simpara>Stop the authoritative DNS server.
              </simpara>
<!-- TODO: what happens when this is sent, will bind10 restart? -->
            </listitem>
          </varlistentry>

        </variablelist>

982
      </para>
983
984
985

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

986
    </section>
987

988
    <section>
989
      <title>Data Source Backends</title>
990
991
992
993
994
995
996
997
998
999

      <note><para>
        For the Y1 prototype release, <command>b10-auth</command>
        only supports the SQLite3 data source backend.
        Upcoming versions will be able to use multiple different
        data sources, such as MySQL, Berkeley DB, or in-memory DB.
      </para></note>


<!-- TODO: really is /tmp/zone.sqlite3 until fixed. -->
1000
      <para>