userguide.xml 25.4 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<?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>
  <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.
      BIND 10 is a rewrite, using C++ and Python, to provide
      modular components for serving and maintaining DNS.
    </para>

28
29
30
31
    <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>

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

35
36
37
    <para>
      BIND 10 provides separate executables for different tasks.
      The standard components include:
38

39
      <itemizedlist>
40

41
      <listitem>
42
      <simpara><command>msgq</command> &mdash; message bus daemon</simpara>
43
44
45
46
47
      </listitem>
      <listitem>
      <simpara><command>b10-auth</command> &mdash; authoritative DNS server</simpara>
      </listitem>
      <listitem>
48
      <simpara><command>b10-cfgmgr</command> &mdash; configuration manager</simpara>
49
50
      </listitem>
      <listitem>
51
      <simpara><command>b10-cmdctl</command> REST-ful communication service</simpara>
52
      </listitem>
53
54

      <listitem>
55
      <simpara><command>b10-xfrin</command> Incoming zone transfer service</simpara>
56
57
      </listitem>

58
59
60
      <listitem>
      <simpara><command>bind10</command> &mdash; master process for BIND 10</simpara>
      </listitem>
61
62
63
64
65
66
67
68
69
70
71
      </itemizedlist>
    </para>

    <para>
      The user tools include:

      <itemizedlist>
      <listitem>
      <simpara><command>bindctl</command> &mdash; interactive administration interface</simpara>
      </listitem>
      <listitem>
72
      <simpara><command>b10-loadzone</command> &mdash; tool to load standard master zone files</simpara>
73
      </listitem>
74
<!-- TODO usermgr -->
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
      </itemizedlist>
    </para>

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

116
  <chapter id="quickstart">
117
    <title>Quick start</title>
118
    <para>
119
      This quickly covers the standard steps for installing
120
      and deploying BIND 10 as an authoritative nameserver using
121
122
      its defaults. For troubleshooting, full customizations and further
      details, see the respective chapters in the BIND 10 user guide.
123
    </para>
124
125
126
127
128
129
130
131
132
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
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192

    <itemizedlist>
    
      <listitem>
        <simpara>Install required dependencies: Python 3.1, SQLite3
          library, and Boost development headers.</simpara>
      </listitem>

      <listitem>
        <simpara>Download the BIND 10 source tarball. <!-- TODO: from -->
        </simpara>
      </listitem>

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

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

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

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

      <listitem>
        <para>Start the server:
          <screen>$ <userinput>/usr/local/sbin/bind10</userinput></screen>
        </para>
      </listitem>

      <listitem>

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

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

    </itemizedlist>

193
194
  </chapter>

195
  <chapter id="install">
196
    <title>Installation from source</title>
197
198
199
200
201
202
203
204
205
206
    <para>
    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.
    </para>

    <sect1>
      <title>Download Tar File</title>
207
      <para>The BIND 10 development snapshots and releases
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
        are available as tarball downloads.
      </para>
<!-- TODO -->
    </sect1>

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

      <screen>$ <userinput>svn co svn://bind10.isc.org/svn/bind10/trunk</userinput></screen>
228
      </para>
229

230
231
232
233
      <para>
        You don't need to retrieve the source code from subversion
        unless you are testing latest code which is not provided in the
        source tarball. Most users will just use the source tar file.
234
      </para>
235

236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
      <sect2>
        <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 <command>--install</command> 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.11 or better (for
	working Python 3.1 tests).
      </para>
255
256
257
258
259
      <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>
260
261
262
263
      </sect2>
    </sect1>

    <sect1>
264
      <title>Required Software</title>
265
      <para>
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
        BIND 10 requires Python 3.1.
      </para>

      <para>
        Building from the source tarball requires the Boost
        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.
286
      </para>
287

288
      <note><para>
289
290
291
292
293
294
295
296
297
298
299
300
301
        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.
302
303
        You may need to install them separately.
      </para></note>
304

305
      <para>
306
307
        Building BIND 10 also requires a C++ compiler and
        standard development headers.
