</section>
- </chapter>
-
- <chapter id="bind10">
- <title>Starting Kea with <command>bind10</command></title>
- <para>
- Kea is started with the <command>bind10</command> command.
- It runs the <command>b10-init</command> daemon which
- starts up the required processes, and
- will also restart some processes that exit unexpectedly.
- <command>bind10</command> is the only command needed to start Kea.
- </para>
-
- <para>
- After starting the <command>b10-msgq</command> communications channel,
- <command>b10-init</command> connects to it,
- runs the configuration manager, and reads its own configuration.
- Then it starts the other modules.
- </para>
-
- <para>
- The <command>b10-sockcreator</command>, <command>b10-msgq</command> and
- <command>b10-cfgmgr</command>
- services make up the core. The <command>b10-msgq</command> daemon
- provides the communication channel between every part of the system.
- The <command>b10-cfgmgr</command> daemon is always needed by every
- module, if only to send information about themselves somewhere,
- but more importantly to ask about their own settings, and
- about other modules. The <command>b10-sockcreator</command> daemon
- can allocate Internet addresses and ports needed by network services
- but is currently unused by DHCP servers.
- </para>
-
- <para>
- In its default configuration, the <command>b10-init</command>
- master process will also start up
- <command>b10-cmdctl</command> for administration tools to
- communicate with the system, and
- <command>b10-stats</command> for statistics collection.
- The DHCP servers are not started by default.
- The configuration of components to start is covered in
- <xref linkend="kea.components"/>.
- </para>
-
- <section id="start">
- <title>Starting Kea</title>
- <para>
- 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.
- Run it with the <option>--verbose</option> switch to
- get additional debugging or diagnostic output.
- </para>
-
-<!-- TODO: user switch -->
-
-<!-- TODO: example: nohup /usr/local/sbin/bind10 1>bind10.log 2>&1 -->
-
- <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>
-
- </section>
-
- </chapter>
-
- <chapter id="msgq">
- <title>Command channel</title>
-
- <para>
- The BIND 10 components use the <command>b10-msgq</command>
- message routing daemon to communicate with Kea components.
- The <command>b10-msgq</command> implements what is called the
- <quote>Command Channel</quote>.
- Processes intercommunicate by sending messages on the command
- channel.
- Example messages include shutdown, get configurations, and set
- configurations.
- This Command Channel is not used for DNS message passing.
- It is used only to control and monitor the BIND 10 system.
- </para>
-
- <para>
- Administrators do not communicate directly with the
- <command>b10-msgq</command> daemon.
- By default, BIND 10 uses a UNIX domain socket file named
- <filename>/usr/local/var/bind10/msg_socket</filename>
- for this interprocess communication.
- </para>
-
- </chapter>
-
- <chapter id="cfgmgr">
- <title>Configuration manager</title>
-
- <para>
- The configuration manager, <command>b10-cfgmgr</command>,
- handles all system configuration. It provides
- persistent storage for configuration, and notifies running
- modules of configuration changes.
- </para>
-
- <para>
- The <command>b10-dhcp6</command>, <command>b10-dhcp4</command> and
- <command>b10-dhcp-ddns</command> daemons receive their configurations
- from the configuration manager over the <command>b10-msgq</command>
- command channel.
- </para>
-
- <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"/>.
- </para>
-
-<!-- TODO -->
- <note>
- <para>
- In future releases of Kea, the architecture which originates in
- the BIND 10 project will be replaced by the new mechanisms to start
- and configure Kea. The new mechanisms will use a file based
- configuration.
- </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>).
- <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 directory is what was defined at build configure time for
- <option>--localstatedir</option>.
- 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>
-
-<!--
-
-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
-
--->
-
- <para>
- The configuration manager does not have any command line arguments.
- Normally it is not started manually, but is automatically
- started using the <command>b10-init</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
--->
-
-<!-- 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
--->
-
- </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
- asks <command>b10-cfgmgr</command> about what modules are
- running and what their configuration is (over the
- <command>b10-msgq</command> channel). Then it will start listening
- on HTTPS for clients — the user interface — 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.
- </para>
-
-<!--
-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
--->
-
-<!-- TODO: replace /usr/local -->
-<!-- TODO: permissions -->
- <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
- certification authority.
- </para>
-
- <note><para>
- 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 received from the BIND 10
- administrator.
- The Kea installation provides a sample PEM bundle that matches
- the sample key and certificate.
- </para></note>
-<!-- TODO: cross-ref -->
-
-<!-- TODO
-openssl req -new -x509 -keyout server.pem -out server.pem -days 365 -nodes
-but that is a single file, maybe this should go back to that format?
--->
-
-<!--
- <para>
-(08:20:56) shane: It is in theory possible to run without cmdctl.
-(08:21:02) shane: I think we discussed this.
- </para>
--->
-
-<!-- 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.
- </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 <option>--port</option> command line option.
- The address to listen on can be set using the <option>--address</option> command
- line argument.
- Each HTTPS connection is stateless and times out in 1200 seconds
- by default. This can be
- redefined by using the <option>--idle-timeout</option> command line argument.
- </para>
-
- <section id="cmdctl.spec">
- <title>Configuration specification for b10-cmdctl</title>
- <para>
- The configuration items for <command>b10-cmdctl</command> are:
- <varname>accounts_file</varname> which defines the path to the
- user accounts database (the default is
- <filename>/usr/local/etc/bind10/cmdctl-accounts.csv</filename>);
- <varname>cert_file</varname> which defines the path to the
- PEM certificate file (the default is
- <filename>/usr/local/etc/bind10/cmdctl-certfile.pem</filename>);
- and
- <varname>key_file</varname> which defines the path to the
- PEM private key file (the default is
- <filename>/usr/local/etc/bind10/cmdctl-keyfile.pem</filename>).
- </para>
-
- </section>
-
-<!--
-TODO
-(12:21:30) jinmei: I'd like to have sample session using a command line www client such as wget
--->
-
- </chapter>
-
- <chapter id="bindctl">
- <title>Control and configure user interface</title>
-
- <note><para>
- <command>bindctl</command> has an internal command history, as
- well as tab-completion for most of the commands and arguments.
- However, these are only enabled if the python readline module
- is available on the system. If not, neither of these
- features will be supported.
- </para></note>
-
- <para>
- The <command>bindctl</command> tool provides an interactive
- prompt for configuring, controlling, and querying the Kea
- components.
- It communicates directly with a REST-ful interface over HTTPS
- provided by <command>b10-cmdctl</command>. It doesn't
- communicate to any other components directly.
- </para>
-
- <section id="bindctl_commandline_options">
- <title>bindctl command-line options</title>
- <variablelist>
- <varlistentry>
- <term>-a <replaceable><address></replaceable>, --address=<replaceable><address></replaceable></term>
- <listitem>
- <simpara>
- IP address that BIND 10's <command>b10-cmdctl</command>
- module is listening on. By default, this is 127.0.0.1.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-c <replaceable><certificate file></replaceable>, --certificate-chain=<replaceable><certificate file></replaceable></term>
- <listitem>
- <simpara>
- PEM-formatted server certificate file. When this option is
- given, <command>bindctl</command> will verify the server
- certificate using the given file as the root of the
- certificate chain. If not specified, <command>bindctl
- </command> does not validate the certificate.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--csv-file-dir=<replaceable><csv file></replaceable></term>
- <listitem>
- <simpara>
- <command>bindctl</command> stores the username and
- password for logging in in a file called
- <filename>default_user.csv</filename>;
- this option specifies the directory where this file is
- stored and read from. When not specified,
- <filename>~/.bind10/</filename> is used.
- <note>Currently, this file contains an unencrypted password.</note>
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-h, --help</term>
- <listitem>
- <simpara>
- Shows a short overview of the command-line options of
- <command>bindctl</command>, and exits.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>--version</term>
- <listitem>
- <simpara>
- Shows the version of <command>bindctl</command>, and exits.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>-p <replaceable><port number></replaceable>, --port=<replaceable><port number></replaceable></term>
- <listitem>
- <simpara>
- Port number that BIND 10's <command>b10-cmdctl</command>
- module is listening on. By default, this is port 8080.
- </simpara>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section id="bindctl_general_syntax">
- <title>General syntax of bindctl commands</title>
- The <command>bindctl</command> tool is an interactive
- command-line tool, with dynamic commands depending on the
- BIND 10 modules that are running. There are a number of
- fixed commands that have no module and that are always
- available.
-
- The general syntax of a command is
-
- <screen><userinput><module> <command> <replaceable>[argument(s)]</replaceable></userinput></screen>
-
- For example, the Init module has a 'shutdown' command to shut down
- BIND 10, with an optional argument 'help':
-
- <screen>> <userinput>Init shutdown help</userinput>
-Command shutdown (Shut down BIND 10 and Kea)
- help (Get help for command)
-This command has no parameters
- </screen>
- There are no mandatory arguments, only the optional 'help'.
- </section>
-
- <section id="bindctl_help">
- <title>Bindctl help</title>
- <command>help</command> is both a command and an option that is available to all other commands. When run as a command directly, it shows the available modules.
- <screen>> <userinput>help</userinput>
-usage: <module name> <command name> [param1 = value1 [, param2 = value2]]
-Type Tab character to get the hint of module/command/parameters.
-Type "help(? h)" for help on bindctl.
-Type "<module_name> help" for help on the specific module.
-Type "<module_name> <command_name> help" for help on the specific command.
-
-Available module names:
-<emphasis>(list of modules)</emphasis>
- </screen>
-
- When 'help' is used as a command to a module, it shows the supported commands for the module; for example:
- <screen>> <userinput>Init help</userinput>
-Module Init Master process
-Available commands:
- help Get help for module.
- shutdown Shut down BIND10 and Kea
- ping Ping the Init process
- show_processes
- List the running BIND10 and Kea processes
- </screen>
-
- And when added to a module command, it shows the description and parameters of that specific command; for example:
- <screen>> <userinput>DhcpDdns shutdown help</userinput>
-Command shutdown (Shuts down b10-dhcp-ddns module server.)
- help (Get help for command)
-Parameters:
- type (string, optional)
- values: normal (default), now, or drain_first
- </screen>
-
- </section>
-
- <section id="bindctl_command_arguments">
- <title>Command arguments</title>
- <simpara>
- Commands can have arguments, which can be either optional or
- mandatory. They can be specified by name
- (e.g. <command><replaceable><command></replaceable> <replaceable><argument name>=<argument value></replaceable></command>), or positionally,
- (e.g. <command><replaceable><command></replaceable> <replaceable><argument value 1></replaceable> <replaceable><argument value 2></replaceable></command>).
- </simpara>
- <simpara>
- <command><replaceable><command></replaceable> <replaceable>help</replaceable></command>
- shows the arguments a command supports and which of those are
- mandatory, and in which order the arguments are expected if
- positional arguments are used.
- </simpara>
- <simpara>
- For example, the <command>shutdown</command> command of the DhcpDdns
- module, as shown in the last example of the previous section, has
- one optional argument which is appended right after the command:
- <screen>> <userinput>DhcpDdns shutdown now</userinput></screen>
- But since the class is optional (defaulting to normal), leaving it out
- works as well:
- <screen>> <userinput>DhcpDdns shutdown</userinput></screen>
- </simpara>
- <simpara>
- The arguments can also be provided with their names:
- <screen>> <userinput>DhcpDdns shutdown type="now"</userinput></screen>
- </simpara>
- </section>
-
- <section id="bindctl_module_commands">
- <title>Module commands</title>
- Each module has its own set of commands (if any), which will only be
- available if the module is running.
- </section>
-
- <section>
- <title>Configuration commands</title>
- Configuration commands are used to view and change the configuration
- of BIND 10 and its modules. Module configuration is only shown if
- that module is running, but similar to commands, there are a number
- of top-level configuration items that are always available (for
- instance <varname>tsig_keys</varname> and
- <varname>data_sources</varname>).
-
- Configuration changes (set, unset, add and remove) are done locally
- first, and have no immediate effect. The changes can be viewed with
- <command>config diff</command>, and either reverted
- (<command>config revert</command>), or committed
- (<command>config commit</command>).
- In the latter case, all local changes are submitted
- to the configuration manager, which verifies them, and if they are
- accepted, applied and saved in persistent storage.
-
- When identifying items in configuration commands, the format is
- <screen><userinput>Module/example/item</userinput></screen>
- Sub-elements of names, lists and sets (see <xref linkend=
- "bindctl_configuration_data_types"/>) are separated with the '/'
- character, and list indices are identified with [<replaceable><index></replaceable>]; for example:
-
- <screen><userinput>Module/example/list[2]/foo</userinput></screen>
-
- <section id="bindctl_configuration_command_list">
- <title>List of configuration commands</title>
- The following configuration commands are available:
- <variablelist>
- <varlistentry>
- <term>show [all] [item name]</term>
- <listitem>
- <simpara>
- Shows the current configuration of the given item. If 'all'
- is given, it will recurse through the entire set, and show
- every nested value.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>show_json [item name]</term>
- <listitem>
- <simpara>
- Shows the full configuration of the given item in JSON format.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>add <item name> [value]</term>
- <listitem>
- <simpara>
- Add an entry to configuration list or a named set (see <xref
- linkend="bindctl_configuration_data_types"/>).
- When adding to a list, the command has one optional
- argument, a value to add to the list. The value must
- be in correct JSON and complete. When adding to a
- named set, it has one mandatory parameter (the name to
- add), and an optional parameter value, similar to when
- adding to a list. In either case, when no value is
- given, an entry will be constructed with default
- values.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>remove</term>
- <listitem>
- <simpara>
- Remove an item from a configuration list or a named set.
- When removing an item for a list, either the index needs to
- be specified, or the complete value of the element to remove
- must be specified (in JSON format).
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>set <item name> <value></term>
- <listitem>
- <simpara>
- Directly set the value of the given item to the given value.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>unset <item name></term>
- <listitem>
- <simpara>
- Remove any user-specified value for the given item.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>diff</term>
- <listitem>
- <simpara>
- Show all current local changes that have not been
- committed yet.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>revert</term>
- <listitem>
- <simpara>
- Revert all local changes without committing them.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>commit</term>
- <listitem>
- <simpara>
- Send all local changes to the configuration manager, which
- will validate them, and apply them if validation succeeds.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>go</term>
- <listitem>
- <simpara>
- Go to a specific configuration part, similar to the 'cd'
- command in a shell.
- <note>There are a number of problems with the current
- implementation of go within <command>bindctl</command>,
- and we recommend not using it for general cases.</note>
- </simpara>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section id="bindctl_configuration_data_types">
- <title>Configuration data types</title>
- Configuration data can be of different types, which can be modified
- in ways that depend on the types. There are a few syntax
- restrictions on these types, but only basic ones. Modules may impose
- additional restrictions on the values of elements.
- <variablelist>
- <varlistentry>
- <term>integer</term>
- <listitem>
- <simpara>
- A basic integer; can be set directly with
- <command>config set</command>, to any integer
- value. The value must not be quoted, or else, it
- will be parsed as a string.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>real</term>
- <listitem>
- <simpara>
- A basic floating point number; can be set
- directly with <command>config set</command>, to
- any floating point value. The value must not be
- quoted, or else, it will be parsed as a string.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>boolean</term>
- <listitem>
- <simpara>
- A basic boolean value; can be set directly with
- <command>config set</command>, to either
- <command>true</command> or
- <command>false</command>. The value must not be
- quoted, or else, it will be parsed as a
- string. Integer values are not allowed.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>string</term>
- <listitem>
- <simpara>
- A basic string value; can be set directly with
- <command>config set</command> to any
- string. Double quotation marks are optional.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>null</term>
- <listitem>
- <simpara>
- This is a special type representing 'no value at all'; usable in compound structures that have optional elements that are not set.
- </simpara>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>maps</term>
- <listitem>
- <simpara>
- Maps are (pre-defined) compound collections of other
- elements of any other type. They are not usually
- modified directly, but their elements are. Every
- top-level element for a module is a map containing
- the configuration values for that map, which can
- themselves be maps again.
- </simpara>
- <simpara>
- Some map entries are optional. If they are, and
- currently have a value, the value can be unset by
- using either <command>config unset
- <replaceable><item name></replaceable>
- </command> or <command>config set
- <replaceable><item name></replaceable>
- null</command>.
-
- </simpara>
- <simpara>
- Maps <emphasis>can</emphasis> be modified as a whole,
- but using the full JSON representation of
- the entire map to set.
-
- Since this involves a lot of text, this is usually
- not recommended.
- </simpara>
- <simpara>
- Another example is the Logging virtual module, which
- is, like any module, a map, but it only contains one
- element: a list of loggers. Normally, an
- administrator would only modify that list (or its
- elements) directly, but it is possible to set the
- entire map in one command; for example:
- <command> config set Logging { "loggers": [] } </command>
- </simpara>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>list</term>
- <listitem>
- <simpara>
- A list is a compound list of other elements of the
- same type. Elements can be added with <command>config
- add <replaceable><list name> [value]</replaceable></command>, and removed with
- <command>config remove <replaceable><list name> [value]</replaceable></command> or
- <command>config remove <replaceable><list name></replaceable><replaceable><index></replaceable></command>.
- The index is of the form <emphasis>square bracket, number,
- square bracket</emphasis> (e.g.
- <command>[0]</command>), and it immediately follows
- the list name (there is no separator or space
- between them). List indices start with 0 for the
- first element.
- </simpara>
- <simpara>
- For addition, if the value is omitted, an entry with
- default values will be added. For removal, either
- the index or the full value (in JSON format) needs
- to be specified.
- </simpara>
- <simpara>
- Lists can also be used with
- <command>config set</command>,
- but like maps, only by specifying the
- entire list value in JSON format.
- </simpara>
- <simpara>
- For example, this command shows the renew-timer used for the second element of the list <varname>subnet4</varname> in the Dhcp4 module:
- <command>config show Dhcp4/subnet4[1]/renew-timer</command>
- </simpara>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>named set</term>
- <listitem>
- <simpara>
- Named sets are similar to lists, in that they are
- sets of elements of the same type, but they are not
- indexed by numbers, but by strings.
- </simpara>
- <simpara>
- Values can be added with
- <command>config add <replaceable><item name> <string> [value]</replaceable></command>
- where 'string' is the name of the element. If 'value'
- is ommitted, default values will be used. Elements
- can be removed with <command>config remove
- <replaceable><item
- name> <string></replaceable></command>
- </simpara>
- <simpara>
- Elements in a named set can be addressed similarly
- to maps.
- </simpara>
- <simpara>
- For example, the <command>Init/components</command>
- elements is a named set;
- adding, showing, and then removing an element
- can be done with the following three commands (note
- the '/'-character versus the space before
- 'example_module'):
- </simpara>
- <simpara>
- <command>config add Init/components example_module</command>
- </simpara>
- <simpara>
- <command>config show Init/components/example_module</command>
- </simpara>
- <simpara>
- <command>config remove Init/components example_module</command>
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>any</term>
- <listitem>
- <simpara>
- The 'any' type is a special type that can have any
- form. Apart from that, it must consist of elements as
- described in this chapter, there is no restriction
- on which element types are used. This type is used
- in places where different data formats could be
- used. Element modification commands depend on the
- actual type of the value. For instance, if the value
- of an 'any' element is a list, <command>config add
- </command> and <command>config remove</command> work
- as for other lists.
- </simpara>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
- </section>
-
- <section>
- <title>The execute command</title>
- The <command>execute</command> command executes a set of commands,
- either from a file
- or from a pre-defined set. Currently, there are no pre-defined sets
- available.
-
- <screen>> <userinput>execute file /tmp/example_commands</userinput></screen>
-
- The optional <command>show</command> argument may be used when
- executing a script from a file; for example:
-
- <screen>> <userinput>execute file /tmp/example_commands show</userinput></screen>
-
- <section id="bindctl_execute_directives">
- <title>Execute directives</title>
- Within sets of commands to be run with the <command>execute</command>
- command, a number of directives are supported:
- <variablelist>
- <varlistentry>
- <term>!echo <replaceable><string></replaceable></term>
- <listitem>
- <simpara>
- Prints the given string to <command>bindctl</command>'s
- output.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>!verbose on</term>
- <listitem>
- <simpara>
- Enables verbose mode; all following commands that are to
- be executed are also printed.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>!verbose off</term>
- <listitem>
- <simpara>
- Disables verbose mode; following commands that are to
- be executed are no longer printed.
- </simpara>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section id="bindctl_execute_notes">
- <title>Notes on execute scripts</title>
- Within scripts, you can add or remove modules with the normal
- configuration commands for <command>Init/components</command>.
- However, as module
- configuration and commands do not show up until the module is
- running, it is currently not possible to add a module and set
- its configuration in one script. This will be addressed in the
- future, but for now the only option is to add and configure
- modules in separate commands and execute scripts.
- </section>
- </section>
- </chapter>
-
- <chapter id="bind10.config">
- <title>bind10 Control and Configuration</title>
-
- <para>
- This chapter explains how to control and configure the
- <command>b10-init</command> parent.
- The startup of this resident process that runs the BIND 10
- daemons is covered in <xref linkend="bind10"/>.
- </para>
-
- <section id="bind10.shutdown">
- <title>Stopping bind10</title>
- <para>
- The BIND 10 suite may be shut down by stopping the
- parent <command>b10-init</command> process. This may be done
- by running the <userinput>Init shutdown</userinput> command
- at the <command>bindctl</command> prompt.
- </para>
- </section>
-
- <section id="kea.components">
- <title>Configuration to start processes</title>
-
- <para>
- The processes to be used can be configured for
- <command>b10-init</command> to start, with the exception
- of the required <command>b10-sockcreator</command>,
- <command>b10-msgq</command> and <command>b10-cfgmgr</command>
- components.
- The configuration is in the <varname>Init/components</varname>
- section. Each element represents one component, which is
- an abstraction of a process.
- </para>
-
- <para>
- To add a process to the set, let's say the DHCPv6 server (which
- is not started by default), you would do this:
- <screen>> <userinput>config add Init/components b10-dhcp6</userinput>
-> <userinput>config set Init/components/b10-dhcp6/kind needed</userinput>
-> <userinput>config set Init/components/b10-dhcp6/priority 10</userinput>
-> <userinput>config commit</userinput></screen></para>
-
- <para>
- Now, what it means. We add an entry called
- <quote>b10-dhcp6</quote>. It is both a name used to
- reference this component in the configuration and the name
- of the process to start. Then we set some parameters on
- how to start it.
- </para>
-
- <para>
- The <varname>special</varname> (not used in the example above), was introduced
- to be used for the components which require some kind of special care
- during startup. One such component is the b10-cmdctl, which is always started
- by default. No other components use this setting and it should be left unset
- for them.
- </para>
-
- <para>
- The <varname>kind</varname> specifies how a failure of the
- component should be handled. If it is set to
- <quote>dispensable</quote> (the default unless you set
- something else), it will get started again if it fails. If
- it is set to <quote>needed</quote> and it fails at startup,
- the whole <command>b10-init</command> shuts down and exits
- with an error exit code. But if it fails some time later, it
- is just started again. If you set it to <quote>core</quote>,
- you indicate that the system is not usable without the
- component and if such component fails, the system shuts
- down no matter when the failure happened. This is the
- behavior of the core components (the ones you can't turn
- off), but you can declare any other components as core as
- well if you wish (but you can turn these off, they just
- can't fail).
- </para>
-
- <para>
- The <varname>priority</varname> defines order in which the
- components should start. The ones with higher numbers are
- started sooner than the ones with lower ones. If you don't
- set it, 0 (zero) is used as the priority. Usually, leaving
- it at the default is enough.
- </para>
-
- <para>
- There are other parameters we didn't use in our example.
- One of them is <varname>address</varname>. It is the address
- used by the component on the <command>b10-msgq</command>
- message bus. The special components already know their
- address, but the usual ones don't. The address is by
- convention the thing after <emphasis>b10-</emphasis>, with
- the first letter capitalized (eg. <command>b10-stats</command>
- would have <quote>Stats</quote> as its address).
-<!-- TODO: this should be simplified so we don't even have to document it -->
- </para>
-
-<!-- TODO: what does "The special components already know their
-address, but the usual ones don't." mean? -->
-
-<!-- TODO: document params when is enabled -->
-
- <para>
- The last one is <varname>process</varname>. It is the name
- of the process to be started. It defaults to the name of
- the component if not set, but you can use this to override
- it. (The special components also already know their
- executable name.)
- </para>
-
- <!-- TODO Add parameters when they work, not implemented yet-->
-
- <note>
- <para>
- The configuration is quite powerful, but that includes
- a lot of space for mistakes. You could turn off the
- <command>b10-cmdctl</command>, but then you couldn't
- change it back the usual way, as it would require it to
- be running (you would have to find and edit the configuration
- directly).
- </para>
- <para>
- In short, you should think twice before disabling something here.
- </para>
- </note>
- <para>
- The running processes started by <command>b10-init</command>
- may be listed by running <userinput>Init show_processes</userinput>
- using <command>bindctl</command>.
- </para>
-
- </section>
- </chapter>
-
- <chapter id="dhcp">
- <title>DHCP</title>
- <para>The Dynamic Host Configuration Protocol for IPv4 (DHCP or
- DHCPv4) and Dynamic Host Configuration Protocol for IPv6 (DHCPv6)
- are protocols that allow one node (server) to provision
- configuration parameters to many hosts and devices (clients). To
- ease deployment in larger networks, additional nodes (relays) may
- be deployed that facilitate communication between servers and
- clients. Even though principles of both DHCPv4 and DHCPv6 are
- somewhat similar, these are two radically different
- protocols. Kea offers two server implementations, one for DHCPv4
- and one for DHCPv6. The DHCPv4 component is colloquially referred to
- as Kea4 and its DHCPv6 counterpart is called Kea6.</para>
- <para> In addition to providing lease management services, both Kea4 and
- Kea6 can provide dynamic DNS (DDNS) updates driven by the lease changes they
- make. These updates are carried out with the assistance of the
- DHCP-DDNS server, colloquially referred to as D2. When configured
- to do so, Kea servers will notify D2 of lease changes. D2 will match
- them to the appropriate DNS servers and instruct those severs to add or
- delete the requisite DNS entries.
- </para>
- <para>This chapter covers those parts of Kea that are common to
- both servers. DHCPv4-specific details are covered in <xref linkend="dhcp4"/>,
- while those details specific to DHCPv6 are described in <xref linkend="dhcp6"/>.
- The DHCP-DDNS server details are covered in <xref linkend="dhcp-ddns-server"/>
- </para>
-
-
<section id="dhcp-config-backend">
<title>Selecting configuration backend</title>
<para>Kea 0.9 introduces configuration backends that are switchable during
</chapter>
+ <chapter id="kea-config">
+ <title>Kea configuration</title>
+
+ <para>Depending on configuration backend chosen (see <xref
+ linkend="dhcp-config-backend"/>), configuration mechanisms are
+ different. The following sections describe details of specific configuration
+ backends. Note that only one configuration backend can be used and its
+ selection is determined during compilation time.</para>
+
+ <section id="bundy-backend">
+ <title>Bundy configuration backend</title>
+ <para>This legacy configuration backend allows Kea to use former BIND10
+ framework. That framework and this Kea configuration backend is no longer
+ supported by ISC. It is currently developed as part of Bundy project (see
+ <ulink url="http://bundy-dns.de">Bundy homepage</ulink>). See Bundy
+ project documentation regarding configuration.</para>
+ </section>
+
+ <section id="json-backend">
+ <title>JSON configuration backend</title>
+ <para>JSON is the default configuration backend and the only one supported
+ as of 0.9 release. It assumes that the servers are started from command
+ line (either directly or using a script, see TODO for details). JSON
+ backend uses certain signals to influence certain behaviors. The
+ configuration file is specified upon startup using -c parameter.</para>
+
+ <section id="json-format">
+ <title>JSON syntax</title>
+ <para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are
+ defined in extended JSON format. The basic JSON is defined in <ulink
+ url="http://tools.ietf.org/html/rfc4627">RFC 4627</ulink>. Kea
+ components use extended JSON, which extends basic format by allowing
+ bash-style comments in the file. Comment lines must have hash (#) in the
+ first column.</para>
+
+ <para>Configuration file consists of a single object (often colloquially
+ called a map) started with a curly bracket. It consists "Dhcp4",
+ "Dhcp6", "DhcpDdns" and/or "Logging" objects. It is possible to define
+ additional elements, but they will be ignored. That principle was chosen
+ to ease configuration management. For example, it is possible to define
+ Dhcp4, Dhcp6 and Logging elements in one configuration file that can be
+ used to start both DHCPv4 and DHCPv6 components. When starting, DHCPv4
+ component will use Dhcp4 object to configure itself and Logging to
+ configure logging parameters, while ignoring Dhcp6 object.</para>
+
+ <para>For example, a very simple configuration for Dhcp6 could look
+ like this:
+<screen>
+{
+
+# DHCPv6 specific configuration starts here.
+"Dhcp6": {
+
+# These are DHCPv6-specific parameters. They will be explained in later sections.
+ "interfaces": [ "eth0" ],
+
+ "preferred-lifetime": 3000,
+ "valid-lifetime": 4000,
+ "renew-timer": 1000,
+ "rebind-timer": 2000,
+
+# The following list defines subnets. Each subnet consists of at
+# least subnet and pool entries.
+ "subnet6": [{
+ "pool": [ "2001:db8:1::/80" ],
+ "subnet": "2001:db8:1::/64"
+ }]
+},
+# DHCPv6 specific configuration ends here.
+
+# Logger parameters (that could be shared among several components) start here.
+"Logging": {
+
+# These are Logger-specific parameters. They will be explained in later sections.
+ "loggers": [{
+ "name": "*",
+ "severity": "DEBUG"
+ }]
+}
+# Logger parameters end here.
+
+}
+</screen>
+ </para>
+
+ </section>
+
+
+ <!-- @todo Add a reference here after #3422 is done -->
+ </section>
+
+
+ </chapter>
+
+
<chapter id="dhcp4">
<title>The DHCPv4 Server</title>
projects / thirdparty / kea.git / commitdiff
