mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-29 04:57:52 +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 sphinxbuild = sphinx-build
sphinxopts = -E
kea-guide.pdf: $(rst_sources) sphinxopts=
@$(sphinxbuild) -b latex $(srcdir) $(builddir)/_build $(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) sphinxbuilddir=$(builddir)/_build
@$(sphinxbuild) -b singlehtml $(srcdir) $(builddir)/_build $(sphinxopts)
pages: $(rst_sources) all: pdf html singlehtml
@$(sphinxbuild) -b html $(srcdir) $(builddir)/_build2 $(sphinxopts)
pdf: $(rst_sources)
$(sphinxbuild) -M latexpdf $(srcdir) $(sphinxbuilddir) $(sphinxopts)
html singlehtml: $(rst_sources)
$(sphinxbuild) -M $@ $(srcdir) $(sphinxbuilddir) $(sphinxopts)
EXTRA_DIST = $(rst_sources) EXTRA_DIST = $(rst_sources)
# TODO: here should be added some stuff for DIST, etc to be consumed by automake/autoconf # 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": 1. Log into MySQL as "root":
:: .. code-block:: console
$ mysql -u root -p $ mysql -u root -p
Enter password: Enter password:
@ -187,16 +187,16 @@ To create the database:
2. Create the MySQL 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 3. Create the user under which Kea will access the database (and give it
a password), then grant it access to the database tables: a password), then grant it access to the database tables:
:: .. code-block:: mysql
mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password'; mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password';
mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost'; 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 (Alternatively, the tables can be created by exiting MySQL and using the
``kea-admin`` tool, as explained below.) To do this: ``kea-admin`` tool, as explained below.) To do this:
:: .. code-block:: mysql
mysql> CONNECT database-name; mysql> CONNECT database-name;
mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql
@ -218,7 +218,7 @@ To create the database:
5. Exit MySQL: 5. Exit MySQL:
:: .. code-block:: mysql
mysql> quit mysql> quit
Bye Bye
@ -227,7 +227,7 @@ To create the database:
If the tables were not created in Step 4, run the ``kea-admin`` tool If the tables were not created in Step 4, run the ``kea-admin`` tool
to create them now: to create them now:
:: .. code-block:: console
$ kea-admin lease-init mysql -u database-user -p database-password -n database-name $ 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: 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 $ 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 of the changes, it may be impossible to subsequently downgrade to an
earlier version. To perform an upgrade, issue the following command: 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 $ 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": 1. Log into PostgreSQL as "root":
:: .. code-block:: console
$ sudo -u postgres psql postgres $ sudo -u postgres psql postgres
Enter password: Enter password:
@ -293,7 +293,7 @@ which the servers will access it. A number of steps are required:
2. Create the database: 2. Create the database:
:: .. code-block:: psql
postgres=# CREATE DATABASE database-name; postgres=# CREATE DATABASE database-name;
CREATE DATABASE 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 3. Create the user under which Kea will access the database (and give it
a password), then grant it access to the database: a password), then grant it access to the database:
:: .. code-block:: psql
postgres=# CREATE USER user-name WITH PASSWORD 'password'; postgres=# CREATE USER user-name WITH PASSWORD 'password';
CREATE ROLE CREATE ROLE
@ -314,7 +314,7 @@ which the servers will access it. A number of steps are required:
4. Exit PostgreSQL: 4. Exit PostgreSQL:
:: .. code-block:: psql
postgres=# \q postgres=# \q
Bye 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 completes, Kea will return to the shell prompt. The
output should be similar to the following: 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 $ psql -d database-name -U user-name -f path-to-kea/share/kea/scripts/pgsql/dhcpdb_create.pgsql
Password for user user-name: 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 If the tables were not created manually, do so now by
running the ``kea-admin`` tool: running the ``kea-admin`` tool:
:: .. code-block:: console
$ kea-admin lease-init pgsql -u database-user -p database-password -n database-name $ 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: 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 $ kea-admin lease-version pgsql -u database-user -p database-password -n database-name
Use the following command to perform an upgrade: 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 $ 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: 1. Export CQLSH_HOST environment variable:
:: .. code-block:: console
$ export CQLSH_HOST=localhost $ export CQLSH_HOST=localhost
2. Log into CQL: 2. Log into CQL:
:: .. code-block:: console
$ cqlsh $ cqlsh
cql> cql>
@ -479,7 +479,7 @@ To create the database:
If the tables were not created in Step 4, do so now by If the tables were not created in Step 4, do so now by
running the ``kea-admin`` tool: running the ``kea-admin`` tool:
:: .. code-block:: console
$ kea-admin lease-init cql -n database-name $ 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: To check the current version of the database, use the following command:
:: .. code-block:: console
$ kea-admin lease-version cql -n database-name $ 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 of the changes, it may be impossible to subsequently downgrade to an
earlier version. To perform an upgrade, issue the following command: earlier version. To perform an upgrade, issue the following command:
:: .. code-block:: console
$ kea-admin lease-upgrade cql -n database-name $ 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 The CA is started by running its binary and specifying the configuration
file it should use. For example: file it should use. For example:
:: .. code-block:: console
$ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf $ ./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 information -----------------------------------------------------
project = 'Kea Administrator Reference Manual' project = 'Kea'
copyright = '2019, Internet Systems Consortium' copyright = '2019, Internet Systems Consortium'
author = '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 --------------------------------------------------- # -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here. # 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 # The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes. # 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 # 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 # 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 ------------------------------------------------- # -- Extension configuration -------------------------------------------------
# -- Options for todo extension ---------------------------------------------- # -- Options for todo extension ----------------------------------------------
# If true, `todo` and `todoList` produce output, else they produce nothing. # If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True 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 In order to control the given Kea service via a UNIX domain socket, use
``socat`` in interactive mode as follows: ``socat`` in interactive mode as follows:
:: .. code-block:: console
$ socat UNIX:/path/to/the/kea/socket - $ socat UNIX:/path/to/the/kea/socket -
or in batch mode, include the "ignoreeof" option as shown below to or in batch mode, include the "ignoreeof" option as shown below to
ensure ``socat`` waits long enough for the server to respond: ensure ``socat`` waits long enough for the server to respond:
:: .. code-block:: console
$ echo "{ some command...}" | socat UNIX:/path/to/the/kea/socket -,ignoreeof $ 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: 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/ $ curl -X POST -H "Content-Type: application/json" -d '{ "command": "config-get", "service": [ "dhcp4" ] }' http://ca.example.org:8000/

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

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

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

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