308
309
        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.
310
      </para>
311

312
313
314
315
316
    </sect1>

    <sect1>
      <title>Supported Platforms</title>
      <para>
317
318
319
320
321
322
323
	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.

324
325
326
327
328
329
        It is planned for BIND 10 to build, install and run on
        Windows and standard Unix-type platforms.
      </para>
    </sect1>

    <sect1>
330
      <title>Configure before the build</title>
331
332
333
334
335
336
337
338
      <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 <command>--help</command>
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
        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>
388
<!-- TODO: gtest, lcov -->
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403

      <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.
404
405
      </para>

406
407
408
409
    </sect1>

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

414
415
        <screen>$ <userinput>make</userinput></screen>
      </para>
416
    </sect1>
417

418
419
    <sect1>
      <title>Install</title>
420
      <para>
421
	To install the BIND 10 executables, support files,
422
423
424
425
426
427
	and documentation, run:
        <screen>$ <userinput>make install</userinput></screen>
      </para>
      <note><para>The install step may require superuser
      privileges.</para></note>

428
429
    </sect1>

430
431
432
433
434
435
<!-- TODO: tests -->

    <sect1>
      <title>Install Hierarchy</title>
      <para>
        The following is the layout of the complete BIND 10 installation:
436
437
438
      <itemizedlist>
      <listitem>
      <simpara><filename>bin/</filename> &mdash; general tools and
439
      diagnostic clients.</simpara>
440
441
442
443
444
      </listitem>
      <listitem>
      <simpara><filename>etc/bind10/</filename> &mdash; configuration files.
      </simpara>
<!-- TODO: create the etc/bind10/ directory? -->
445
446
447
      </listitem>
      <listitem>
      <simpara><filename>lib/</filename> &mdash; libraries and
448
      python modules.</simpara>
449
450
451
452
      </listitem>
      <listitem>
      <simpara><filename>libexec/bind10/</filename> &mdash; executables that
      a user wouldn't normally run directly. Nor would they be used
453
454
      independently. These are the BIND 10 modules which are daemons
      started by the <command>bind10</command> tool.
455
456
457
458
      </simpara>
      </listitem>
      <listitem>
      <simpara><filename>sbin/</filename> &mdash; commands used by
459
      the system administrator.
460
461
462
463
      </simpara>
      </listitem>
      <listitem>
      <simpara><filename>share/bind10/</filename> &mdash; configuration
464
        specifications.
465
466
467
468
      </simpara>
      </listitem>
      <listitem>
      <simpara><filename>share/man/</filename> &mdash; manual pages (online
469
        documentation).
470
471
472
      </simpara>
      </listitem>
      <listitem>
473
474
      <simpara><filename>var/bind10/</filename> &mdash; data source and
        configuration databases.
475
<!-- TODO: move the sqlite3 database there -->
476
477
478
479
480
      </simpara>
      </listitem>
      </itemizedlist>
    </para>
    </sect1>
481
482
483
484
485
486
487
488

<!--
    <sect1 id="install.troubleshooting">
      <title>Troubleshooting</title>
      <para>
      </para>
    </sect1>
-->
489
490
  
  </chapter>
491

492
493
  <chapter id="bind10">
    <title>Starting BIND10 with bind10</title>
494
495
496
497
498
499
500
501
502
503
504
505
506
507
    <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.
508
509
510
511
512
513
    </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
514
      The <command>b10-cfgmgr</command> daemon is always needed by every
515
516
517
      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
518
519
520
521
522
      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.)
523
524
    </para>

525
526
527
528
529
530
531
532
533
534
535
536
    <sect1 id="start">
      <title>Starting BIND 10</title>
      <para>
        To start the BIND 10 service, simply run <command>bind10</command>.
        Run it with the <command>--verbose</command> switch to
        get additional debugging or diagnostic output.
      </para>
<!-- TODO: note it doesn't go into background -->
    </sect1>

  </chapter>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
  <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>

