mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-22 01:49:48 +00:00
Code Issues Releases Wiki Activity

many improvements to docs based on sphinx

Browse Source 
- improved code-blocks
- improved json formatting: more compact, replaced // to # for comments
  to make them highlighted
- improved tables proportions
- fixed kea version: |release| should be used instead of KEAVERSION
- changed them to 'Read The Docs' to align with BIND
- cleaned up conf.py
- improved building in Makefile.am, now there are 3 targets (pdf, html, singlehtml)
  and 'all' that depends on those 3
- added kea.css to make html content wider and tables narrow to fit into
  text column
This commit is contained in:
Michal Nowikowski 2019-07-15 08:32:02 +02:00
parent a13c6ef7ca
commit b5b87d1849
20 changed files with 709 additions and 789 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
doc/guide/Makefile.am
View File

@ -33,18 +33,32 @@ rst_sources+=stats.rst
sphinxbuild = sphinx-build
sphinxopts = -E
kea-guide.pdf: $(rst_sources)
@$(sphinxbuild) -b latex $(srcdir) $(builddir)/_build $(sphinxopts)
sphinxopts=
sphinxopts+=-v
sphinxopts+=-E
sphinxopts+=-a
sphinxopts+=-c "${abs_srcdir}"
sphinxopts+=-D release="@PACKAGE_VERSION@"
sphinxopts+=-D version="@PACKAGE_VERSION@"
kea-guide.html: $(rst_sources)
@$(sphinxbuild) -b singlehtml $(srcdir) $(builddir)/_build $(sphinxopts)
sphinxbuilddir=$(builddir)/_build
pages: $(rst_sources)
@$(sphinxbuild) -b html $(srcdir) $(builddir)/_build2 $(sphinxopts)
all: pdf html singlehtml
pdf: $(rst_sources)
$(sphinxbuild) -M latexpdf $(srcdir) $(sphinxbuilddir) $(sphinxopts)
html singlehtml: $(rst_sources)
$(sphinxbuild) -M $@ $(srcdir) $(sphinxbuilddir) $(sphinxopts)
EXTRA_DIST = $(rst_sources)
# TODO: here should be added some stuff for DIST, etc to be consumed by automake/autoconf
clean::
-rm -rf $(sphinxbuilddir)
.PHONY: all pdf html singlehtml

12
doc/guide/_static/kea.css Normal file
View File

@ -0,0 +1,12 @@
/* give more screen width to the content as by default it is too narrow
and many tables and boxes are squeezed */
.wy-nav-content {
max-width: 1100px;
}
/* by default table content is not wrapped and then the tables
are pretty wide so removing that
*/
.wy-table-responsive table td, .wy-table-responsive table th {
white-space: normal;
}

46
doc/guide/admin.rst
View File

@ -179,7 +179,7 @@ To create the database:
1. Log into MySQL as "root":
::
.. code-block:: console
$ mysql -u root -p
Enter password:
@ -187,16 +187,16 @@ To create the database:
2. Create the MySQL database:
::
.. code-block:: mysql
mysql> CREATE DATABASE database-name;
mysql> CREATE DATABASE database_name;
(database-name is the name chosen for the database.)
(database_name is the name chosen for the database.)
3. Create the user under which Kea will access the database (and give it
a password), then grant it access to the database tables:
::
.. code-block:: mysql
mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password';
mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost';
@ -209,7 +209,7 @@ To create the database:
(Alternatively, the tables can be created by exiting MySQL and using the
``kea-admin`` tool, as explained below.) To do this:
::
.. code-block:: mysql
mysql> CONNECT database-name;
mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql
@ -218,7 +218,7 @@ To create the database:
5. Exit MySQL:
::
.. code-block:: mysql
mysql> quit
Bye
@ -227,7 +227,7 @@ To create the database:
If the tables were not created in Step 4, run the ``kea-admin`` tool
to create them now:
::
.. code-block:: console
$ kea-admin lease-init mysql -u database-user -p database-password -n database-name
@ -248,7 +248,7 @@ existing database will need to be upgraded. This can be done using the
To check the current version of the database, use the following command:
::
.. code-block:: console
$ kea-admin lease-version mysql -u database-user -p database-password -n database-name
@ -262,7 +262,7 @@ upgrade process does not discard any data, but depending on the nature
of the changes, it may be impossible to subsequently downgrade to an
earlier version. To perform an upgrade, issue the following command:
::
.. code-block:: console
$ kea-admin lease-upgrade mysql -u database-user -p database-password -n database-name
@ -285,7 +285,7 @@ which the servers will access it. A number of steps are required:
1. Log into PostgreSQL as "root":
::
.. code-block:: console
$ sudo -u postgres psql postgres
Enter password:
@ -293,7 +293,7 @@ which the servers will access it. A number of steps are required:
2. Create the database:
::
.. code-block:: psql
postgres=# CREATE DATABASE database-name;
CREATE DATABASE
@ -304,7 +304,7 @@ which the servers will access it. A number of steps are required:
3. Create the user under which Kea will access the database (and give it
a password), then grant it access to the database:
::
.. code-block:: psql
postgres=# CREATE USER user-name WITH PASSWORD 'password';
CREATE ROLE
@ -314,7 +314,7 @@ which the servers will access it. A number of steps are required:
4. Exit PostgreSQL:
::
.. code-block:: psql
postgres=# \q
Bye
@ -328,7 +328,7 @@ which the servers will access it. A number of steps are required:
completes, Kea will return to the shell prompt. The
output should be similar to the following:
::
.. code-block:: console
$ psql -d database-name -U user-name -f path-to-kea/share/kea/scripts/pgsql/dhcpdb_create.pgsql
Password for user user-name:
@ -388,7 +388,7 @@ Initialize the PostgreSQL Database Using kea-admin
If the tables were not created manually, do so now by
running the ``kea-admin`` tool:
::
.. code-block:: console
$ kea-admin lease-init pgsql -u database-user -p database-password -n database-name
@ -409,13 +409,13 @@ database backend type must be used in the commands.
Use the following command to check the current schema version:
::
.. code-block:: console
$ kea-admin lease-version pgsql -u database-user -p database-password -n database-name
Use the following command to perform an upgrade:
::
.. code-block:: console
$ kea-admin lease-upgrade pgsql -u database-user -p database-password -n database-name
@ -447,13 +447,13 @@ To create the database:
1. Export CQLSH_HOST environment variable:
::
.. code-block:: console
$ export CQLSH_HOST=localhost
2. Log into CQL:
::
.. code-block:: console
$ cqlsh
cql>
@ -479,7 +479,7 @@ To create the database:
If the tables were not created in Step 4, do so now by
running the ``kea-admin`` tool:
::
.. code-block:: console
$ kea-admin lease-init cql -n database-name
@ -500,7 +500,7 @@ existing database will need to be upgraded. This can be done using the
To check the current version of the database, use the following command:
::
.. code-block:: console
$ kea-admin lease-version cql -n database-name
@ -514,7 +514,7 @@ upgrade process does not discard any data, but depending on the nature
of the changes, it may be impossible to subsequently downgrade to an
earlier version. To perform an upgrade, issue the following command:
::
.. code-block:: console
$ kea-admin lease-upgrade cql -n database-name

2
doc/guide/agent.rst
View File

@ -259,7 +259,7 @@ Starting the Control Agent
The CA is started by running its binary and specifying the configuration
file it should use. For example:
::
.. code-block:: console
$ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf

46
doc/guide/conf.py
View File

@ -19,16 +19,10 @@
# -- Project information -----------------------------------------------------
project = 'Kea Administrator Reference Manual'
project = 'Kea'
copyright = '2019, Internet Systems Consortium'
author = 'Internet Systems Consortium'
# The short X.Y version
version = '1.6'
# The full version, including alpha/beta/rc tags
release = '1.6.0'
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
@ -75,7 +69,8 @@ pygments_style = None
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
#html_theme = 'alabaster'
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@ -146,39 +141,14 @@ man_pages = [
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'KeaAdministratorReferenceManual', 'Kea Administrator Reference Manual Documentation',
author, 'KeaAdministratorReferenceManual', 'One line description of project.',
'Miscellaneous'),
]
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''
# A unique identification for the text.
#
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
# -- Extension configuration -------------------------------------------------
# -- Options for todo extension ----------------------------------------------
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
# custom setup hook
def setup(app):
app.add_stylesheet('kea.css')

6
doc/guide/ctrl-channel.rst
View File

@ -183,14 +183,14 @@ common UNIX/Linux tools such as ``socat`` and ``curl``.
In order to control the given Kea service via a UNIX domain socket, use
``socat`` in interactive mode as follows:
::
.. code-block:: console
$ socat UNIX:/path/to/the/kea/socket -
or in batch mode, include the "ignoreeof" option as shown below to
ensure ``socat`` waits long enough for the server to respond:
::
.. code-block:: console
$ echo "{ some command...}" | socat UNIX:/path/to/the/kea/socket -,ignoreeof
@ -208,7 +208,7 @@ section.
To use Kea's RESTful API with ``curl``, use the following:
::
.. code-block:: console
$ curl -X POST -H "Content-Type: application/json" -d '{ "command": "config-get", "service": [ "dhcp4" ] }' http://ca.example.org:8000/

353
doc/guide/dhcp4-srv.rst
View File