34
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 The first-time user is strongly encouraged to look at Hammer's built-in
help: help:
:: .. code-block:: console
./hammer.py --help $ ./hammer.py --help
It will list available parameters. It will list available parameters.
@ -31,7 +31,7 @@ Hammer is able to set up various operating systems running either in LXC
or in VirtualBox. To list of supported systems, use the or in VirtualBox. To list of supported systems, use the
``supported-systems`` command: ``supported-systems`` command:
:: .. code-block:: console
$ ./hammer.py supported-systems $ ./hammer.py supported-systems
fedora: fedora:
@ -61,9 +61,9 @@ First, you must install the Hammer dependencies: Vagrant
and either VirtualBox or LXC. To make life easier, Hammer can install and either VirtualBox or LXC. To make life easier, Hammer can install
Vagrant and the required Vagrant plugins using the command: 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. 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 and perform the actual build, and to run the unit tests locally in the current
system. This can be achieved by running the command: 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 The scope of the process can be defined using --with (-w) and --without
(-x) options. By default the build command will build Kea with (-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: 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, The basic scope can be extended by: mysql, pgsql, cql, native-pkg,
radius, shell, and forge. 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 Hammer can be told to set up a new virtual machine with a specified
operating system, without the build: 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 This way we can prepare a system for our own use. To get to such a system
using SSH, invoke: 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 It is possible to speed up subsequent Hammer builds. To achieve this
Hammer employs `ccache <https://ccache.samba.org/>`__. During 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 parameter for Hammer. In the indicated folder, there are separate stored objects for each target
operating system. 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: For more information check:
:: .. code-block:: console
./hammer.py --help $ ./hammer.py --help

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

@ -341,17 +341,11 @@ with the only difference that ``this-server-name`` should be set to
:: ::
{
"Dhcp4": { "Dhcp4": {
"hooks-libraries": [{
...
"hooks-libraries": [
{
"library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so", "library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so",
"parameters": { } "parameters": { }
}, }, {
{
"library": "/usr/lib/kea/hooks/libdhcp_ha.so", "library": "/usr/lib/kea/hooks/libdhcp_ha.so",
"parameters": { "parameters": {
"high-availability": [{ "high-availability": [{
@ -361,60 +355,43 @@ with the only difference that ``this-server-name`` should be set to
"max-response-delay": 10000, "max-response-delay": 10000,
"max-ack-delay": 5000, "max-ack-delay": 5000,
"max-unacked-clients": 5, "max-unacked-clients": 5,
"peers": [ "peers": [{
{
"name": "server1", "name": "server1",
"url": "http://192.168.56.33:8080/", "url": "http://192.168.56.33:8080/",
"role": "primary", "role": "primary",
"auto-failover": true "auto-failover": true
}, }, {
{
"name": "server2", "name": "server2",
"url": "http://192.168.56.66:8080/", "url": "http://192.168.56.66:8080/",
"role": "secondary", "role": "secondary",
"auto-failover": true "auto-failover": true
}, }, {
{
"name": "server3", "name": "server3",
"url": "http://192.168.56.99:8080/", "url": "http://192.168.56.99:8080/",
"role": "backup", "role": "backup",
"auto-failover": false "auto-failover": false
} }]
]
}] }]
} }
} }],
],
"subnet4": [ "subnet4": [{
{
"subnet": "192.0.3.0/24", "subnet": "192.0.3.0/24",
"pools": [ "pools": [{
{
"pool": "192.0.3.100 - 192.0.3.150", "pool": "192.0.3.100 - 192.0.3.150",
"client-class": "HA_server1" "client-class": "HA_server1"
}, }, {
{
"pool": "192.0.3.200 - 192.0.3.250", "pool": "192.0.3.200 - 192.0.3.250",
"client-class": "HA_server2" "client-class": "HA_server2"
} }],
],
"option-data": [ "option-data": [{
{
"name": "routers", "name": "routers",
"data": "192.0.3.1" "data": "192.0.3.1"
} }],
],
"relay": { "ip-address": "10.1.2.3" } "relay": { "ip-address": "10.1.2.3" }
} }]
],
...
}
} }
Two hook libraries must be loaded to enable HA: Two hook libraries must be loaded to enable HA:
@ -566,90 +543,62 @@ HA hook library configuration has been removed from this example.
:: ::
{
"Dhcp4": { "Dhcp4": {
"client-classes": [{
"client-classes": [
{
"name": "phones", "name": "phones",
"test": "substring(option[60].hex,0,6) == 'Aastra'", "test": "substring(option[60].hex,0,6) == 'Aastra'",
}, }, {
{
"name": "laptops", "name": "laptops",
"test": "not member('phones')" "test": "not member('phones')"
}, }, {
{
"name": "phones_server1", "name": "phones_server1",
"test": "member('phones') and member('HA_server1')" "test": "member('phones') and member('HA_server1')"
}, }, {
{
"name": "phones_server2", "name": "phones_server2",
"test": "member('phones') and member('HA_server2')" "test": "member('phones') and member('HA_server2')"
}, }, {
{
"name": "laptops_server1", "name": "laptops_server1",
"test": "member('laptops') and member('HA_server1')" "test": "member('laptops') and member('HA_server1')"
}, }, {
{
"name": "laptops_server2", "name": "laptops_server2",
"test": "member('laptops') and member('HA_server2')" "test": "member('laptops') and member('HA_server2')"
} }],
],
"hooks-libraries": [ "hooks-libraries": [{
{
"library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so", "library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so",
"parameters": { } "parameters": { }
}, }, {
{
"library": "/usr/lib/kea/hooks/libdhcp_ha.so", "library": "/usr/lib/kea/hooks/libdhcp_ha.so",
"parameters": { "parameters": {
"high-availability": [{ "high-availability": [{
... ...
}] }]
} }
} }],
],
"subnet4": [ "subnet4": [{
{
"subnet": "192.0.3.0/24", "subnet": "192.0.3.0/24",
"pools": [ "pools": [{
{
"pool": "192.0.3.100 - 192.0.3.125", "pool": "192.0.3.100 - 192.0.3.125",
"client-class": "phones_server1" "client-class": "phones_server1"
}, }, {
{
"pool": "192.0.3.126 - 192.0.3.150", "pool": "192.0.3.126 - 192.0.3.150",
"client-class": "laptops_server1" "client-class": "laptops_server1"
}, }, {
{
"pool": "192.0.3.200 - 192.0.3.225", "pool": "192.0.3.200 - 192.0.3.225",
"client-class": "phones_server2" "client-class": "phones_server2"
}, }, {
{
"pool": "192.0.3.226 - 192.0.3.250", "pool": "192.0.3.226 - 192.0.3.250",
"client-class": "laptops_server2" "client-class": "laptops_server2"
} }],
],
"option-data": [ "option-data": [{
{
"name": "routers", "name": "routers",
"data": "192.0.3.1" "data": "192.0.3.1"
} }],
],
"relay": { "ip-address": "10.1.2.3" } "relay": { "ip-address": "10.1.2.3" }
} }],
],
...
}
} }
The configuration provided above splits the address range into four The configuration provided above splits the address range into four
@ -677,17 +626,11 @@ hot-standby configuration:
:: ::
{
"Dhcp4": { "Dhcp4": {
"hooks-libraries": [{
...
"hooks-libraries": [
{
"library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so", "library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so",
"parameters": { } "parameters": { }
}, }, {
{
"library": "/usr/lib/kea/hooks/libdhcp_ha.so", "library": "/usr/lib/kea/hooks/libdhcp_ha.so",
"parameters": { "parameters": {
"high-availability": [{ "high-availability": [{
@ -697,56 +640,40 @@ hot-standby configuration:
"max-response-delay": 10000, "max-response-delay": 10000,
"max-ack-delay": 5000, "max-ack-delay": 5000,
"max-unacked-clients": 5, "max-unacked-clients": 5,
"peers": [ "peers": [{
{
"name": "server1", "name": "server1",
"url": "http://192.168.56.33:8080/", "url": "http://192.168.56.33:8080/",
"role": "primary", "role": "primary",
"auto-failover": true "auto-failover": true
}, }, {
{
"name": "server2", "name": "server2",
"url": "http://192.168.56.66:8080/", "url": "http://192.168.56.66:8080/",
"role": "standby", "role": "standby",
"auto-failover": true "auto-failover": true
}, }, {
{
"name": "server3", "name": "server3",
"url": "http://192.168.56.99:8080/", "url": "http://192.168.56.99:8080/",
"role": "backup", "role": "backup",
"auto-failover": false "auto-failover": false
} }]
]
}] }]
} }
} }],
],
"subnet4": [ "subnet4": [{
{
"subnet": "192.0.3.0/24", "subnet": "192.0.3.0/24",
"pools": [ "pools": [{
{
"pool": "192.0.3.100 - 192.0.3.250", "pool": "192.0.3.100 - 192.0.3.250",
"client-class": "HA_server1" "client-class": "HA_server1"
} }],
],
"option-data": [ "option-data": [{
{
"name": "routers", "name": "routers",
"data": "192.0.3.1" "data": "192.0.3.1"
} }],
],
"relay": { "ip-address": "10.1.2.3" } "relay": { "ip-address": "10.1.2.3" }
} }]
],
...
}
} }
This configuration is very similar to the load-balancing configuration 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": { "Dhcp4": {
// Your regular DHCPv4 configuration parameters here. # Your regular DHCPv4 configuration parameters here.
"hooks-libraries": [ "hooks-libraries": [
{ {
"library": "/usr/local/lib/kea/hooks/libdhc_host_cache.so", "library": "/usr/local/lib/kea/hooks/libdhc_host_cache.so",
"parameters": { "parameters": {
// Tells Kea to never cache more than 1000 hosts. # Tells Kea to never cache more than 1000 hosts.
"maximum": 1000 "maximum": 1000
} }

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

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

42
doc/guide/install.rst
View File

@ -152,7 +152,7 @@ development is done in the “master” branch.
The code can be checked out from The code can be checked out from
``https://gitlab.isc.org/isc-projects/kea.git``: ``https://gitlab.isc.org/isc-projects/kea.git``:
:: .. code-block:: console
$ git clone https://gitlab.isc.org/isc-projects/kea.git $ 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 Kea uses the GNU Build System to discover build environment details. To
generate the makefiles using the defaults, simply run: generate the makefiles using the defaults, simply run:
:: .. code-block:: console
$ ./configure $ ./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 Internet anyway, please set the XSLTPROC_NET environment variable in
configure to any non-empty value, e.g. configure to any non-empty value, e.g.
:: .. code-block:: console
$ ./configure XSLTPROC_NET=yes --enable-generate-docs $ ./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 headers in /usr/pkg/include, specifies that PostgreSQL support should be
enabled, and sets the installation location to /opt/kea: enabled, and sets the installation location to /opt/kea:
:: .. code-block:: console
$ ./configure \ $ ./configure \
--with-boost-include=/usr/pkg/include \ --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 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): sake of this example to be located in /usr/pkg/lib):
:: .. code-block:: console
$ ./configure \ $ ./configure \
--with-boost-libs=-lboost_system \ --with-boost-libs=-lboost_system \
@ -316,7 +316,7 @@ Build
After the configure step is complete, build the executables from the C++ After the configure step is complete, build the executables from the C++
code and prepare the Python scripts by running the command: code and prepare the Python scripts by running the command:
:: .. code-block:: console
$ make $ make
@ -326,7 +326,7 @@ Install
To install the Kea executables, support files, and documentation, issue To install the Kea executables, support files, and documentation, issue
the command: the command:
:: .. code-block:: console
$ make install $ 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 prefix/lib if configured with --prefix) in ``/etc/ld.so.conf`` (or the
relevant linker cache configuration file for your OS): relevant linker cache configuration file for your OS):
:: .. code-block:: console
$ ldconfig $ ldconfig
@ -393,17 +393,17 @@ with the following modification. To enable the MySQL database code, at
the "configure" step (see :ref:`configure`), the "configure" step (see :ref:`configure`),
the --with-mysql switch should be specified: 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 If MySQL was not installed in the default location, the location of the
MySQL configuration program "mysql_config" should be included with the MySQL configuration program "mysql_config" should be included with the
switch, i.e. 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 See :ref:`mysql-database-create` for details regarding MySQL
database configuration. 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, with the following modification. To enable the PostgreSQL database code,
at the "configure" step (see :ref:`configure`), the --with-pgsql switch should be specified: 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 If PostgreSQL was not installed in the default location, the location of
the PostgreSQL configuration program "pg_config" should be included with the PostgreSQL configuration program "pg_config" should be included with
the switch, i.e. 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 See :ref:`pgsql-database-create` for details regarding PostgreSQL
database configuration. 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 Kea as described in :ref:`installation`. To enable the
Cassandra (CQL) database code, at the "configure" step (see :ref:`configure`), enter: 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 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 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 https://github.com/datastax/cpp-driver. In June 2016, the following
commands were used: commands were used:
:: .. code-block:: console
$ git clone https://github.com/datastax/cpp-driver $ git clone https://github.com/datastax/cpp-driver
$ cd 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 with the following modification. To enable the Cassandra (CQL) database
code, at the "configure" step (see :ref:`configure`), enter: 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, supports both DHCPv4 and DHCPv6 protocols along with their extensions,
e.g. prefix delegation and dynamic updates to DNS. e.g. prefix delegation and dynamic updates to DNS.
This guide covers Kea version KEAVERSION. This guide covers Kea version |release|.
Supported Platforms Supported Platforms
=================== ===================
Kea is officially supported on CentOS, Fedora, Ubuntu, Debian, and Kea is officially supported on CentOS, Fedora, Ubuntu, Debian, and
FreeBSD systems. It is also likely to work on many other platforms. 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) - CentOS Linux — 7.1804 (aka 7.5)
- Fedora — 28, 29 - 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 Protocol (DHCP) servers, developed and maintained by Internet Systems
Consortium (ISC). 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, Links to the most up-to-date version of this document (in PDF, HTML,
and plain text formats), along with other documents for 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>`_. 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 Internet Systems Consortium, Inc, a 501(c)3 non-profit organization. ISC
is primarily funded by revenues from support subscriptions for our open is primarily funded by revenues from support subscriptions for our open
source, and we encourage all professional users to consider this option. 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 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 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 We thank all the organizations and individuals who have helped to make
Kea possible. `Comcast <https://www.comcast.com/>`__ and the Comcast 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: ``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 ``<command>`` is one of the commands described in
`Commands <#keactrl-commands>`__. `Commands <#keactrl-commands>`__.
@ -53,7 +53,7 @@ on a per-command basis using the ``-c`` switch.
The contents of ``keactrl.conf`` are: The contents of ``keactrl.conf`` are:
:: .. code-block:: bash
# This is a configuration file for keactrl script which controls # This is a configuration file for keactrl script which controls
# the startup, shutdown, reconfiguration and gathering the status # 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 Typical output from ``keactrl`` when starting the servers looks similar
to the following: to the following:
:: .. code-block:: console
$ keactrl start $ keactrl start
INFO/keactrl: Starting kea-dhcp4 -c /usr/local/etc/kea/kea-dhcp4.conf -d 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 servers are running when the start command is issued, the output will
look similar to the following: look similar to the following:
:: .. code-block:: console
$ keactrl start $ keactrl start
INFO/keactrl: kea-dhcp4 appears to be running, see: PID 10918, PID file: /usr/local/var/kea/kea.kea-dhcp4.pid. 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: The following command stops all servers:
:: .. code-block:: console
$ keactrl stop $ keactrl stop
INFO/keactrl: Stopping kea-dhcp4... 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 of the servers are not running, an informational message is displayed as
in the ``stop`` command output below. in the ``stop`` command output below.
:: .. code-block:: console
$ keactrl stop $ keactrl stop
INFO/keactrl: kea-dhcp4 isn't running. 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 it re-reads its configuration file and, if the new configuration is
valid, uses the new configuration. A reload is executed as follows: valid, uses the new configuration. A reload is executed as follows:
:: .. code-block:: console
$ keactrl reload $ keactrl reload
INFO/keactrl: Reloading kea-dhcp4... 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 configuration has changed, please stop and restart it for the change to
take effect. This limitation will be removed in a future release. take effect. This limitation will be removed in a future release.
:: .. code-block:: console
$ keactrl stop $ keactrl stop
INFO/keactrl: kea-dhcp4 isn't running. 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 Sometimes it is useful to check which servers are running. The
``status`` command reports this, with typical output that looks like: ``status`` command reports this, with typical output that looks like:
:: .. code-block:: console
$ keactrl status $ keactrl status
DHCPv4 server: active 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 ``keactrl`` to stop the ``kea-dhcp4`` and ``kea-dhcp6`` servers and
leave the ``kea-dhcp-ddns`` and ``kea-ctrl-agent`` running: leave the ``kea-dhcp-ddns`` and ``kea-ctrl-agent`` running:
:: .. code-block:: console
$ keactrl stop -s dhcp4,dhcp6 $ keactrl stop -s dhcp4,dhcp6
Similarly, the following will start only the ``kea-dhcp4`` and Similarly, the following will start only the ``kea-dhcp4`` and
``kea-dhcp-ddns`` servers, but not ``kea-dhcp6`` or ``kea-ctrl-agent``. ``kea-dhcp-ddns`` servers, but not ``kea-dhcp6`` or ``kea-ctrl-agent``.
:: .. code-block:: console
$ keactrl start -s dhcp4,dhcp_ddns $ 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: To list the currently installed YANG modules:
:: .. code-block:: console
$ sysrepoctl -l $ sysrepoctl -l
@ -105,12 +105,12 @@ after installation.
To install modules from sources, do the following: To install modules from sources, do the following:
:: .. code-block:: console
cd src/share/yang/modules $ 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 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-dhcp4-server*.yang
sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g kea-dhcp6-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 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: 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 $ 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'... 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 It is possible to confirm whether the models are imported correctly by using
sysrepoctl -l: sysrepoctl -l:
:: .. code-block:: console
$ sysrepoctl -l $ sysrepoctl -l
Sysrepo schema directory: /home/thomson/devel/sysrepo-0.7.6/build/repository/yang/ 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. To install a new revision of a module it must first be uninstalled, e.g.
by: by:
:: .. code-block:: console
sudo sysrepoctl -u -m kea-dhcp4-server 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 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 server provides a YANG interface for all Kea servers and the agent.
{ {
"Netconf": "Netconf":
{ {
// Control flags can be defined in the global scope or # Control flags can be defined in the global scope or
// in a managed server scope. Precedences are: # in a managed server scope. Precedences are:
// - use the default value (true) # - use the default value (true)
// - use the global value # - use the global value
// - use the local value. # - use the local value.
// So this overwrites the default value: # So this overwrites the default value:
"boot-update": false, "boot-update": false,
// This map specifies how each server is managed. For each server there # 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. # is a name of the YANG model to be used and the control channel.
// //
// Currently three control channel types are supported: # Currently three control channel types are supported:
// "stdout" which outputs the configuration on the standard output, # "stdout" which outputs the configuration on the standard output,
// "unix" which uses the local control channel supported by the # "unix" which uses the local control channel supported by the
// "dhcp4" and "dhcp6" servers ("d2" support is not yet available), # "dhcp4" and "dhcp6" servers ("d2" support is not yet available),
// and "http" which uses the Control Agent "ca" to manage itself or # and "http" which uses the Control Agent "ca" to manage itself or
// to forward commands to "dhcp4" or "dhcp6". # to forward commands to "dhcp4" or "dhcp6".
"managed-servers": "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": "dhcp4":
{ {
"comment": "DHCP4 server", "comment": "DHCP4 server",
@ -420,7 +420,7 @@ Kea sources.
} }
}, },
// DHCPv6 parameters. # DHCPv6 parameters.
"dhcp6": "dhcp6":
{ {
"model": "kea-dhcp6-server", "model": "kea-dhcp6-server",
@ -431,8 +431,8 @@ Kea sources.
} }
}, },
// Currently the DHCP-DDNS (nicknamed D2) server does not support # Currently the DHCP-DDNS (nicknamed D2) server does not support
// a command channel. # a command channel.
"d2": "d2":
{ {
"model": "kea-dhcp-ddns", "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": "ca":
{ {
"model": "kea-ctrl-agent", "model": "kea-ctrl-agent",
@ -455,39 +455,39 @@ Kea sources.
} }
}, },
// kea-netconf is able to load hooks libraries that augment its operation. # kea-netconf is able to load hooks libraries that augment its operation.
// Currently there are no hook points defined in kea-netconf # Currently there are no hook points defined in kea-netconf
// processing. # processing.
"hooks-libraries": [ "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", "library": "/opt/local/netconf-commands.so",
// Some libraries may support parameters. Make sure you # Some libraries may support parameters. Make sure you
// type this section carefully, as kea-netconf does not # type this section carefully, as kea-netconf does not
// validate it (because the format is library-specific). # validate it (because the format is library-specific).
"parameters": { "parameters": {
"param1": "foo" "param1": "foo"
} }
} }
], ],
// Similar to other Kea components, NETCONF also uses logging. # Similar to other Kea components, NETCONF also uses logging.
"loggers": [ "loggers": [
{ {
"name": "kea-netconf", "name": "kea-netconf",
"output_options": [ "output_options": [
{ {
"output": "/var/log/kea-netconf.log", "output": "/var/log/kea-netconf.log",
// Several additional parameters are possible in # Several additional parameters are possible in
// addition to the typical output. # addition to the typical output.
// Flush determines whether logger flushes output # Flush determines whether logger flushes output
// to a file. # to a file.
// Maxsize determines maximum filesize before # Maxsize determines maximum filesize before
// the file is being rotated. # the file is being rotated.
// Maxver specifies the maximum number of # Maxver specifies the maximum number of
// rotated files being kept. # rotated files being kept.
"flush": true, "flush": true,
"maxsize": 204800, "maxsize": 204800,
"maxver": 4 "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 possible to rename interfaces, for instance on a Linux with an ens38
interface: interface:
:: .. code-block:: console
# ip link set down dev ens38 # ip link set down dev ens38
# ip link set name eth1 dev ens38 # ip link set name eth1 dev ens38
@ -561,7 +561,7 @@ interface:
The interface must have an address in the test prefix: The interface must have an address in the test prefix:
:: .. code-block:: console
# ip -6 addr add 2001:db8::1/64 dev eth1 # 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 In order to launch the Kea DHCPv6 server using the configuration
contained within the ``boot.json`` file, run: contained within the ``boot.json`` file, run:
:: .. code-block:: console
# kea-dhcp6 -d -c boot.json # kea-dhcp6 -d -c boot.json
The current configuration of the server can be fetched via control The current configuration of the server can be fetched via control
socket by running: socket by running:
:: .. code-block:: console
# echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea6-sock '-,ignoreeof' # 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: The Kea NETCONF agent is launched by:
:: .. code-block:: console
# kea-netconf -d -c netconf.json # 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. possible to populate updates to the configuration to the DHCPv6 server.
The following is the configuration extracted from ``startup.xml``: The following is the configuration extracted from ``startup.xml``:
:: .. code-block:: xml
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"> <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6> <subnet6>
@ -669,7 +669,7 @@ The following is the configuration extracted from ``startup.xml``:
To populate this new configuration: To populate this new configuration:
:: .. code-block:: console
# sysrepocfg -d startup -f xml -i startup.xml kea-dhcp6-server # 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`` In the first case, consider the following ``BAD-schema.xml``
configuration file: configuration file:
:: .. code-block:: xml
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"> <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet4> <subnet4>
@ -727,14 +727,14 @@ configuration file:
It is directly rejected by ``sysrepocfg``: It is directly rejected by ``sysrepocfg``:
:: .. code-block:: console
# sysrepocfg -d running -f xml -i BAD-schema.xml kea-dhcp6-server # sysrepocfg -d running -f xml -i BAD-schema.xml kea-dhcp6-server
In the second case, the configuration is rejected by ``kea-netconf``. In the second case, the configuration is rejected by ``kea-netconf``.
For example, consider this ``BAD-translator.xml`` file: For example, consider this ``BAD-translator.xml`` file:
:: .. code-block:: xml
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"> <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6> <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 In the third case, the configuration is presented to the Kea DHCPv6
server and fails to validate as in this ``BAD-config.xml`` file: 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"> <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6> <subnet6>
@ -793,7 +793,7 @@ NETCONF Operation Example with Two Pools
This example adds a second pool to the initial (i.e. startup) This example adds a second pool to the initial (i.e. startup)
configuration in the ``twopools.xml`` file: configuration in the ``twopools.xml`` file:
:: .. code-block:: xml
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"> <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6> <subnet6>
@ -821,7 +821,7 @@ configuration in the ``twopools.xml`` file:
This configuration is installed by: This configuration is installed by:
:: .. code-block:: console
# sysrepocfg -d running -f xml -i twopools.xml kea-dhcp6-server # 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: This example specifies two subnets in the ``twosubnets.xml`` file:
:: .. code-block:: xml
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"> <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<subnet6> <subnet6>
@ -864,7 +864,7 @@ This example specifies two subnets in the ``twosubnets.xml`` file:
This configuration is installed by: This configuration is installed by:
:: .. code-block:: console
# sysrepocfg -d running -f xml -i twosubnets.xml kea-dhcp6-server # 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) This example adds a logger entry to the initial (i.e. startup)
configuration in the ``logging.xml`` file: configuration in the ``logging.xml`` file:
:: .. code-block:: xml
<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server"> <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
<interfaces-config> <interfaces-config>
@ -947,7 +947,7 @@ The corresponding Kea configuration in JSON is:
Finally, any of the previous examples can be replayed using Finally, any of the previous examples can be replayed using
``sysrepocfg`` in edit mode as follows: ``sysrepocfg`` in edit mode as follows:
:: .. code-block:: console
# sysrepocfg -d running -f xml -e vi kea-dhcp6-server # 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: 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: 4. Go into the source directory and run the configure script:
:: .. code-block:: console
$ cd kea-KEAVERSION $ cd kea-|release|
$ ./configure [your extra parameters] $ ./configure [your extra parameters]
5. Build it: 5. Build it:
:: .. code-block:: console
$ make $ make
6. Install it (by default it will be placed in ``/usr/local/``, so it 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): is likely that you will need root privileges for this step):
:: .. code-block:: console
# make install # 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 8. In order to start the DHCPv4 server in the background, run the
following command (as root): following command (as root):
:: .. code-block:: console
# keactrl start -s dhcp4 # keactrl start -s dhcp4
Or run the following command to start the DHCPv6 server instead: Or run the following command to start the DHCPv6 server instead:
:: .. code-block:: console
# keactrl start -s dhcp6 # keactrl start -s dhcp6
Note that it is also possible to start all servers simultaneously: 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: 9. Verify that the Kea server(s) is/are running:
:: .. code-block:: console
# keactrl status # keactrl status
@ -92,7 +92,7 @@ Quick Start Guide for DHCPv4 and DHCPv6 Services
11. Stop running the server(s): 11. Stop running the server(s):
:: .. code-block:: console
# keactrl stop # keactrl stop
@ -112,12 +112,12 @@ Running the Kea Servers Directly
The Kea servers can be started directly, without the need to use The Kea servers can be started directly, without the need to use
``keactrl``. To start the DHCPv4 server run the following command: ``keactrl``. To start the DHCPv4 server run the following command:
:: .. code-block:: console
# kea-dhcp4 -c /path/to/your/kea4/config/file.json # kea-dhcp4 -c /path/to/your/kea4/config/file.json
Similarly, to start the DHCPv6 server run the following command: Similarly, to start the DHCPv6 server run the following command:
:: .. code-block:: console
# kea-dhcp6 -c /path/to/your/kea6/config/file.json # 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: ``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: where:
@ -71,7 +71,7 @@ all supported commands from the CA, use the ``list-commands`` command.
The following shows a simple example of usage: The following shows a simple example of usage:
:: .. code-block:: console
$ kea-shell --host 192.0.2.1 --port 8001 --service dhcp4 list-commands $ kea-shell --host 192.0.2.1 --port 8001 --service dhcp4 list-commands
^D ^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 been used), along with the parameters specified in param.json. The
result will be stored in result.json. result will be stored in result.json.
:: .. code-block:: console
$ cat param.json $ cat param.json
"filename": "my-config-file.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 ``--path`` parameter should be used. For instance, if requests to the
"/kea" path are forwarded to the CA this can be used: "/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 ... $ kea-shell --host 192.0.2.1 --port 8001 --path kea ...