569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
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
  <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>The administrator
	 doesn't use it directly, but uses a tool like
	 <command>bindctl</command> (or other GUI or web interface)
         to communicate with the configuration manager.
      </para>

<!-- 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
        --localstatedir. The default is <filename>/usr/local/var/</filename>.)
	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>

      <para>
        The direct communication with the configuration manager is
        <command>b10-cmdctl</command> using its REST-ful interface.
        This is covered in <xref linkend="cmdctl"/>.
      </para>

<!-- TODO -->
      <note><para>
	The Y1 prototype release only provides the
	<command>bindctl</command> as a user interface to it.
        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>


<!--

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

-->
634
635

    <para>
636
637
638
639
640
641
642
643
644
      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
645
646
647
648
649
650
651
652
653
654
-->

     <para>
     </para>

<!-- 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
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
-->

  </chapter>

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

      <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>
<!-- TODO: copy examples from wiki, try with wget -->

      <para>
      When <command>b10-cmdctl</command> starts, it firsts
674
675
      asks <command>b10-cfgmgr</command> about what modules are
      running and what their configuration is (over the
676
677
      <command>msgq</command> channel). Then it will start listening
      on HTTPS for clients, such as <command>bindctl</command>.
678
    </para>
679

680
681
<!-- TODO: replace /usr/local -->
<!-- TODO: permissions -->
682
683
684
685
686
687
688
689
690
691
692
    <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
693
694
      certification authority.
    </para>
695
696

    <note><para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
697
698
699
700
701
702
703
704
      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
705
706
707
      the sample key and certificate.
    </para></note>
<!-- TODO: cross-ref -->
Jeremy C. Reed's avatar
Jeremy C. Reed committed
708
709
710
711
712

<!-- 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?
-->
713
714
715
716
717
718
719

<!--
    <para>
(08:20:56) shane: It is in theory possible to run without cmdctl.
(08:21:02) shane: I think we discussed this.
    </para>
-->
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756

<!-- 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.
      The port can be set by using the --port command line option.
      The address to listen on can be set using the --address command
      line argument.
      Each HTTPS connection is stateless and timesout in 1200 seconds
      by default.  This can be
      redefined by using the --idle-timeout command line argument.
    </para>

    <sect1 id="cmdctl.spec">
      <title>Configuration specification for b10-cmdctl</title>
757
      <para>
758
759
760
761
        The configuration items for <command>b10-cmdctl</command> are:
key_file
cert_file
accounts_file
762
      </para>
763
764
<!-- TODO -->

765
      <para>
766
767
768
769
        The control commands are:
print_settings
shutdown
print_message
770
      </para>
771
<!-- TODO -->
772
773
774
775
    </sect1>

<!--
TODO
776
777
(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
778
779
-->

780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
  </chapter>

  <chapter id="authserver">
    <title>Authoritative Server</title>
    <para>
    </para>

    <sect1>
      <title>Server Configurations</title>
      <para>
      </para>
    </sect1>

    <sect1>
      <title>Data Source Backends</title>
      <para>
      </para>
    </sect1>

    <sect1>
      <title>Loading Master Zones Files</title>
      <para>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
802
803
804
805
806
807
808
809
810
811
812
<!-- TODO
loadzone
What happens in the database? replaces existing? What if a.foo
existed but new zone file didn't have a.foo, would previous a.foo
in database be removed?

if you replace the zone foo.com, all records from the prior foo.com disappear and a whole new set appears
-->

<!--TODO: permissions for xfrin or loadzone to create the file -->

813
814
815
816
817
818
      </para>
    </sect1>

    <sect1>
      <title>Troubleshooting</title>
      <para>
819
820
821
822
823
824
825
826
827
828
829
      </para>
    </sect1>

  </chapter>

<!-- TODO: how to help: run unit tests, join lists, review trac tickets -->

  <!-- <index>    <title>Index</title> </index> -->

</book>

830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
<!--

TODO:

Overview

Getting BIND 10 Installed
  Basics
  Dependencies
  Optional
  Advanced

How Does Everything Work Together?

Need Help?

-->