@ -1707,91 +1707,90 @@ currently has no means to validate it.
.. table:: List of Standard DHCP Option Types
+-----------------------------------+-------------------------------------------------------+
| Name | Meaning |
+===================================+=======================================================+
| binary | An arbitrary string of bytes, |
| | specified as a set of hexadecimal |
| | digits. |
+-----------------------------------+-------------------------------------------------------+
| boolean | A boolean value with allowed |
| | values true or false. |
+-----------------------------------+-------------------------------------------------------+
| empty | No value; data is carried in |
| | sub-options. |
+-----------------------------------+-------------------------------------------------------+
| fqdn | Fully qualified domain name (e.g. |
| | www.example.com). |
+-----------------------------------+-------------------------------------------------------+
| ipv4-address | IPv4 address in the usual |
| | dotted-decimal notation (e.g. |
| | 192.0.2.1). |
+-----------------------------------+-------------------------------------------------------+
| ipv6-address | IPv6 address in the usual colon |
| | notation (e.g. 2001:db8::1). |
+-----------------------------------+-------------------------------------------------------+
| ipv6-prefix | IPv6 prefix and prefix length |
| | specified using CIDR notation, |
| | e.g. 2001:db8:1::/64. This data |
| | type is used to represent an |
| | 8-bit field conveying a prefix |
| | length and the variable length |
| | prefix value. |
+-----------------------------------+-------------------------------------------------------+
| psid | PSID and PSID length separated by |
| | a slash, e.g. 3/4 specifies |
| | PSID=3 and PSID length=4. In the |
| | wire format it is represented by |
| | an 8-bit field carrying PSID |
| | length (in this case equal to 4) |
| | and the 16-bits-long PSID value |
| | field (in this case equal to |
| | "0011000000000000b" using binary |
| | notation). Allowed values for a |
| | PSID length are 0 to 16. See `RFC |
| | 7597 <https://tools.ietf.org/html/rfc7597>`__ |
| | for details about the PSID wire |
| | representation. |
+-----------------------------------+-------------------------------------------------------+
| record | Structured data that may be |
| | comprised of any types (except |
| | "record" and "empty"). The array |
| | flag applies to the last field |
| | only. |
+-----------------------------------+-------------------------------------------------------+
| string | Any text. Please note that Kea |
| | will silently discard any |
| | terminating/trailing nulls from |
| | the end of 'string' options when |
| | unpacking received packets. This |
| | is in keeping with `RFC 2132, |
| | Section |
| | 2 <https://tools.ietf.org/html/rfc2132#section-2>`__. |
+-----------------------------------+-------------------------------------------------------+
| tuple | A length encoded as an 8- (16- |
| | for DHCPv6) bit unsigned integer |
| | followed by a string of this |
| | length. |
+-----------------------------------+-------------------------------------------------------+
| uint8 | 8-bit unsigned integer with |
| | allowed values 0 to 255. |
+-----------------------------------+-------------------------------------------------------+
| uint16 | 16-bit unsigned integer with |
| | allowed values 0 to 65535. |
+-----------------------------------+-------------------------------------------------------+
| uint32 | 32-bit unsigned integer with |
| | allowed values 0 to 4294967295. |
+-----------------------------------+-------------------------------------------------------+
| int8 | 8-bit signed integer with allowed |
| | values -128 to 127. |
+-----------------------------------+-------------------------------------------------------+
| int16 | 16-bit signed integer with |
| | allowed values -32768 to 32767. |
+-----------------------------------+-------------------------------------------------------+
| int32 | 32-bit signed integer with |
| | allowed values -2147483648 to |
| | 2147483647. |
+-----------------------------------+-------------------------------------------------------+
+-----------------+-------------------------------------------------------+
| Name | Meaning |
+=================+=======================================================+
| binary | An arbitrary string of bytes, specified as a set |
| | of hexadecimal digits. |
+-----------------+-------------------------------------------------------+
| boolean | A boolean value with allowed |
| | values true or false. |
+-----------------+-------------------------------------------------------+
| empty | No value; data is carried in |
| | sub-options. |
+-----------------+-------------------------------------------------------+
| fqdn | Fully qualified domain name (e.g. |
| | www.example.com). |
+-----------------+-------------------------------------------------------+
| ipv4-address | IPv4 address in the usual |
| | dotted-decimal notation (e.g. |
| | 192.0.2.1). |
+-----------------+-------------------------------------------------------+
| ipv6-address | IPv6 address in the usual colon |
| | notation (e.g. 2001:db8::1). |
+-----------------+-------------------------------------------------------+
| ipv6-prefix | IPv6 prefix and prefix length |
| | specified using CIDR notation, |
| | e.g. 2001:db8:1::/64. This data |
| | type is used to represent an |
| | 8-bit field conveying a prefix |
| | length and the variable length |
| | prefix value. |
+-----------------+-------------------------------------------------------+
| psid | PSID and PSID length separated by |
| | a slash, e.g. 3/4 specifies |
| | PSID=3 and PSID length=4. In the |
| | wire format it is represented by |
| | an 8-bit field carrying PSID |
| | length (in this case equal to 4) |
| | and the 16-bits-long PSID value |
| | field (in this case equal to |
| | "0011000000000000b" using binary |
| | notation). Allowed values for a |
| | PSID length are 0 to 16. See `RFC |
| | 7597 <https://tools.ietf.org/html/rfc7597>`__ |
| | for details about the PSID wire |
| | representation. |
+-----------------+-------------------------------------------------------+
| record | Structured data that may be |
| | comprised of any types (except |
| | "record" and "empty"). The array |
| | flag applies to the last field |
| | only. |
+-----------------+-------------------------------------------------------+
| string | Any text. Please note that Kea |
| | will silently discard any |
| | terminating/trailing nulls from |
| | the end of 'string' options when |
| | unpacking received packets. This |
| | is in keeping with `RFC 2132, |
| | Section |
| | 2 <https://tools.ietf.org/html/rfc2132#section-2>`__. |
+-----------------+-------------------------------------------------------+
| tuple | A length encoded as an 8- (16- |
| | for DHCPv6) bit unsigned integer |
| | followed by a string of this |
| | length. |
+-----------------+-------------------------------------------------------+
| uint8 | 8-bit unsigned integer with |
| | allowed values 0 to 255. |
+-----------------+-------------------------------------------------------+
| uint16 | 16-bit unsigned integer with |
| | allowed values 0 to 65535. |
+-----------------+-------------------------------------------------------+
| uint32 | 32-bit unsigned integer with |
| | allowed values 0 to 4294967295. |
+-----------------+-------------------------------------------------------+
| int8 | 8-bit signed integer with allowed |
| | values -128 to 127. |
+-----------------+-------------------------------------------------------+
| int16 | 16-bit signed integer with |
| | allowed values -32768 to 32767. |
+-----------------+-------------------------------------------------------+
| int32 | 32-bit signed integer with |
| | allowed values -2147483648 to |
| | 2147483647. |
+-----------------+-------------------------------------------------------+
.. _dhcp4-custom-options:
@ -2893,26 +2892,26 @@ table:
.. table:: Default FQDN Flag Behavior
+-----------------+-----------------+-----------------+-----------------+
| Client | Client Intent | Server Response | Server |
| Flags:N-S | | | Flags:N-S-O |
+=================+=================+=================+=================+
| 0-0 | Client wants to | Server | 1-0-0 |
| | do forward | generates | |
| | updates, server | reverse-only | |
| | should do | request | |
| | reverse updates | | |
+-----------------+-----------------+-----------------+-----------------+
| 0-1 | Server should | Server | 0-1-0 |
| | do both forward | generates | |
| | and reverse | request to | |
| | updates | update both | |
| | | directions | |
+-----------------+-----------------+-----------------+-----------------+
| 1-0 | Client wants no | Server does not | 1-0-0 |
| | updates done | generate a | |
| | | request | |
+-----------------+-----------------+-----------------+-----------------+
+------------+---------------------+-----------------+-------------+
| Client | Client Intent | Server Response | Server |
| Flags:N-S | | | Flags:N-S-O |
+============+=====================+=================+=============+
| 0-0 | Client wants to | Server | 1-0-0 |
| | do forward | generates | |
| | updates, server | reverse-only | |
| | should do | request | |
| | reverse updates | | |
+------------+---------------------+-----------------+-------------+
| 0-1 | Server should | Server | 0-1-0 |
| | do both forward | generates | |
| | and reverse | request to | |
| | updates | update both | |
| | | directions | |
+------------+---------------------+-----------------+-------------+
| 1-0 | Client wants no | Server does not | 1-0-0 |
| | updates done | generate a | |
| | | request | |
+------------+---------------------+-----------------+-------------+
The first row in the table above represents "client delegation." Here
the DHCP client states that it intends to do the forward DNS updates and
@ -4142,8 +4141,8 @@ following can be used:
::
"Dhcp4:" {
// This specifies global reservations. They will apply to all subnets that
// have global reservations enabled.
# This specifies global reservations. They will apply to all subnets that
# have global reservations enabled.
"reservations": [
{
@ -4154,9 +4153,9 @@ following can be used:
"hw-address": "01:02:03:04:05:06",
"hostname": "hw-host-fixed",
// Use of IP address in global reservation is risky. If used outside of
// a matching subnet, such as 192.0.1.0/24, it will result in a broken
// configuration being handed to the client.
# Use of IP address in global reservation is risky. If used outside of
# a matching subnet, such as 192.0.1.0/24, it will result in a broken
# configuration being handed to the client.
"ip-address": "192.0.1.77"
},
{
@ -4249,17 +4248,17 @@ introduced:
"Dhcp4": {
"shared-networks": [
{
// Name of the shared network. It may be an arbitrary string
// and it must be unique among all shared networks.
# Name of the shared network. It may be an arbitrary string
# and it must be unique among all shared networks.
"name": "my-secret-lair-level-1",
// The subnet selector can be specified at the shared network level.
// Subnets from this shared network will be selected for directly
// connected clients sending requests to server's "eth0" interface.
# The subnet selector can be specified at the shared network level.
# Subnets from this shared network will be selected for directly
# connected clients sending requests to server's "eth0" interface.
"interface": "eth0",
// This starts a list of subnets in this shared network.
// There are two subnets in this example.
# This starts a list of subnets in this shared network.
# There are two subnets in this example.
"subnet4": [
{
"subnet": "10.0.0.0/8",
@ -4270,13 +4269,13 @@ introduced:
"pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ]
}
],
} ], // end of shared-networks
} ], # end of shared-networks
// It is likely that in the network there will be a mix of regular,
// "plain" subnets and shared networks. It is perfectly valid to mix
// them in the same configuration file.
//
// This is a regular subnet. It is not part of any shared network.
# It is likely that in the network there will be a mix of regular,
# "plain" subnets and shared networks. It is perfectly valid to mix
# them in the same configuration file.
#
# This is a regular subnet. It is not part of any shared network.
"subnet4": [
{
"subnet": "192.0.3.0/24",
@ -4285,7 +4284,7 @@ introduced:
}
]
} // end of Dhcp4
} # end of Dhcp4
}
As demonstrated in the example, it is possible to mix shared and regular
@ -4315,12 +4314,12 @@ then override its value in the subnet scope. For example:
"interface": "eth0",
// This applies to all subnets in this shared network, unless
// values are overridden on subnet scope.
# This applies to all subnets in this shared network, unless
# values are overridden on subnet scope.
"valid-lifetime": 600,
// This option is made available to all subnets in this shared
// network.
# This option is made available to all subnets in this shared
# network.
"option-data": [ {
"name": "log-servers",
"data": "1.2.3.4"
@ -4331,7 +4330,7 @@ then override its value in the subnet scope. For example:
"subnet": "10.0.0.0/8",
"pools": [ { "pool": "10.0.0.1 - 10.0.0.99" } ],
// This particular subnet uses different values.
# This particular subnet uses different values.
"valid-lifetime": 1200,
"option-data": [
{
@ -4347,8 +4346,8 @@ then override its value in the subnet scope. For example:
"subnet": "192.0.2.0/24",
"pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ],
// This subnet does not specify its own valid-lifetime value,
// so it is inherited from shared network scope.
# This subnet does not specify its own valid-lifetime value,
# so it is inherited from shared network scope.
"option-data": [
{
"name": "routers",
@ -4389,8 +4388,8 @@ convenient to specify it once at the shared network level.
{
"name": "office-floor-2",
// This tells Kea that the whole shared network is reachable over a
// local interface. This applies to all subnets in this network.
# This tells Kea that the whole shared network is reachable over a
# local interface. This applies to all subnets in this network.
"interface": "eth0",
"subnet4": [
@ -4403,9 +4402,9 @@ convenient to specify it once at the shared network level.
"subnet": "192.0.2.0/24",
"pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ]
// Specifying a different interface name is a configuration
// error:
// "interface": "eth1"
# Specifying a different interface name is a configuration
# error:
# "interface": "eth1"
}
]
} ]
@ -5390,29 +5389,25 @@ of LED devices could be configured in the following way:
::
"Dhcp4": {
"subnet4": [
{
"subnet": "192.0.2.0/24",
"pools": [ {
"pool": "192.0.2.10 - 192.0.2.20",
// This is pool specific user context
"user-context": { "color": "red" }
} ],
"subnet4": [{
"subnet": "192.0.2.0/24",
"pools": [{
"pool": "192.0.2.10 - 192.0.2.20",
# This is pool specific user context
"user-context": { "color": "red" }
}],
// This is a subnet-specific user context. Any type
// of information can be entered here as long as it is valid JSON.
"user-context": {
"comment": "network on the second floor",
"last-modified": "2017-09-04 13:32",
"description": "you can put anything you like here",
"phones": [ "x1234", "x2345" ],
"devices-registered": 42,
"billing": false
}
},
...
],
...
# This is a subnet-specific user context. Any type
# of information can be entered here as long as it is valid JSON.
"user-context": {
"comment": "network on the second floor",
"last-modified": "2017-09-04 13:32",
"description": "you can put anything you like here",
"phones": [ "x1234", "x2345" ],
"devices-registered": 42,
"billing": false
}
}],
}
Kea does not interpret or use the user context information; it simply stores it and makes it
@ -5605,31 +5600,23 @@ Consider the following configuration snippet:
::
{
"Dhcp4": {
"config-control": {
"config-databases": [
{
"type": "mysql",
"name": "kea",
"user": "kea",
"password": "kea",
"host": "192.0.2.1",
"port": 3302
}
],
"config-fetch-wait-time": 20
},
"hooks-libraries": [
{
"library": "/usr/local/lib/kea/hooks/libdhcp_mysql_cb.so"
},
{
"library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so"
}
],
...
}
"Dhcp4": {
"config-control": {
"config-databases": [{
"type": "mysql",
"name": "kea",
"user": "kea",
"password": "kea",
"host": "192.0.2.1",
"port": 3302
}],
"config-fetch-wait-time": 20
},
"hooks-libraries": [{
"library": "/usr/local/lib/kea/hooks/libdhcp_mysql_cb.so"
}, {
"library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so"
}],
}
The ``config-control`` command contains two parameters. ``config-databases``

116
doc/guide/dhcp6-srv.rst
View File

@ -3635,8 +3635,9 @@ following can be used:
::
"Dhcp6:" {
// This specifies global reservations. They will apply to all subnets that
// have global reservations enabled.
# This specifies global reservations.
# They will apply to all subnets that
# have global reservations enabled.
"reservations": [
{
@ -3647,9 +3648,10 @@ following can be used:
"hw-address": "01:02:03:04:05:06",
"hostname": "hw-host-fixed",
// Use of IP address in global reservation is risky. If used outside of
// matching subnet, such as 3001::/64, it will result in a broken
// configuration being handed to the client.
# Use of IP address in global reservation is risky.
# If used outside of matching subnet, such as 3001::/64,
# it will result in a broken configuration being handed
# to the client.
"ip-address": "2001:db8:ff::77"
},
{
@ -3732,52 +3734,44 @@ introduced:
::
{
"Dhcp6": {
"shared-networks": [
{
// Name of the shared network. It may be an arbitrary string
// and it must be unique among all shared networks.
"name": "ipv6-lab-1",
"shared-networks": [{
# Name of the shared network. It may be an arbitrary string
# and it must be unique among all shared networks.
"name": "ipv6-lab-1",
// The subnet selector can be specified on the shared network level.
// Subnets from this shared network will be selected for clients
// communicating via relay agent having the specified IP address.
"relay": {
"ip-addresses": [ "2001:db8:2:34::1" ]
},
# The subnet selector can be specified on the shared network
# level. Subnets from this shared network will be selected
# for clients communicating via relay agent having
# the specified IP address.
"relay": {
"ip-addresses": [ "2001:db8:2:34::1" ]
},
// This starts a list of subnets in this shared network.
// There are two subnets in this example.
"subnet6": [
{
"subnet": "2001:db8::/48",
"pools": [ { "pool": "2001:db8::1 - 2001:db8::ffff" } ]
},
{
"subnet": "3ffe:ffe::/64",
"pools": [ { "pool": "3ffe:ffe::/64" } ]
}
]
} ], // end of shared-networks
# This starts a list of subnets in this shared network.
# There are two subnets in this example.
"subnet6": [{
"subnet": "2001:db8::/48",
"pools": [{ "pool": "2001:db8::1 - 2001:db8::ffff" }]
}, {
"subnet": "3ffe:ffe::/64",
"pools": [{ "pool": "3ffe:ffe::/64" }]
}]
}], # end of shared-networks
// It is likely that in the network there will be a mix of regular,
// "plain" subnets and shared networks. It is perfectly valid to mix
// them in the same configuration file.
//
// This is a regular subnet. It is not part of any shared-network.
"subnet6": [
{
"subnet": "2001:db9::/48",
"pools": [ { "pool": "2001:db9::/64" } ],
"relay": {
"ip-addresses": [ "2001:db8:1:2::1" ]
}
# It is likely that in the network there will be a mix of regular,
# "plain" subnets and shared networks. It is perfectly valid
# to mix them in the same configuration file.
#
# This is a regular subnet. It is not part of any shared-network.
"subnet6": [{
"subnet": "2001:db9::/48",
"pools": [{ "pool": "2001:db9::/64" }],
"relay": {
"ip-addresses": [ "2001:db8:1:2::1" ]
}
]
} // end of Dhcp6
}
}]
} # end of Dhcp6
As demonstrated in the example, it is possible to mix shared and regular
("plain") subnets. Each shared network must have a unique name. This is
@ -3807,12 +3801,12 @@ then override its value in the subnet scope. For example:
"ip-addresses": [ "2001:db8:2:34::1" ]
},
// This applies to all subnets in this shared network, unless
// values are overridden on subnet scope.
# This applies to all subnets in this shared network, unless
# values are overridden on subnet scope.
"valid-lifetime": 600,
// This option is made available to all subnets in this shared
// network.
# This option is made available to all subnets in this shared
# network.
"option-data": [ {
"name": "dns-servers",
"data": "2001:db8::8888"
@ -3823,7 +3817,7 @@ then override its value in the subnet scope. For example:
"subnet": "2001:db8:1::/48",
"pools": [ { "pool": "2001:db8:1::1 - 2001:db8:1::ffff" } ],
// This particular subnet uses different values.
# This particular subnet uses different values.
"valid-lifetime": 1200,
"option-data": [
{
@ -3839,8 +3833,8 @@ then override its value in the subnet scope. For example:
"subnet": "2001:db8:2::/48",
"pools": [ { "pool": "2001:db8:2::1 - 2001:db8:2::ffff" } ],
// This subnet does not specify its own valid-lifetime value,
// so it is inherited from shared network scope.
# This subnet does not specify its own valid-lifetime value,
# so it is inherited from shared network scope.
"option-data": [
{
"name": "dns-servers",
@ -3888,8 +3882,8 @@ convenient to specify it once at the shared network level.
{
"name": "office-floor-2",
// This tells Kea that the whole shared network is reachable over a
// local interface. This applies to all subnets in this network.
# This tells Kea that the whole shared network is reachable over a
# local interface. This applies to all subnets in this network.
"interface": "eth0",
"subnet6": [
@ -3902,9 +3896,9 @@ convenient to specify it once at the shared network level.
"subnet": "3ffe:abcd::/64",
"pools": [ { "pool": "3ffe:abcd::1 - 3ffe:abcd::ffff" } ]
// Specifying a different interface name is a configuration
// error:
// "interface": "eth1"
# Specifying a different interface name is a configuration
# error:
# "interface": "eth1"
}
],
} ]
@ -5410,7 +5404,7 @@ option is actually needed. An example configuration looks as follows:
"prefix-len": 56,
"delegated-len": 64,
// This is a pool specific context.
# This is a pool specific context.
"user-context": {
"threshold-percent": 85,
"v4-network": "192.168.0.0/16",
@ -5423,8 +5417,8 @@ option is actually needed. An example configuration looks as follows:
} ],
"subnet": "2001:db8::/32",
// This is a subnet-specific context. Any type of
// information can be entered here as long as it is valid JSON.
# This is a subnet-specific context. Any type of
# information can be entered here as long as it is valid JSON.
"user-context": {
"comment": "Those v4-v6 migration technologies are tricky.",
"experimental": true,

36
doc/guide/hammer.rst
View File

@ -21,9 +21,9 @@ please do so with care.
The first-time user is strongly encouraged to look at Hammer's built-in
help:
::
.. code-block:: console
./hammer.py --help
$ ./hammer.py --help
It will list available parameters.
@ -31,9 +31,9 @@ Hammer is able to set up various operating systems running either in LXC
or in VirtualBox. To list of supported systems, use the
``supported-systems`` command:
::
.. code-block:: console
$./hammer.py supported-systems
$ ./hammer.py supported-systems
fedora:
- 27: lxc, virtualbox
- 28: lxc, virtualbox
@ -61,9 +61,9 @@ First, you must install the Hammer dependencies: Vagrant
and either VirtualBox or LXC. To make life easier, Hammer can install
Vagrant and the required Vagrant plugins using the command:
::
.. code-block:: console
./hammer.py ensure-hammer-deps
$ ./hammer.py ensure-hammer-deps
VirtualBox and LXC need to be installed manually.
@ -71,9 +71,9 @@ The basic functions provided by Hammer are to prepare the build environment
and perform the actual build, and to run the unit tests locally in the current
system. This can be achieved by running the command:
::
.. code-block:: console
./hammer.py build -p local
$ ./hammer.py build -p local
The scope of the process can be defined using --with (-w) and --without
(-x) options. By default the build command will build Kea with
@ -81,9 +81,9 @@ documentation, install it locally, and run unit tests.
To exclude the installation and generation of docs, type:
::
.. code-block:: console
./hammer.py build -p local -x install docs
$ ./hammer.py build -p local -x install docs
The basic scope can be extended by: mysql, pgsql, cql, native-pkg,
radius, shell, and forge.
@ -96,16 +96,16 @@ radius, shell, and forge.
Hammer can be told to set up a new virtual machine with a specified
operating system, without the build:
::
.. code-block:: console
./hammer.py prepare-system -p virtualbox -s freebsd -r 12.0
$ ./hammer.py prepare-system -p virtualbox -s freebsd -r 12.0
This way we can prepare a system for our own use. To get to such a system
using SSH, invoke:
::
.. code-block:: console
./hammer.py ssh -p virtualbox -s freebsd -r 12.0
$ ./hammer.py ssh -p virtualbox -s freebsd -r 12.0
It is possible to speed up subsequent Hammer builds. To achieve this
Hammer employs `ccache <https://ccache.samba.org/>`__. During
@ -116,9 +116,9 @@ or LXC. To indicate the folder, you must indicate the --ccache-dir
parameter for Hammer. In the indicated folder, there are separate stored objects for each target
operating system.
::
.. code-block:: console
./hammer.py build -p lxc -s ubuntu -r 18.04 --ccache-dir ~/kea-ccache
$ ./hammer.py build -p lxc -s ubuntu -r 18.04 --ccache-dir ~/kea-ccache
..
@ -130,6 +130,6 @@ operating system.
For more information check:
::
.. code-block:: console
./hammer.py --help
$ ./hammer.py --help

351
doc/guide/hooks-ha.rst
View File

@ -341,80 +341,57 @@ with the only difference that ``this-server-name`` should be set to
::
{
"Dhcp4": {
...
"hooks-libraries": [
{
"library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so",
"parameters": { }
},
{
"library": "/usr/lib/kea/hooks/libdhcp_ha.so",
"parameters": {
"high-availability": [ {
"this-server-name": "server1",
"mode": "load-balancing",
"heartbeat-delay": 10000,
"max-response-delay": 10000,
"max-ack-delay": 5000,
"max-unacked-clients": 5,
"peers": [
{
"name": "server1",
"url": "http://192.168.56.33:8080/",
"role": "primary",
"auto-failover": true
},
{
"name": "server2",
"url": "http://192.168.56.66:8080/",
"role": "secondary",
"auto-failover": true
},
{
"name": "server3",
"url": "http://192.168.56.99:8080/",
"role": "backup",
"auto-failover": false
}
]
} ]
}
"hooks-libraries": [{
"library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so",
"parameters": { }
}, {
"library": "/usr/lib/kea/hooks/libdhcp_ha.so",
"parameters": {
"high-availability": [{
"this-server-name": "server1",
"mode": "load-balancing",
"heartbeat-delay": 10000,
"max-response-delay": 10000,
"max-ack-delay": 5000,
"max-unacked-clients": 5,
"peers": [{
"name": "server1",
"url": "http://192.168.56.33:8080/",
"role": "primary",
"auto-failover": true
}, {
"name": "server2",
"url": "http://192.168.56.66:8080/",
"role": "secondary",
"auto-failover": true
}, {
"name": "server3",
"url": "http://192.168.56.99:8080/",
"role": "backup",
"auto-failover": false
}]
}]
}
],
}],
"subnet4": [
{
"subnet": "192.0.3.0/24",
"pools": [
{
"pool": "192.0.3.100 - 192.0.3.150",
"client-class": "HA_server1"
},
{
"pool": "192.0.3.200 - 192.0.3.250",
"client-class": "HA_server2"
}
],
"subnet4": [{
"subnet": "192.0.3.0/24",
"pools": [{
"pool": "192.0.3.100 - 192.0.3.150",
"client-class": "HA_server1"
}, {
"pool": "192.0.3.200 - 192.0.3.250",
"client-class": "HA_server2"
}],
"option-data": [
{
"name": "routers",
"data": "192.0.3.1"
}
],
"relay": { "ip-address": "10.1.2.3" }
}
],
...
}
"option-data": [{
"name": "routers",
"data": "192.0.3.1"
}],
"relay": { "ip-address": "10.1.2.3" }
}]
}
Two hook libraries must be loaded to enable HA:
@ -566,90 +543,62 @@ HA hook library configuration has been removed from this example.
::
{
"Dhcp4": {
"client-classes": [{
"name": "phones",
"test": "substring(option[60].hex,0,6) == 'Aastra'",
}, {
"name": "laptops",
"test": "not member('phones')"
}, {
"name": "phones_server1",
"test": "member('phones') and member('HA_server1')"
}, {
"name": "phones_server2",
"test": "member('phones') and member('HA_server2')"
}, {
"name": "laptops_server1",
"test": "member('laptops') and member('HA_server1')"
}, {
"name": "laptops_server2",
"test": "member('laptops') and member('HA_server2')"
}],
"client-classes": [
{
"name": "phones",
"test": "substring(option[60].hex,0,6) == 'Aastra'",
},
{
"name": "laptops",
"test": "not member('phones')"
},
{
"name": "phones_server1",
"test": "member('phones') and member('HA_server1')"
},
{
"name": "phones_server2",
"test": "member('phones') and member('HA_server2')"
},
{
"name": "laptops_server1",
"test": "member('laptops') and member('HA_server1')"
},
{
"name": "laptops_server2",
"test": "member('laptops') and member('HA_server2')"
"hooks-libraries": [{
"library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so",
"parameters": { }
}, {
"library": "/usr/lib/kea/hooks/libdhcp_ha.so",
"parameters": {
"high-availability": [{
...
}]
}
],
}],
"hooks-libraries": [
{
"library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so",
"parameters": { }
},
{
"library": "/usr/lib/kea/hooks/libdhcp_ha.so",
"parameters": {
"high-availability": [ {
"subnet4": [{
"subnet": "192.0.3.0/24",
"pools": [{
"pool": "192.0.3.100 - 192.0.3.125",
"client-class": "phones_server1"
}, {
"pool": "192.0.3.126 - 192.0.3.150",
"client-class": "laptops_server1"
}, {
"pool": "192.0.3.200 - 192.0.3.225",
"client-class": "phones_server2"
}, {
"pool": "192.0.3.226 - 192.0.3.250",
"client-class": "laptops_server2"
}],
...
} ]
}
}
],
"subnet4": [
{
"subnet": "192.0.3.0/24",
"pools": [
{
"pool": "192.0.3.100 - 192.0.3.125",
"client-class": "phones_server1"
},
{
"pool": "192.0.3.126 - 192.0.3.150",
"client-class": "laptops_server1"
},
{
"pool": "192.0.3.200 - 192.0.3.225",
"client-class": "phones_server2"
},
{
"pool": "192.0.3.226 - 192.0.3.250",
"client-class": "laptops_server2"
}
],
"option-data": [
{
"name": "routers",
"data": "192.0.3.1"
}
],
"relay": { "ip-address": "10.1.2.3" }
}
],
...
}
"option-data": [{
"name": "routers",
"data": "192.0.3.1"
}],
"relay": { "ip-address": "10.1.2.3" }
}],
}
The configuration provided above splits the address range into four
@ -677,76 +626,54 @@ hot-standby configuration:
::
{
"Dhcp4": {
...
"hooks-libraries": [
{
"library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so",
"parameters": { }
},
{
"library": "/usr/lib/kea/hooks/libdhcp_ha.so",
"parameters": {
"high-availability": [ {
"this-server-name": "server1",
"mode": "hot-standby",
"heartbeat-delay": 10000,
"max-response-delay": 10000,
"max-ack-delay": 5000,
"max-unacked-clients": 5,
"peers": [
{
"name": "server1",
"url": "http://192.168.56.33:8080/",
"role": "primary",
"auto-failover": true
},
{
"name": "server2",
"url": "http://192.168.56.66:8080/",
"role": "standby",
"auto-failover": true
},
{
"name": "server3",
"url": "http://192.168.56.99:8080/",
"role": "backup",
"auto-failover": false
}
]
} ]
}
"hooks-libraries": [{
"library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so",
"parameters": { }
}, {
"library": "/usr/lib/kea/hooks/libdhcp_ha.so",
"parameters": {
"high-availability": [{
"this-server-name": "server1",
"mode": "hot-standby",
"heartbeat-delay": 10000,
"max-response-delay": 10000,
"max-ack-delay": 5000,
"max-unacked-clients": 5,
"peers": [{
"name": "server1",
"url": "http://192.168.56.33:8080/",
"role": "primary",
"auto-failover": true
}, {
"name": "server2",
"url": "http://192.168.56.66:8080/",
"role": "standby",
"auto-failover": true
}, {
"name": "server3",
"url": "http://192.168.56.99:8080/",
"role": "backup",
"auto-failover": false
}]
}]
}
],
}],
"subnet4": [
{
"subnet": "192.0.3.0/24",
"pools": [
{
"pool": "192.0.3.100 - 192.0.3.250",
"client-class": "HA_server1"
}
],
"subnet4": [{
"subnet": "192.0.3.0/24",
"pools": [{
"pool": "192.0.3.100 - 192.0.3.250",
"client-class": "HA_server1"
}],
"option-data": [
{
"name": "routers",
"data": "192.0.3.1"
}
],
"relay": { "ip-address": "10.1.2.3" }
}
],
...
}
"option-data": [{
"name": "routers",
"data": "192.0.3.1"
}],
"relay": { "ip-address": "10.1.2.3" }
}]
}
This configuration is very similar to the load-balancing configuration

4
doc/guide/hooks-host-cache.rst
View File

@ -31,14 +31,14 @@ any other hooks library; for example, this configuration could be used:
"Dhcp4": {
// Your regular DHCPv4 configuration parameters here.
# Your regular DHCPv4 configuration parameters here.
"hooks-libraries": [
{
"library": "/usr/local/lib/kea/hooks/libdhc_host_cache.so",
"parameters": {
// Tells Kea to never cache more than 1000 hosts.
# Tells Kea to never cache more than 1000 hosts.
"maximum": 1000
}

101
doc/guide/hooks-radius.rst
View File

@ -54,7 +54,7 @@ STEP 1: Install dependencies
Several tools are needed to build the dependencies and Kea itself. The
following commands should install them:
::
.. code-block:: console
$ sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
$ sudo yum install gcc-g++ openssl-devel log4cplus-devel wget git
@ -74,7 +74,7 @@ until those are processed, it is strongly recommended to use the
FreeRADIUS client with ISC's patches. To download and compile this
version, please use the following steps:
::
.. code-block:: console
$ git clone https://github.com/fxdupont/freeradius-client.git
$ cd freeradius-client/
@ -100,7 +100,7 @@ compiled using the g++ 4.8 version in CentOS.
To download and compile Boost 1.65, please use the following commands:
::
.. code-block:: console
$ wget -nd https://dl.bintray.com/boostorg/release/1.65.1/source/boost_1_65_1.tar.gz
$ tar zxvf boost_1_65_1.tar.gz
@ -116,30 +116,33 @@ compiled.
STEP 4: Compile and install Kea
Obtain the Kea sources either by downloading them from the git
repository or extracting the tarball:
repository or extracting the tarball. Use one of those commands
to obtain the Kea sources.
::
Choice 1: get from github
# Use one of those commands to obtain the Kea sources:
.. code-block:: console
# Choice 1: get from github
$ git clone https://github.com/isc-projects/kea
# Get a tarball and extract it
$ tar zxvf kea-KEAVERSION.tar.gz
Choice 2: get a tarball and extract it
.. code-block:: console
$ tar zxvf kea-|release|.tar.gz
The next step is to extract the premium Kea package that contains the
RADIUS repository into the Kea sources. After the tarball is extracted,
the Kea sources should have a premium/ subdirectory.
::
.. code-block:: console
$ cd kea
$ tar zxvf ../kea-premium-radius-KEAVERSION.tar.gz
$ tar zxvf ../kea-premium-radius-|release|.tar.gz
Once this is done, verify that the Kea sources look similar to this:
::
.. code-block:: console
$ ls -l
total 952
@ -168,7 +171,7 @@ is necessary to tell Kea where the FreeRADIUS client sources can be
found. Also, since the non-standard Boost is used, the path to it must
be specified.
::
.. code-block:: console
$ autoreconf -i
$ ./configure --with-freeradius=/path/to/freeradius --with-boost-include=/path/to/boost --with-boost-lib-dir=/path/to/boost/state/lib
@ -178,11 +181,11 @@ directory (/usr/local) and the Boost 1.65 sources were compiled in
/home/thomson/devel/boost1_65_1, the configure path should look as
follows:
::
.. code-block:: console
./configure --with-freeradius=/usr/local \
--with-boost-include=/home/thomson/devel/boost_1_65_1 \
--with-boost-lib-dir=/home/thomson/devel/boost_1_65_1/stage/lib
$ ./configure --with-freeradius=/usr/local \
--with-boost-include=/home/thomson/devel/boost_1_65_1 \
--with-boost-lib-dir=/home/thomson/devel/boost_1_65_1/stage/lib
After some checks, the configure script should print a report similar to
the following:
@ -195,8 +198,8 @@ the following:
Package:
Name: kea
Version: KEAVERSION
Extended version: KEAVERSION (tarball)
Version: |release|
Extended version: |release| (tarball)
OS Family: Linux
Hooks directory: /usr/local/lib/kea/hooks
@ -280,7 +283,7 @@ Once the configuration is complete, compile Kea using make. If the
system has more than one core, using the "-j N"
option is recommended to speed up the build.
::
.. code-block:: console
$ make -j5
$ sudo make install
@ -298,25 +301,25 @@ takes many parameters. For example, this configuration could be used:
"Dhcp4": {
// Your regular DHCPv4 configuration parameters here.
# Your regular DHCPv4 configuration parameters here.
"hooks-libraries": [
{
// Note that RADIUS requires host-cache for proper operation,
// so that library is loaded as well.
# Note that RADIUS requires host-cache for proper operation,
# so that library is loaded as well.
"library": "/usr/local/lib/kea/hooks/libdhcp_host_cache.so"
},
{
"library": "/usr/local/lib/kea/hooks/libdhc_radius.so",
"parameters": {
// Specify where FreeRADIUS dictionary could be located
# Specify where FreeRADIUS dictionary could be located
"dictionary": "/usr/local/etc/freeradius/dictionary",
// Specify which address to use to communicate with RADIUS servers
# Specify which address to use to communicate with RADIUS servers
"bindaddr": "*",
// more RADIUS parameters here
# more RADIUS parameters here
}
} ]
@ -459,61 +462,61 @@ following snippet could be used:
"parameters": {
// Other RADIUS parameters here
# Other RADIUS parameters here
"access": {
// This starts the list of access servers
# This starts the list of access servers
"servers": [
{
// These are parameters for the first (and only) access server
# These are parameters for the first (and only) access server
"name": "127.0.0.1",
"port": 1812,
"secret": "xyz123"
}
// Additional access servers could be specified here
# Additional access servers could be specified here
],
// This defines a list of additional attributes Kea will send to each
// access server in Access-Request.
# This defines a list of additional attributes Kea will send to each
# access server in Access-Request.
"attributes": [
{
// This attribute is identified by name (must be present in the
// dictionary) and has static value (i.e. the same value will be
// sent to every server for every packet)
# This attribute is identified by name (must be present in the
# dictionary) and has static value (i.e. the same value will be
# sent to every server for every packet)
"name": "Password",
"data": "mysecretpassword"
},
{
// It is also possible to specify an attribute using its type,
// rather than a name. 77 is Connect-Info. The value is specified
// using hex. Again, this is a static value. It will be sent the
// same for every packet and to every server.
# It is also possible to specify an attribute using its type,
# rather than a name. 77 is Connect-Info. The value is specified
# using hex. Again, this is a static value. It will be sent the
# same for every packet and to every server.
"type": 77,
"raw": "65666a6a71"
},
{
// This example shows how an expression can be used to send dynamic
// value. The expression (see Section 13) may take any value from
// the incoming packet or even its metadata (e.g. the interface
// it was received over from)
# This example shows how an expression can be used to send dynamic
# value. The expression (see Section 13) may take any value from
# the incoming packet or even its metadata (e.g. the interface
# it was received over from)
"name": "Configuration-Token",
"expr": "hexstring(pkt4.mac,':')"
}
] // End of attributes
} // End of access
] # End of attributes
} # End of access
// Accounting parameters.
# Accounting parameters.
"accounting": {
// This starts the list of accounting servers
# This starts the list of accounting servers
"servers": [
{
// These are parameters for the first (and only) accounting server
# These are parameters for the first (and only) accounting server
"name": "127.0.0.1",
"port": 1813,
"secret": "sekret"
}
// Additional accounting servers could be specified here
# Additional accounting servers could be specified here
]
}

151
doc/guide/hooks.rst
View File

@ -65,32 +65,32 @@ For our users' convenience, the premium hooks installation procedure is describe
1. Download the package; detailed instructions are provided separately on how
to get it. The package will be a file with a name similar to
kea-premium-KEAVERSION.tar.gz. (The name may vary depending on the package
kea-premium-|release|.tar.gz. (The name may vary depending on the package
purchased.)
2. Administrators who still have the sources for the corresponding version of the
open-source Kea package still on their system from the initial Kea installation
should skip this step. Otherwise, extract the Kea source from the original
tarball that was downloaded. For example, with a download of Kea KEAVERSION.,
there should be a tarball called kea-KEAVERSION.tar.gz on the system.
tarball that was downloaded. For example, with a download of Kea |release|.,
there should be a tarball called kea-|release|.tar.gz on the system.
Unpack this tarball:
::
$ tar zxvf kea-KEAVERSION.tar.gz
$ tar zxvf kea-|release|.tar.gz
This will unpack the tarball into the kea-KEAVERSION subdirectory of
This will unpack the tarball into the kea-|release| subdirectory of
the current working directory.
3. Unpack the Kea premium tarball into the directory into which Kea was
unpacked. Once Kea KEAVERSION has been unpacked into a kea-KEAVERSION
unpacked. Once Kea |release| has been unpacked into a kea-|release|
subdirectory and the Kea premium tarball is in the current directory, the following
steps will unpack the premium tarball into the correct location:
::
$ cd kea-KEAVERSION
$ tar xvf ../kea-premium-KEAVERSION.tar.gz
$ cd kea-|release|
$ tar xvf ../kea-premium-|release|.tar.gz
Note that unpacking the Kea premium package will put the files into a
directory named "premium". Regardless of the name of the package, the
@ -114,13 +114,13 @@ first section of the output should look something like this:
::
Package:
Name: kea
Version: KEAVERSION
Extended version:KEAVERSION (tarball)
OS Family: Linux
Using GNU sed: yes
Premium package: yes
Included Hooks: forensic_log flex_id host_cmds
Name: kea
Version: |release|
Extended version: |release| (tarball)
OS Family: Linux
Using GNU sed: yes
Premium package: yes
Included Hooks: forensic_log flex_id host_cmds
The last line indicates which specific hooks were detected. Note that
some hooks may require their own dedicated switches, e.g. the RADIUS hook
@ -285,50 +285,63 @@ loaded by the correct process per the table below.
.. table:: List of Available Hooks Libraries
+-----------------+-----------------+-----------------+-----------------+
| Name | Availability | Since | Load by process |
+=================+=================+=================+=================+
| user_chk | Kea sources | Kea 0.8 | kea-dhcp4, |
| | | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Forensic | Support | Kea 1.1.0 | kea-dhcp4, |
| Logging | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Flexible | Support | Kea 1.2.0 | kea-dhcp4, |
| Identifier | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Host Commands | Support | Kea 1.2.0 | kea-dhcp4, |
| | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Subnet Commands | Support | Kea 1.3.0 | kea-dhcp4, |
| | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Lease Commands | Kea sources | Kea 1.3.0 | kea-dhcp4, |
| | | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| High | Kea sources | Kea 1.4.0 | kea-dhcp4, |
| Availability | | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Statistics | Kea sources | Kea 1.4.0 | kea-dhcp4, |
| Commands | | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| RADIUS | Support | Kea 1.4.0 | kea-dhcp4, |
| | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Host Cache | Support | Kea 1.4.0 | kea-dhcp4, |
| | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Class Commands | Support | Kea 1.5.0 | kea-dhcp4, |
| | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| MySQL | Kea sources | Kea 1.6.0 | kea-dhcp4, |
| Configuration | | | kea-dhcp6 |
| Backend | | | |
+-----------------+-----------------+-----------------+-----------------+
| Configuration | Support | Kea 1.6.0 | kea-dhcp4, |
| Backend | customers | | kea-dhcp6 |
| Commands | | | |
+-----------------+-----------------+-----------------+-----------------+
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
| Name | Availability | Since | Load by process | Description |
+=================+=================+=================+=================+======================================================+
| user_chk | Kea sources | Kea 0.8 | kea-dhcp4, | Reads known users list from a file. Unknown users |
| | | | kea-dhcp6 | will be |
| | | | | assigned a lease |
| | | | | from the last subnet defined in the configuration |
| | | | | file, |
| | | | | e.g. to redirect |
| | | | | them a captive portal. This demonstrates how an |
| | | | | external |
| | | | | source of |
| | | | | information can be used to influence the Kea |
| | | | | allocation |
| | | | | engine. This hook |
| | | | | is part of the Kea source code and is available in |
| | | | | the |
| | | | | src/hooks/dhcp/user_chk directory. |
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
| Forensic | Support | Kea 1.1.0 | kea-dhcp4, | |
| Logging | customers | | kea-dhcp6 | |
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
| Flexible | Support | Kea 1.2.0 | kea-dhcp4, | |
| Identifier | customers | | kea-dhcp6 | |
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
| Host Commands | Support | Kea 1.2.0 | kea-dhcp4, | |
| | customers | | kea-dhcp6 | |
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
| Subnet Commands | Support | Kea 1.3.0 | kea-dhcp4, | |
| | customers | | kea-dhcp6 | |
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
| Lease Commands | Kea sources | Kea 1.3.0 | kea-dhcp4, | |
| | | | kea-dhcp6 | |
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
| High | Kea sources | Kea 1.4.0 | kea-dhcp4, | |
| Availability | | | kea-dhcp6 | |
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
| Statistics | Kea sources | Kea 1.4.0 | kea-dhcp4, | |
| Commands | | | kea-dhcp6 | |
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
| RADIUS | Support | Kea 1.4.0 | kea-dhcp4, | |
| | customers | | kea-dhcp6 | |
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
| Host Cache | Support | Kea 1.4.0 | kea-dhcp4, | |
| | customers | | kea-dhcp6 | |
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
| Class Commands | Support | Kea 1.5.0 | kea-dhcp4, | |
| | customers | | kea-dhcp6 | |
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
| MySQL | Kea sources | Kea 1.6.0 | kea-dhcp4, | |
| Configuration | | | kea-dhcp6 | |
| Backend | | | | |
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
| Configuration | Support | Kea 1.6.0 | kea-dhcp4, | |
| Backend | customers | | kea-dhcp6 | |
| Commands | | | | |
+-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+
ISC hopes to see more hooks libraries become available as time
progresses, developed both internally and externally. Since this list
@ -902,13 +915,13 @@ can be achieved by using the following configuration:
::
"Dhcp6": {
"subnet6": [{ ..., // subnet definition starts here
"subnet6": [{ ..., # subnet definition starts here
"reservations": [
"flex-id": "'port1234'", // value of the first 8 bytes of the interface-id
"flex-id": "'port1234'", # value of the first 8 bytes of the interface-id
"ip-addresses": [ "2001:db8::1" ]
],
}], // end of subnet definitions
"host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers
}], # end of subnet definitions
"host-reservation-identifiers": ["duid", "flex-id"], # add "flex-id" to reservation identifiers
"hooks-libraries": [
{
"library": "/path/libdhcp_flex_id.so",
@ -941,13 +954,13 @@ for non-printable characters and do not require the use of the
::
"Dhcp6": {
"subnet6": [{ ..., // subnet definition starts here
"subnet6": [{ ..., # subnet definition starts here
"reservations": [
"flex-id": "01:02:03:04:05:06", // value of the first 8 bytes of the interface-id
"flex-id": "01:02:03:04:05:06", # value of the first 8 bytes of the interface-id
"ip-addresses": [ "2001:db8::1" ]
],
}], // end of subnet definitions
"host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers
}], # end of subnet definitions
"host-reservation-identifiers": ["duid", "flex-id"], # add "flex-id" to reservation identifiers
"hooks-libraries": [
{
"library": "/path/libdhcp_flex_id.so",
@ -2246,12 +2259,12 @@ An example response could look as follows:
{
"subnet": "192.0.2.0/24",
"id": 5,
// many other subnet-specific details here
# many other subnet-specific details here
},
{
"id": 6,
"subnet": "192.0.3.0/31",
// many other subnet-specific details here
# many other subnet-specific details here
}
],
"valid-lifetime": 120

46
doc/guide/install.rst
View File

@ -152,7 +152,7 @@ development is done in the “master” branch.
The code can be checked out from
``https://gitlab.isc.org/isc-projects/kea.git``:
::
.. code-block:: console
$ git clone https://gitlab.isc.org/isc-projects/kea.git
@ -179,7 +179,7 @@ Configure Before the Build
Kea uses the GNU Build System to discover build environment details. To
generate the makefiles using the defaults, simply run:
::
.. code-block:: console
$ ./configure
@ -254,7 +254,7 @@ developers, or people who want to extend Kea code or send patches:
Internet anyway, please set the XSLTPROC_NET environment variable in
configure to any non-empty value, e.g.
::
.. code-block:: console
$ ./configure XSLTPROC_NET=yes --enable-generate-docs
@ -287,7 +287,7 @@ For example, the following command configures Kea to find the Boost
headers in /usr/pkg/include, specifies that PostgreSQL support should be
enabled, and sets the installation location to /opt/kea:
::
.. code-block:: console
$ ./configure \
--with-boost-include=/usr/pkg/include \
@ -298,7 +298,7 @@ If you have any problems with building Kea using the header-only Boost
code, or you'd like to use the Boost system library (assumed for the
sake of this example to be located in /usr/pkg/lib):
::
.. code-block:: console
$ ./configure \
--with-boost-libs=-lboost_system \
@ -316,7 +316,7 @@ Build
After the configure step is complete, build the executables from the C++
code and prepare the Python scripts by running the command:
::
.. code-block:: console
$ make
@ -326,7 +326,7 @@ Install
To install the Kea executables, support files, and documentation, issue
the command:
::
.. code-block:: console
$ make install
@ -342,7 +342,7 @@ If required, run ``ldconfig`` as root with ``/usr/local/lib`` (or with
prefix/lib if configured with --prefix) in ``/etc/ld.so.conf`` (or the
relevant linker cache configuration file for your OS):
::
.. code-block:: console
$ ldconfig
@ -355,8 +355,8 @@ relevant linker cache configuration file for your OS):
::
program: error while loading shared libraries: libkea-something.so.1:
cannot open shared object file: No such file or directory
program: error while loading shared libraries: libkea-something.so.1:
cannot open shared object file: No such file or directory
.. _dhcp-install-configure:
@ -393,17 +393,17 @@ with the following modification. To enable the MySQL database code, at
the "configure" step (see :ref:`configure`),
the --with-mysql switch should be specified:
::
.. code-block:: console
./configure [other-options] --with-mysql
$ ./configure [other-options] --with-mysql
If MySQL was not installed in the default location, the location of the
MySQL configuration program "mysql_config" should be included with the
switch, i.e.
::
.. code-block:: console
./configure [other-options] --with-mysql=path-to-mysql_config
$ ./configure [other-options] --with-mysql=path-to-mysql_config
See :ref:`mysql-database-create` for details regarding MySQL
database configuration.
@ -419,17 +419,17 @@ Build and install Kea as described in :ref:`installation`,
with the following modification. To enable the PostgreSQL database code,
at the "configure" step (see :ref:`configure`), the --with-pgsql switch should be specified:
::
.. code-block:: console
./configure [other-options] --with-pgsql
$ ./configure [other-options] --with-pgsql
If PostgreSQL was not installed in the default location, the location of
the PostgreSQL configuration program "pg_config" should be included with
the switch, i.e.
::
.. code-block:: console
./configure [other-options] --with-pgsql=path-to-pg_config
$ ./configure [other-options] --with-pgsql=path-to-pg_config
See :ref:`pgsql-database-create` for details regarding PostgreSQL
database configuration.
@ -446,9 +446,9 @@ simply install or build and install the package. Then build and install
Kea as described in :ref:`installation`. To enable the
Cassandra (CQL) database code, at the "configure" step (see :ref:`configure`), enter:
::
.. code-block:: console
./configure [other-options] --with-cql=path-to-pkg-config
$ ./configure [other-options] --with-cql=path-to-pkg-config
Note if ``pkg-config`` is at its standard location (and thus in the
shell path) you do not need to supply its path. If it does not work
@ -461,7 +461,7 @@ dependencies for building cpp-driver, see the project homepage
https://github.com/datastax/cpp-driver. In June 2016, the following
commands were used:
::
.. code-block:: console
$ git clone https://github.com/datastax/cpp-driver
$ cd cpp-driver
@ -486,9 +486,9 @@ Build and install Kea as described in :ref:`installation`,
with the following modification. To enable the Cassandra (CQL) database
code, at the "configure" step (see :ref:`configure`), enter:
::
.. code-block:: console
./configure [other-options] --with-cql=path-to-cql_config
$ ./configure [other-options] --with-cql=path-to-cql_config

4
doc/guide/intro.rst
View File

@ -8,14 +8,14 @@ Kea is the next generation of DHCP software developed by ISC. It
supports both DHCPv4 and DHCPv6 protocols along with their extensions,
e.g. prefix delegation and dynamic updates to DNS.
This guide covers Kea version KEAVERSION.
This guide covers Kea version |release|.
Supported Platforms
===================
Kea is officially supported on CentOS, Fedora, Ubuntu, Debian, and
FreeBSD systems. It is also likely to work on many other platforms.
Kea-KEAVERSION builds have been tested on:
Kea-|release| builds have been tested on:
- CentOS Linux — 7.1804 (aka 7.5)
- Fedora — 28, 29

6
doc/guide/kea-guide.rst
View File

@ -6,7 +6,7 @@ Kea is an open source implementation of the Dynamic Host Configuration
Protocol (DHCP) servers, developed and maintained by Internet Systems
Consortium (ISC).
This is the reference guide for Kea version &keaversion;.
This is the reference guide for Kea version |release|.
Links to the most up-to-date version of this document (in PDF, HTML,
and plain text formats), along with other documents for
Kea, can be found in ISC's `Knowledgebase <https://kb.isc.org/docs/kea-administrator-reference-manual>`_.
@ -47,11 +47,11 @@ Kea is an open source project designed, developed, and maintained by
Internet Systems Consortium, Inc, a 501(c)3 non-profit organization. ISC
is primarily funded by revenues from support subscriptions for our open
source, and we encourage all professional users to consider this option.
To learn more, see ​\ https://www.isc.org/support/.
To learn more, see \ https://www.isc.org/support/.
If you would like to contribute to ISC to assist us in continuing to
make quality open source software, please visit our donations page at
​\ https://www.isc.org/donate/.
\ https://www.isc.org/donate/.
We thank all the organizations and individuals who have helped to make
Kea possible. `Comcast <https://www.comcast.com/>`__ and the Comcast

24
doc/guide/keactrl.rst
View File

@ -22,9 +22,9 @@ Command Line Options
``keactrl`` is run as follows:
::
.. code-block:: console
keactrl <command> [-c keactrl-config-file] [-s server[,server,...]]
# keactrl <command> [-c keactrl-config-file] [-s server[,server,...]]
``<command>`` is one of the commands described in
`Commands <#keactrl-commands>`__.
@ -53,7 +53,7 @@ on a per-command basis using the ``-c`` switch.
The contents of ``keactrl.conf`` are:
::
.. code-block:: bash
# This is a configuration file for keactrl script which controls
# the startup, shutdown, reconfiguration and gathering the status
@ -155,7 +155,7 @@ The following commands are supported by ``keactrl``:
Typical output from ``keactrl`` when starting the servers looks similar
to the following:
::
.. code-block:: console
$ keactrl start
INFO/keactrl: Starting kea-dhcp4 -c /usr/local/etc/kea/kea-dhcp4.conf -d
@ -169,7 +169,7 @@ keactrl to determine whether a given server is running. If one or more
servers are running when the start command is issued, the output will
look similar to the following:
::
.. code-block:: console
$ keactrl start
INFO/keactrl: kea-dhcp4 appears to be running, see: PID 10918, PID file: /usr/local/var/kea/kea.kea-dhcp4.pid.
@ -188,7 +188,7 @@ must be manually deleted.
The following command stops all servers:
::
.. code-block:: console
$ keactrl stop
INFO/keactrl: Stopping kea-dhcp4...
@ -202,7 +202,7 @@ regardless of whether they are "enabled" in ``keactrl.conf``. If any
of the servers are not running, an informational message is displayed as
in the ``stop`` command output below.
::
.. code-block:: console
$ keactrl stop
INFO/keactrl: kea-dhcp4 isn't running.
@ -218,7 +218,7 @@ file and that are currently running. When a server receives the SIGHUP signal
it re-reads its configuration file and, if the new configuration is
valid, uses the new configuration. A reload is executed as follows:
::
.. code-block:: console
$ keactrl reload
INFO/keactrl: Reloading kea-dhcp4...
@ -232,7 +232,7 @@ version 1.5.0, kea-netconf does not support the SIGHUP signal. If its
configuration has changed, please stop and restart it for the change to
take effect. This limitation will be removed in a future release.
::
.. code-block:: console
$ keactrl stop
INFO/keactrl: kea-dhcp4 isn't running.
@ -262,7 +262,7 @@ take effect. This limitation will be removed in a future release.
Sometimes it is useful to check which servers are running. The
``status`` command reports this, with typical output that looks like:
::
.. code-block:: console
$ keactrl status
DHCPv4 server: active
@ -288,14 +288,14 @@ the ``keactrl`` command is issued. For example, the following instructs
``keactrl`` to stop the ``kea-dhcp4`` and ``kea-dhcp6`` servers and
leave the ``kea-dhcp-ddns`` and ``kea-ctrl-agent`` running:
::
.. code-block:: console
$ keactrl stop -s dhcp4,dhcp6
Similarly, the following will start only the ``kea-dhcp4`` and
``kea-dhcp-ddns`` servers, but not ``kea-dhcp6`` or ``kea-ctrl-agent``.
::
.. code-block:: console
$ keactrl start -s dhcp4,dhcp_ddns

128
doc/guide/netconf.rst
View File

@ -69,7 +69,7 @@ named in Kea models (a short version of schema models).
To list the currently installed YANG modules:
::
.. code-block:: console
$ sysrepoctl -l
@ -105,12 +105,12 @@ after installation.
To install modules from sources, do the following:
::
.. code-block:: console
cd src/share/yang/modules
sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g ietf-dhcpv6-server*.yang
sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g kea-dhcp4-server*.yang
sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g kea-dhcp6-server*.yang
$ cd src/share/yang/modules
$ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g ietf-dhcpv6-server*.yang
$ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g kea-dhcp4-server*.yang
$ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g kea-dhcp6-server*.yang
...
Note that the first -s parameter specifies the location of the YANG
@ -120,7 +120,7 @@ by the Kea configuration under the SYSREPO_REPO name.
The installation should look similar to the following:
::
.. code-block:: console
$ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g ietf-dhcpv6-server*.yang
Installing a new module from file 'ietf-dhcpv6-server@2018-11-20.yang'...
@ -148,7 +148,7 @@ The installation should look similar to the following:
It is possible to confirm whether the models are imported correctly by using
sysrepoctl -l:
::
.. code-block:: console
$ sysrepoctl -l
Sysrepo schema directory: /home/thomson/devel/sysrepo-0.7.6/build/repository/yang/
@ -175,7 +175,7 @@ sysrepoctl -l:
To install a new revision of a module it must first be uninstalled, e.g.
by:
::
.. code-block:: console
sudo sysrepoctl -u -m kea-dhcp4-server
@ -384,31 +384,31 @@ Kea sources.
::
// This is a simple example of a configuration for the NETCONF agent.
// This server provides a YANG interface for all Kea servers and the agent.
# This is a simple example of a configuration for the NETCONF agent.
# This server provides a YANG interface for all Kea servers and the agent.
{
"Netconf":
{
// Control flags can be defined in the global scope or
// in a managed server scope. Precedences are:
// - use the default value (true)
// - use the global value
// - use the local value.
// So this overwrites the default value:
# Control flags can be defined in the global scope or
# in a managed server scope. Precedences are:
# - use the default value (true)
# - use the global value
# - use the local value.
# So this overwrites the default value:
"boot-update": false,
// This map specifies how each server is managed. For each server there
// is a name of the YANG model to be used and the control channel.
# This map specifies how each server is managed. For each server there
# is a name of the YANG model to be used and the control channel.
//
// Currently three control channel types are supported:
// "stdout" which outputs the configuration on the standard output,
// "unix" which uses the local control channel supported by the
// "dhcp4" and "dhcp6" servers ("d2" support is not yet available),
// and "http" which uses the Control Agent "ca" to manage itself or
// to forward commands to "dhcp4" or "dhcp6".
# Currently three control channel types are supported:
# "stdout" which outputs the configuration on the standard output,
# "unix" which uses the local control channel supported by the
# "dhcp4" and "dhcp6" servers ("d2" support is not yet available),
# and "http" which uses the Control Agent "ca" to manage itself or
# to forward commands to "dhcp4" or "dhcp6".
"managed-servers":
{
// This is how kea-netconf can communicate with the DHCPv4 server.
# This is how kea-netconf can communicate with the DHCPv4 server.
"dhcp4":
{
"comment": "DHCP4 server",
@ -420,7 +420,7 @@ Kea sources.
}
},
// DHCPv6 parameters.
# DHCPv6 parameters.
"dhcp6":
{
"model": "kea-dhcp6-server",
@ -431,8 +431,8 @@ Kea sources.
}
},
// Currently the DHCP-DDNS (nicknamed D2) server does not support
// a command channel.
# Currently the DHCP-DDNS (nicknamed D2) server does not support
# a command channel.
"d2":
{
"model": "kea-dhcp-ddns",
@ -443,7 +443,7 @@ Kea sources.
}
},
// Of course the Control Agent (CA) supports HTTP.
# Of course the Control Agent (CA) supports HTTP.
"ca":
{
"model": "kea-ctrl-agent",
@ -455,39 +455,39 @@ Kea sources.
}
},
// kea-netconf is able to load hooks libraries that augment its operation.
// Currently there are no hook points defined in kea-netconf
// processing.
# kea-netconf is able to load hooks libraries that augment its operation.
# Currently there are no hook points defined in kea-netconf
# processing.
"hooks-libraries": [
// The hooks libraries list may contain more than one library.
# The hooks libraries list may contain more than one library.
{
// The only necessary parameter is the library filename.
# The only necessary parameter is the library filename.
"library": "/opt/local/netconf-commands.so",
// Some libraries may support parameters. Make sure you
// type this section carefully, as kea-netconf does not
// validate it (because the format is library-specific).
# Some libraries may support parameters. Make sure you
# type this section carefully, as kea-netconf does not
# validate it (because the format is library-specific).
"parameters": {
"param1": "foo"
}
}
],
// Similar to other Kea components, NETCONF also uses logging.
# Similar to other Kea components, NETCONF also uses logging.
"loggers": [
{
"name": "kea-netconf",
"output_options": [
{
"output": "/var/log/kea-netconf.log",
// Several additional parameters are possible in
// addition to the typical output.
// Flush determines whether logger flushes output
// to a file.
// Maxsize determines maximum filesize before
// the file is being rotated.
// Maxver specifies the maximum number of
// rotated files being kept.
# Several additional parameters are possible in
# addition to the typical output.
# Flush determines whether logger flushes output
# to a file.
# Maxsize determines maximum filesize before
# the file is being rotated.
# Maxver specifies the maximum number of
# rotated files being kept.
"flush": true,
"maxsize": 204800,
"maxver": 4
@ -553,7 +553,7 @@ The test box has an Ethernet interface named eth1. On some systems it is
possible to rename interfaces, for instance on a Linux with an ens38
interface:
::
.. code-block:: console
# ip link set down dev ens38
# ip link set name eth1 dev ens38
@ -561,7 +561,7 @@ interface:
The interface must have an address in the test prefix:
::
.. code-block:: console
# ip -6 addr add 2001:db8::1/64 dev eth1
@ -586,14 +586,14 @@ DHCPv6 server:
In order to launch the Kea DHCPv6 server using the configuration
contained within the ``boot.json`` file, run:
::
.. code-block:: console
# kea-dhcp6 -d -c boot.json
The current configuration of the server can be fetched via control
socket by running:
::
.. code-block:: console
# echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea6-sock '-,ignoreeof'
@ -638,7 +638,7 @@ Note that in production there should not be a need to log at the DEBUG level.
The Kea NETCONF agent is launched by:
::
.. code-block:: console
# kea-netconf -d -c netconf.json
@ -646,7 +646,7 @@ Now that both ``kea-netconf`` and ``kea-dhcp6`` are running, it is
possible to populate updates to the configuration to the DHCPv6 server.
The following is the configuration extracted from ``startup.xml``:
::
.. code-block:: xml
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6>
@ -669,7 +669,7 @@ The following is the configuration extracted from ``startup.xml``:
To populate this new configuration:
::
.. code-block:: console
# sysrepocfg -d startup -f xml -i startup.xml kea-dhcp6-server
@ -704,7 +704,7 @@ NETCONF:
In the first case, consider the following ``BAD-schema.xml``
configuration file:
::
.. code-block:: xml
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet4>
@ -727,14 +727,14 @@ configuration file:
It is directly rejected by ``sysrepocfg``:
::
.. code-block:: console
# sysrepocfg -d running -f xml -i BAD-schema.xml kea-dhcp6-server
In the second case, the configuration is rejected by ``kea-netconf``.
For example, consider this ``BAD-translator.xml`` file:
::
.. code-block:: xml
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6>
@ -759,7 +759,7 @@ For example, consider this ``BAD-translator.xml`` file:
In the third case, the configuration is presented to the Kea DHCPv6
server and fails to validate as in this ``BAD-config.xml`` file:
::
.. code-block:: xml
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6>
@ -793,7 +793,7 @@ NETCONF Operation Example with Two Pools
This example adds a second pool to the initial (i.e. startup)
configuration in the ``twopools.xml`` file:
::
.. code-block:: xml
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6>
@ -821,7 +821,7 @@ configuration in the ``twopools.xml`` file:
This configuration is installed by:
::
.. code-block:: console
# sysrepocfg -d running -f xml -i twopools.xml kea-dhcp6-server
@ -832,7 +832,7 @@ NETCONF Operation Example with Two Subnets
This example specifies two subnets in the ``twosubnets.xml`` file:
::
.. code-block:: xml
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6>
@ -864,7 +864,7 @@ This example specifies two subnets in the ``twosubnets.xml`` file:
This configuration is installed by:
::
.. code-block:: console
# sysrepocfg -d running -f xml -i twosubnets.xml kea-dhcp6-server
@ -876,7 +876,7 @@ NETCONF Operation Example with Logging
This example adds a logger entry to the initial (i.e. startup)
configuration in the ``logging.xml`` file:
::
.. code-block:: xml
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<interfaces-config>
@ -947,7 +947,7 @@ The corresponding Kea configuration in JSON is:
Finally, any of the previous examples can be replayed using
``sysrepocfg`` in edit mode as follows:
::
.. code-block:: console
# sysrepocfg -d running -f xml -e vi kea-dhcp6-server

28
doc/guide/quickstart.rst
View File

@ -22,27 +22,27 @@ Quick Start Guide for DHCPv4 and DHCPv6 Services
3. Extract the tarball. For example:
::
.. code-block:: console
$ tar xvzf kea-KEAVERSION.tar.gz
$ tar xvzf kea-|release|.tar.gz
4. Go into the source directory and run the configure script:
::
.. code-block:: console
$ cd kea-KEAVERSION
$ cd kea-|release|
$ ./configure [your extra parameters]
5. Build it:
::
.. code-block:: console
$ make
6. Install it (by default it will be placed in ``/usr/local/``, so it
is likely that you will need root privileges for this step):
::
.. code-block:: console
# make install
@ -55,25 +55,25 @@ Quick Start Guide for DHCPv4 and DHCPv6 Services
8. In order to start the DHCPv4 server in the background, run the
following command (as root):
::
.. code-block:: console
# keactrl start -s dhcp4
Or run the following command to start the DHCPv6 server instead:
::
.. code-block:: console
# keactrl start -s dhcp6
Note that it is also possible to start all servers simultaneously:
::
.. code-block:: console
$ keactrl start
# keactrl start
9. Verify that the Kea server(s) is/are running:
::
.. code-block:: console
# keactrl status
@ -92,7 +92,7 @@ Quick Start Guide for DHCPv4 and DHCPv6 Services
11. Stop running the server(s):
::
.. code-block:: console
# keactrl stop
@ -112,12 +112,12 @@ Running the Kea Servers Directly
The Kea servers can be started directly, without the need to use
``keactrl``. To start the DHCPv4 server run the following command:
::
.. code-block:: console
# kea-dhcp4 -c /path/to/your/kea4/config/file.json
Similarly, to start the DHCPv6 server run the following command:
::
.. code-block:: console
# kea-dhcp6 -c /path/to/your/kea6/config/file.json

10
doc/guide/shell.rst
View File

@ -27,9 +27,9 @@ Shell Usage
``kea-shell`` is run as follows:
::
.. code-block:: console
kea-shell [--host hostname] [--port number] [--path path] [--timeout seconds] [--service service-name] [command]
$ kea-shell [--host hostname] [--port number] [--path path] [--timeout seconds] [--service service-name] [command]
where:
@ -71,7 +71,7 @@ all supported commands from the CA, use the ``list-commands`` command.
The following shows a simple example of usage:
::
.. code-block:: console
$ kea-shell --host 192.0.2.1 --port 8001 --service dhcp4 list-commands
^D
@ -89,7 +89,7 @@ the command "config-write" to the CA (the ``--service`` parameter has not
been used), along with the parameters specified in param.json. The
result will be stored in result.json.
::
.. code-block:: console
$ cat param.json
"filename": "my-config-file.json"
@ -100,7 +100,7 @@ servers, the default empty path in the URL is not enough, so the
``--path`` parameter should be used. For instance, if requests to the
"/kea" path are forwarded to the CA this can be used:
::
.. code-block:: console
$ kea-shell --host 192.0.2.1 --port 8001 --path kea ...