From: Tomek Mrugalski Date: Tue, 10 Jun 2014 17:45:38 +0000 (+0200) Subject: [3418] Several chapters related to BIND10 framework removed, JSON config added X-Git-Tag: trac3473_base~12^2~19 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=312d49e9ba896df7f8883fc8b11ecb7c08392c4d;p=thirdparty%2Fkea.git [3418] Several chapters related to BIND10 framework removed, JSON config added --- diff --git a/doc/guide/kea-guide.xml b/doc/guide/kea-guide.xml index 6fb6acc4e7..fece401e3e 100644 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@ -796,1079 +796,6 @@ as a dependency earlier --> - - - - Starting Kea with <command>bind10</command> - - Kea is started with the bind10 command. - It runs the b10-init daemon which - starts up the required processes, and - will also restart some processes that exit unexpectedly. - bind10 is the only command needed to start Kea. - - - - After starting the b10-msgq communications channel, - b10-init connects to it, - runs the configuration manager, and reads its own configuration. - Then it starts the other modules. - - - - The b10-sockcreator, b10-msgq and - b10-cfgmgr - services make up the core. The b10-msgq daemon - provides the communication channel between every part of the system. - The b10-cfgmgr 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 b10-sockcreator daemon - can allocate Internet addresses and ports needed by network services - but is currently unused by DHCP servers. - - - - In its default configuration, the b10-init - master process will also start up - b10-cmdctl for administration tools to - communicate with the system, and - b10-stats for statistics collection. - The DHCP servers are not started by default. - The configuration of components to start is covered in - . - - -
- Starting Kea - - To start the BIND 10 service, simply run bind10 - 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 switch to - get additional debugging or diagnostic output. - - - - - - - - - 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 python. - This is not needed on some operating systems. - - - -
- - - - - Command channel - - - The BIND 10 components use the b10-msgq - message routing daemon to communicate with Kea components. - The b10-msgq implements what is called the - Command Channel. - 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. - - - - Administrators do not communicate directly with the - b10-msgq daemon. - By default, BIND 10 uses a UNIX domain socket file named - /usr/local/var/bind10/msg_socket - for this interprocess communication. - - - - - - Configuration manager - - - The configuration manager, b10-cfgmgr, - handles all system configuration. It provides - persistent storage for configuration, and notifies running - modules of configuration changes. - - - - The b10-dhcp6, b10-dhcp4 and - b10-dhcp-ddns daemons receive their configurations - from the configuration manager over the b10-msgq - command channel. - - - The administrator doesn't connect to it directly, but - uses a user interface to communicate with the configuration - manager via b10-cmdctl's REST-ful interface. - b10-cmdctl is covered in . - - - - - - 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. - - - - - The b10-cfgmgr daemon can send all - specifications and all current settings to the - bindctl client (via - b10-cmdctl). - b10-cfgmgr relays configurations received - from b10-cmdctl to the appropriate modules. - - - - - - - - - - The stored configuration file is at - /usr/local/var/bind10/b10-config.db. - (The directory is what was defined at build configure time for - . - The default is /usr/local/var/.) - 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. - - - - - - The configuration manager does not have any command line arguments. - Normally it is not started manually, but is automatically - started using the b10-init master process - (as covered in ). - - - - - - - - - - - Remote control daemon - - - b10-cmdctl 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. - - - - - When b10-cmdctl starts, it firsts - asks b10-cfgmgr about what modules are - running and what their configuration is (over the - b10-msgq channel). Then it will start listening - on HTTPS for clients — the user interface — such - as bindctl. - - - - b10-cmdctl directly sends commands - (received from the user interface) to the specified component. - Configuration changes are actually commands to - b10-cfgmgr so are sent there. - - - - - - - The HTTPS server requires a private key, - such as a RSA PRIVATE KEY. - The default location is at - /usr/local/etc/bind10/cmdctl-keyfile.pem. - (A sample key is at - /usr/local/share/bind10/cmdctl-keyfile.pem.) - It also uses a certificate located at - /usr/local/etc/bind10/cmdctl-certfile.pem. - (A sample certificate is at - /usr/local/share/bind10/cmdctl-certfile.pem.) - This may be a self-signed certificate or purchased from a - certification authority. - - - - The HTTPS server doesn't support a certificate request from a - client (at this time). - - The b10-cmdctl 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. - - - - - - - - - - - - The b10-cmdctl daemon also requires - the user account file located at - /usr/local/etc/bind10/cmdctl-accounts.csv. - This comma-delimited file lists the accounts with a user name, - hashed password, and salt. - - - - The administrator may create a user account with the - b10-cmdctl-usermgr tool. - - - - - - - By default the HTTPS server listens on the localhost port 8080. - The port can be set by using the command line option. - The address to listen on can be set using the command - line argument. - Each HTTPS connection is stateless and times out in 1200 seconds - by default. This can be - redefined by using the command line argument. - - -
- Configuration specification for b10-cmdctl - - The configuration items for b10-cmdctl are: - accounts_file which defines the path to the - user accounts database (the default is - /usr/local/etc/bind10/cmdctl-accounts.csv); - cert_file which defines the path to the - PEM certificate file (the default is - /usr/local/etc/bind10/cmdctl-certfile.pem); - and - key_file which defines the path to the - PEM private key file (the default is - /usr/local/etc/bind10/cmdctl-keyfile.pem). - - -
- - - - - - - Control and configure user interface - - - bindctl 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. - - - - The bindctl 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 b10-cmdctl. It doesn't - communicate to any other components directly. - - -
- bindctl command-line options - - - -a <address>, --address=<address> - - - IP address that BIND 10's b10-cmdctl - module is listening on. By default, this is 127.0.0.1. - - - - - -c <certificate file>, --certificate-chain=<certificate file> - - - PEM-formatted server certificate file. When this option is - given, bindctl will verify the server - certificate using the given file as the root of the - certificate chain. If not specified, bindctl - does not validate the certificate. - - - - - --csv-file-dir=<csv file> - - - bindctl stores the username and - password for logging in in a file called - default_user.csv; - this option specifies the directory where this file is - stored and read from. When not specified, - ~/.bind10/ is used. - Currently, this file contains an unencrypted password. - - - - - -h, --help - - - Shows a short overview of the command-line options of - bindctl, and exits. - - - - - --version - - - Shows the version of bindctl, and exits. - - - - - -p <port number>, --port=<port number> - - - Port number that BIND 10's b10-cmdctl - module is listening on. By default, this is port 8080. - - - - -
- -
- General syntax of bindctl commands - The bindctl 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 - - <module> <command> [argument(s)] - - For example, the Init module has a 'shutdown' command to shut down - BIND 10, with an optional argument 'help': - - > Init shutdown help -Command shutdown (Shut down BIND 10 and Kea) - help (Get help for command) -This command has no parameters - - There are no mandatory arguments, only the optional 'help'. -
- -
- Bindctl help - help 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. - > help -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: -(list of modules) - - - When 'help' is used as a command to a module, it shows the supported commands for the module; for example: - > Init help -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 - - - And when added to a module command, it shows the description and parameters of that specific command; for example: - > DhcpDdns shutdown help -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 - - -
- -
- Command arguments - - Commands can have arguments, which can be either optional or - mandatory. They can be specified by name - (e.g. <command> <argument name>=<argument value>), or positionally, - (e.g. <command> <argument value 1> <argument value 2>). - - - <command> help - 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. - - - For example, the shutdown 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: - > DhcpDdns shutdown now - But since the class is optional (defaulting to normal), leaving it out - works as well: - > DhcpDdns shutdown - - - The arguments can also be provided with their names: - > DhcpDdns shutdown type="now" - -
- -
- Module commands - Each module has its own set of commands (if any), which will only be - available if the module is running. -
- -
- Configuration commands - 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 tsig_keys and - data_sources). - - Configuration changes (set, unset, add and remove) are done locally - first, and have no immediate effect. The changes can be viewed with - config diff, and either reverted - (config revert), or committed - (config commit). - 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 - Module/example/item - Sub-elements of names, lists and sets (see ) are separated with the '/' - character, and list indices are identified with [<index>]; for example: - - Module/example/list[2]/foo - -
- List of configuration commands - The following configuration commands are available: - - - show [all] [item name] - - - Shows the current configuration of the given item. If 'all' - is given, it will recurse through the entire set, and show - every nested value. - - - - - show_json [item name] - - - Shows the full configuration of the given item in JSON format. - - - - - add <item name> [value] - - - Add an entry to configuration list or a named set (see ). - 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. - - - - - remove - - - 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). - - - - - set <item name> <value> - - - Directly set the value of the given item to the given value. - - - - - unset <item name> - - - Remove any user-specified value for the given item. - - - - - diff - - - Show all current local changes that have not been - committed yet. - - - - - revert - - - Revert all local changes without committing them. - - - - - commit - - - Send all local changes to the configuration manager, which - will validate them, and apply them if validation succeeds. - - - - - go - - - Go to a specific configuration part, similar to the 'cd' - command in a shell. - There are a number of problems with the current - implementation of go within bindctl, - and we recommend not using it for general cases. - - - - -
- -
- Configuration data types - 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. - - - integer - - - A basic integer; can be set directly with - config set, to any integer - value. The value must not be quoted, or else, it - will be parsed as a string. - - - - - real - - - A basic floating point number; can be set - directly with config set, to - any floating point value. The value must not be - quoted, or else, it will be parsed as a string. - - - - - boolean - - - A basic boolean value; can be set directly with - config set, to either - true or - false. The value must not be - quoted, or else, it will be parsed as a - string. Integer values are not allowed. - - - - - string - - - A basic string value; can be set directly with - config set to any - string. Double quotation marks are optional. - - - - - null - - - This is a special type representing 'no value at all'; usable in compound structures that have optional elements that are not set. - - - - - - maps - - - 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. - - - Some map entries are optional. If they are, and - currently have a value, the value can be unset by - using either config unset - <item name> - or config set - <item name> - null. - - - - Maps can 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. - - - 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: - config set Logging { "loggers": [] } - - - - - - list - - - A list is a compound list of other elements of the - same type. Elements can be added with config - add <list name> [value], and removed with - config remove <list name> [value] or - config remove <list name><index>. - The index is of the form square bracket, number, - square bracket (e.g. - [0]), and it immediately follows - the list name (there is no separator or space - between them). List indices start with 0 for the - first element. - - - 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. - - - Lists can also be used with - config set, - but like maps, only by specifying the - entire list value in JSON format. - - - For example, this command shows the renew-timer used for the second element of the list subnet4 in the Dhcp4 module: - config show Dhcp4/subnet4[1]/renew-timer - - - - - - named set - - - 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. - - - Values can be added with - config add <item name> <string> [value] - where 'string' is the name of the element. If 'value' - is ommitted, default values will be used. Elements - can be removed with config remove - <item - name> <string> - - - Elements in a named set can be addressed similarly - to maps. - - - For example, the Init/components - 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'): - - - config add Init/components example_module - - - config show Init/components/example_module - - - config remove Init/components example_module - - - - - any - - - 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, config add - and config remove work - as for other lists. - - - - -
-
- -
- The execute command - The execute command executes a set of commands, - either from a file - or from a pre-defined set. Currently, there are no pre-defined sets - available. - - > execute file /tmp/example_commands - - The optional show argument may be used when - executing a script from a file; for example: - - > execute file /tmp/example_commands show - -
- Execute directives - Within sets of commands to be run with the execute - command, a number of directives are supported: - - - !echo <string> - - - Prints the given string to bindctl's - output. - - - - - !verbose on - - - Enables verbose mode; all following commands that are to - be executed are also printed. - - - - - !verbose off - - - Disables verbose mode; following commands that are to - be executed are no longer printed. - - - - -
- -
- Notes on execute scripts - Within scripts, you can add or remove modules with the normal - configuration commands for Init/components. - 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. -
-
- - - - bind10 Control and Configuration - - - This chapter explains how to control and configure the - b10-init parent. - The startup of this resident process that runs the BIND 10 - daemons is covered in . - - -
- Stopping bind10 - - The BIND 10 suite may be shut down by stopping the - parent b10-init process. This may be done - by running the Init shutdown command - at the bindctl prompt. - -
- -
- Configuration to start processes - - - The processes to be used can be configured for - b10-init to start, with the exception - of the required b10-sockcreator, - b10-msgq and b10-cfgmgr - components. - The configuration is in the Init/components - section. Each element represents one component, which is - an abstraction of a process. - - - - To add a process to the set, let's say the DHCPv6 server (which - is not started by default), you would do this: - > config add Init/components b10-dhcp6 -> config set Init/components/b10-dhcp6/kind needed -> config set Init/components/b10-dhcp6/priority 10 -> config commit - - - Now, what it means. We add an entry called - b10-dhcp6. 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. - - - - The special (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. - - - - The kind specifies how a failure of the - component should be handled. If it is set to - dispensable (the default unless you set - something else), it will get started again if it fails. If - it is set to needed and it fails at startup, - the whole b10-init 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 core, - 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). - - - - The priority 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. - - - - There are other parameters we didn't use in our example. - One of them is address. It is the address - used by the component on the b10-msgq - message bus. The special components already know their - address, but the usual ones don't. The address is by - convention the thing after b10-, with - the first letter capitalized (eg. b10-stats - would have Stats as its address). - - - - - - - - - The last one is process. 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.) - - - - - - - The configuration is quite powerful, but that includes - a lot of space for mistakes. You could turn off the - b10-cmdctl, 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). - - - In short, you should think twice before disabling something here. - - - - The running processes started by b10-init - may be listed by running Init show_processes - using bindctl. - - -
- - - - DHCP - 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. - 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. - - This chapter covers those parts of Kea that are common to - both servers. DHCPv4-specific details are covered in , - while those details specific to DHCPv6 are described in . - The DHCP-DDNS server details are covered in - - -
Selecting configuration backend Kea 0.9 introduces configuration backends that are switchable during @@ -2088,6 +1015,101 @@ host database-name user-name + + Kea configuration + + Depending on configuration backend chosen (see ), 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. + +
+ Bundy configuration backend + 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 + Bundy homepage). See Bundy + project documentation regarding configuration. +
+ +
+ JSON configuration backend + 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. + +
+ JSON syntax + Configuration files for DHCPv4, DHCPv6 and DDNS modules are + defined in extended JSON format. The basic JSON is defined in RFC 4627. 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. + + 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. + + For example, a very simple configuration for Dhcp6 could look + like this: + +{ + +# 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. + +} + + + +
+ + + +
+ + + + + The DHCPv4 Server