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

Converting from docbook to sphinx: fixing links, editing grammar and style as needed

Browse Source
This commit is contained in:
Suzanne Goldlust 2019-06-26 16:03:19 -04:00 committed by Michal Nowikowski
parent edfeb3f498
commit 0228c239c1
11 changed files with 850 additions and 868 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/guide/admin.rst
View File

@ -124,7 +124,7 @@ backend may be essential for the success of your deployment.
| | | | | | | | | | | |
+---------------+----------------+----------------+---------------+--------------+ +---------------+----------------+----------------+---------------+--------------+
memfile Memfile
------- -------
The memfile backend is able to store lease information, but cannot The memfile backend is able to store lease information, but cannot
@ -538,7 +538,7 @@ Year 2038 Issue
The lease expiration time is stored in the SQL database for each lease The lease expiration time is stored in the SQL database for each lease
as a timestamp value. Kea developers observed that the MySQL database as a timestamp value. Kea developers observed that the MySQL database
doesn't accept timestamps beyond 2147483647 seconds (the maximum signed doesn't accept timestamps beyond 2147483647 seconds (the maximum signed
32-bit number) from the beginning of the Unix epoch (00:00:00 on 1 32-bit number) from the beginning of the UNIX epoch (00:00:00 on 1
January 1970). Some versions of PostgreSQL do accept greater values, but January 1970). Some versions of PostgreSQL do accept greater values, but
the value is altered when it is read back. For this reason, the lease the value is altered when it is read back. For this reason, the lease
database backends put a restriction on the maximum timestamp to be database backends put a restriction on the maximum timestamp to be

20
doc/guide/classify.rst
View File

@ -26,7 +26,7 @@ client class to receive common options.
An incoming packet can be associated with a client class in several An incoming packet can be associated with a client class in several
ways: ways:
- Implicitly, using a vendor class option or another builtin condition. - Implicitly, using a vendor class option or another built-in condition.
- Using an expression which evaluates to true. - Using an expression which evaluates to true.
@ -49,7 +49,7 @@ The classification process is conducted in several steps:
2. Vendor class options are processed. 2. Vendor class options are processed.
3. Classes with matching expressions and not marked for later evaluation ("on 3. Classes with matching expressions and not marked for later evaluation ("on
request" or depending on the KNOWN/UNKNOWN builtin classes) request" or depending on the KNOWN/UNKNOWN built-in classes)
are processed in the order they are defined in the are processed in the order they are defined in the
configuration; the boolean expression is evaluated and, if it configuration; the boolean expression is evaluated and, if it
returns true ("match"), the incoming packet is associated with the returns true ("match"), the incoming packet is associated with the
@ -74,7 +74,7 @@ The classification process is conducted in several steps:
packet is assigned to the UNKNOWN class. packet is assigned to the UNKNOWN class.
7. Classes with matching expressions - directly, or indirectly using the 7. Classes with matching expressions - directly, or indirectly using the
KNOWN/UNKNOWN builtin classes and not marked for later evaluation ("on KNOWN/UNKNOWN built-in classes and not marked for later evaluation ("on
request") - are processed in the order they are defined request") - are processed in the order they are defined
in the configuration; the boolean expression is evaluated and, if it in the configuration; the boolean expression is evaluated and, if it
returns true ("match"), the incoming packet is associated with the returns true ("match"), the incoming packet is associated with the
@ -128,10 +128,10 @@ value is obtained is unspecified.
.. _classification-using-vendor: .. _classification-using-vendor:
Builtin Client Classes Built-in Client Classes
====================== ======================
Some classes are builtin, so they do not need to be defined. The main Some classes are built-in, so they do not need to be defined. The main
example uses Vendor Class information: the server checks whether an example uses Vendor Class information: the server checks whether an
incoming DHCPv4 packet includes the vendor class identifier option (60) incoming DHCPv4 packet includes the vendor class identifier option (60)
or an incoming DHCPv6 packet includes the vendor class option (16). If or an incoming DHCPv6 packet includes the vendor class option (16). If
@ -150,13 +150,13 @@ be found in :ref:`high-availability-library`.
Other examples are the ALL class, which all incoming packets belong to, Other examples are the ALL class, which all incoming packets belong to,
and the KNOWN class, assigned when host reservations exist for a and the KNOWN class, assigned when host reservations exist for a
particular client. By convention, builtin classes' names begin with all particular client. By convention, built-in classes' names begin with all
capital letters. capital letters.
Currently recognized builtin class names are ALL, KNOWN and UNKNOWN, and the Currently recognized built-in class names are ALL, KNOWN and UNKNOWN, and the
prefixes VENDOR_CLASS_, HA_, AFTER_, and EXTERNAL_. Although the AFTER\_ prefixes VENDOR_CLASS_, HA_, AFTER_, and EXTERNAL_. Although the AFTER\_
prefix is a provision for an as-yet-unwritten hook, the EXTERNAL\_ prefix is a provision for an as-yet-unwritten hook, the EXTERNAL\_
prefix can be freely used; builtin classes are implicitly defined so prefix can be freely used; built-in classes are implicitly defined so
they never raise warnings if they do not appear in the configuration. they never raise warnings if they do not appear in the configuration.
.. _classification-using-expressions: .. _classification-using-expressions:
@ -186,7 +186,7 @@ in the operator returning an empty string.
Dependencies between classes are also checked. For instance, forward Dependencies between classes are also checked. For instance, forward
dependencies are rejected when the configuration is parsed; an dependencies are rejected when the configuration is parsed; an
expression can only depend on already-defined classes (including builtin expression can only depend on already-defined classes (including built-in
classes) which are evaluated in a previous or the same evaluation phase. classes) which are evaluated in a previous or the same evaluation phase.
This does not apply to the KNOWN or UNKNOWN classes. This does not apply to the KNOWN or UNKNOWN classes.
@ -339,7 +339,7 @@ Notes:
- "member('foobar')" checks whether the packet belongs to the client - "member('foobar')" checks whether the packet belongs to the client
class "foobar". To avoid dependency loops, the configuration file class "foobar". To avoid dependency loops, the configuration file
parser verifies whether client classes were already defined or are parser verifies whether client classes were already defined or are
builtin, i.e., beginning by "VENDOR_CLASS_", "AFTER__" (for the built-in, i.e., beginning by "VENDOR_CLASS_", "AFTER__" (for the
to-come "after" hook) and "EXTERNAL_" or equal to "ALL", "KNOWN", to-come "after" hook) and "EXTERNAL_" or equal to "ALL", "KNOWN",
"UNKNOWN", etc. "UNKNOWN", etc.

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

@ -280,12 +280,12 @@ information in a CSV file rather than a database. As well as requiring
less administration, an advantage of using a file for storage is that it less administration, an advantage of using a file for storage is that it
eliminates a dependency on third-party database software. eliminates a dependency on third-party database software.
The configuration of the file backend (Memfile) is controlled through The configuration of the file backend (memfile) is controlled through
the Dhcp4/lease-database parameters. The ``type`` parameter is mandatory the Dhcp4/lease-database parameters. The ``type`` parameter is mandatory
and it specifies which storage for leases the server should use. The and it specifies which storage for leases the server should use. The
value of ``"memfile"`` indicates that the file should be used as the value of ``"memfile"`` indicates that the file should be used as the
storage. The following list gives additional optional parameters that storage. The following list gives additional optional parameters that
can be used to configure the Memfile backend. can be used to configure the memfile backend.
- ``persist``: controls whether the new leases and updates to existing - ``persist``: controls whether the new leases and updates to existing
leases are written to the file. It is strongly recommended that the leases are written to the file. It is strongly recommended that the
@ -310,7 +310,7 @@ can be used to configure the Memfile backend.
value of the ``lfc-interval`` is ``3600``. A value of 0 disables the value of the ``lfc-interval`` is ``3600``. A value of 0 disables the
LFC. LFC.
An example configuration of the Memfile backend is presented below: An example configuration of the memfile backend is presented below:
:: ::
@ -3944,7 +3944,7 @@ which belong to them.
} }
Static class assignments, as shown above, can be used in conjunction Static class assignments, as shown above, can be used in conjunction
with classification, using expressions. The "KNOWN" or "UNKNOWN" builtin with classification, using expressions. The "KNOWN" or "UNKNOWN" built-in
class is added to the packet and any class depending on it (directly or class is added to the packet and any class depending on it (directly or
indirectly) and not only-if-required is evaluated. indirectly) and not only-if-required is evaluated.

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

@ -266,12 +266,12 @@ information in a CSV file rather than a database. As well as requiring
less administration, an advantage of using a file for storage is that it less administration, an advantage of using a file for storage is that it
eliminates a dependency on third-party database software. eliminates a dependency on third-party database software.
The configuration of the file backend (Memfile) is controlled through The configuration of the file backend (memfile) is controlled through
the Dhcp6/lease-database parameters. The ``type`` parameter is mandatory the Dhcp6/lease-database parameters. The ``type`` parameter is mandatory
and it specifies which storage for leases the server should use. The and it specifies which storage for leases the server should use. The
value of ``"memfile"`` indicates that the file should be used as the value of ``"memfile"`` indicates that the file should be used as the
storage. The following list gives additional optional parameters that storage. The following list gives additional optional parameters that
can be used to configure the Memfile backend. can be used to configure the memfile backend.
- ``persist``: controls whether the new leases and updates to existing - ``persist``: controls whether the new leases and updates to existing
leases are written to the file. It is strongly recommended that the leases are written to the file. It is strongly recommended that the
@ -296,7 +296,7 @@ can be used to configure the Memfile backend.
default value of the ``lfc-interval`` is ``3600``. A value of 0 default value of the ``lfc-interval`` is ``3600``. A value of 0
disables the LFC. disables the LFC.
An example configuration of the Memfile backend is presented below: An example configuration of the memfile backend is presented below:
:: ::
@ -3433,7 +3433,7 @@ which belong to them.
} }
Static class assignments, as shown above, can be used in conjunction Static class assignments, as shown above, can be used in conjunction
with classification, using expressions. The "KNOWN" or "UNKNOWN" builtin with classification, using expressions. The "KNOWN" or "UNKNOWN" built-in
class is added to the packet and any class depending on it (directly or class is added to the packet and any class depending on it (directly or
indirectly) and not only-if-required is evaluated. indirectly) and not only-if-required is evaluated.
@ -4411,7 +4411,7 @@ configuration:
This very simple configuration provides DNS server information to This very simple configuration provides DNS server information to
all clients in the network, regardless of their location. Note the all clients in the network, regardless of their location. Note the
specification of the Memfile lease database; this is needed as Kea specification of the memfile lease database; this is needed as Kea
requires a lease database to be specified even if it is not used. requires a lease database to be specified even if it is not used.
.. _dhcp6-rfc7550: .. _dhcp6-rfc7550:

328
doc/guide/hooks-cb-cmds.rst
View File

@ -3,22 +3,22 @@
cb_cmds: Configuration Backend Commands cb_cmds: Configuration Backend Commands
======================================= =======================================
This section describes the ``cb_cmds`` hooks library which is used to This section describes the ``cb_cmds`` hooks library, which is used to
manage Kea servers' configurations in the Configuration Backends. This manage Kea servers' configurations in the Configuration Backends. This
library must be used in conjuction with the available CB hooks libraries library must be used in conjunction with the available CB hooks libraries
implementing the common APIs to create, read, update and delete (CRUD) implementing the common APIs to create, read, update, and delete (CRUD)
the configuration information in the respective databases. For example: the configuration information in the respective databases. For example:
the ``mysql_cb`` hooks library, released in Kea 1.6.0, implements this the ``mysql_cb`` hooks library, released in Kea 1.6.0, implements this
API for MySQL. In order to manage the configuration information in the API for MySQL. In order to manage the configuration information in the
MySQL database both ``mysql_cb`` and ``cb_cmds`` libraries must be MySQL database, both the ``mysql_cb`` and ``cb_cmds`` libraries must be
loaded by the server used for the configuration management. loaded by the server used for the configuration management.
The ``cb_cmds`` library is only available to ISC customers with a The ``cb_cmds`` library is only available to ISC customers with a paid
support contract. support contract.
**Note** **Note**
This library may only be loaded by the ``kea-dhcp4`` or the This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process. ``kea-dhcp6`` process.
Commands Structure Commands Structure
@ -26,23 +26,23 @@ Commands Structure
There are 5 types of commands supported by this library: There are 5 types of commands supported by this library:
- ``del`` - delete selected object from the database, e.g. - ``del`` - delete the selected object from the database, e.g.
``remote-global-parameter4-del`` ``remote-global-parameter4-del``.
- ``get`` - fetch selected object from the database, e.g. - ``get`` - fetch the selected object from the database, e.g.
``remote-subnet4-get``, ``remote-subnet4-get``.
- ``get-all`` - fetch all objects of the particular type from the - ``get-all`` - fetch all objects of the particular type from the
database, e.g. ``remote-option-def4-get-all``, database, e.g. ``remote-option-def4-get-all``.
- ``list`` - list all objects of the particular type in the database, - ``list`` - list all objects of the particular type in the database,
e.g. ``remote-network4-list``; this class of commands returns brief e.g. ``remote-network4-list``; this class of commands returns brief
information about each object comparing to the output of ``get-all``, information about each object comparing to the output of ``get-all``.
- ``set`` - creates or replaces an object of the given type in the - ``set`` - creates or replaces an object of the given type in the
database, e.g. ``remote-option4-global-set`` . database, e.g. ``remote-option4-global-set``.
All types of commands accept optional ``remote`` map which selects the All types of commands accept an optional ``remote`` map which selects the
database instance to which the command refers. For example: database instance to which the command refers. For example:
:: ::
@ -59,21 +59,21 @@ database instance to which the command refers. For example:
} }
selects the MySQL database, running on host 192.0.2.33 and port 3302, to selects the MySQL database, running on host 192.0.2.33 and port 3302, to
fetch the list of subnets from. All parameters in the ``remote`` are fetch the list of subnets from. All parameters in the ``remote`` argument are
optional. The ``port`` parameter can be only specified in conjuction optional. The ``port`` parameter can be only specified in conjunction
with the ``host``. If no parameters in the ``remote`` parameter are to with the ``host``. If no options in the ``remote`` parameter are to
be specified, the parameter should be omitted. In this case, the server be specified, the parameter should be omitted. In this case, the server
will use the first backend listed in the ``config-control`` map within will use the first backend listed in the ``config-control`` map within
the configuration of the server receiving the command. the configuration of the server receiving the command.
**Note** **Note**
In the Kea 1.6.0 release, it is possible to configure the Kea server As of the Kea 1.6.0 release, it is possible to configure the Kea server
to use only one configuration backend. Strictly speaking, it is to use only one configuration backend. Strictly speaking, it is
possible to point Kea server to at most one MySQL database using the possible to point the Kea server to at most one MySQL database using the
``config-control`` parameter. That's why, in this release, the ``config-control`` parameter. That's why, in this release, the
``remote`` parameter may be omitted in the commands because the ``remote`` parameter may be omitted in the commands, because the
cb_cmds hooks library will use by default the sole backend. cb_cmds hooks library will use the sole backend by default.
.. _cb-cmds-dhcp: .. _cb-cmds-dhcp:
@ -83,23 +83,23 @@ Control Commands for DHCP Servers
This section describes and gives some examples of the control commands This section describes and gives some examples of the control commands
implemented by the ``cb_cmds`` hooks library, to manage the implemented by the ``cb_cmds`` hooks library, to manage the
configuration information of the DHCPv4 and DHCPv6 servers. Many of the configuration information of the DHCPv4 and DHCPv6 servers. Many of the
commands are almost identical between DHCPv4 and DHCPv6, i.e. only commands are almost identical between DHCPv4 and DHCPv6; they only
differ by the command name. Other commands slightly differ by the differ by the command name. Other commands differ slightly by the
structure of the inserted data, e.g. the structure of the IPv4 subnet structure of the inserted data; for example, the structure of the IPv4 subnet
information is different than the structure of the IPv6 subnet. information is different than that of the IPv6 subnet.
Nevertheless, they still share the structure of the command arguments Nevertheless, they still share the structure of their command arguments
and thus it makes sense to describe them together. and thus it makes sense to describe them together.
In the following sections, various commands are described and the usage In the following sections, various commands are described and some usage
examples are provided. In the sections jointly describing the DHCPv4 and examples are provided. In the sections jointly describing the DHCPv4 and
DHCPv6 variants of the particular command we sometimes use the following DHCPv6 variants of the particular command, we sometimes use the following
notation - the ``remote-subnet[46]-set`` is the wildcard name for the notation: the ``remote-subnet[46]-set`` is the wildcard name for the
two commands: ``remote-subnet4-set`` and ``remote-subnet6-set``. two commands: ``remote-subnet4-set`` and ``remote-subnet6-set``.
In addition, whenever the text in the subsequent sections refers to a In addition, whenever the text in the subsequent sections refers to a
DHCP command or DHCP parameter, it refers to both DHCPv4 and DHCPv6 DHCP command or DHCP parameter, it refers to both DHCPv4 and DHCPv6
variants. The text specific to the particular server type refers to them variants. The text specific to the particular server type refers to them
as: DHCPv4 command, DHCPv4 parameter, DHCPv6 command, DHCPv6 parameter as: DHCPv4 command, DHCPv4 parameter, DHCPv6 command, DHCPv6 parameter,
etc. etc.
.. _cb-cmds-metadata: .. _cb-cmds-metadata:
@ -108,13 +108,13 @@ Metadata
~~~~~~~~ ~~~~~~~~
The typical response to the ``get`` or ``list`` command includes a list The typical response to the ``get`` or ``list`` command includes a list
of returned objects (e.g. subnets) and each such object contains the of returned objects (e.g. subnets), and each such object contains the
``metadata`` map with some database specific information describing this ``metadata`` map with some database-specific information describing this
object. In other words, the metadata contains any information about the object. In other words, the metadata contains any information about the
fetched object which may be useful for the administrator, but is not the fetched object which may be useful for the administrator, but which is not
part of the object specification from the DHCP server standpoint. In the part of the object specification from the DHCP server standpoint. In the
Kea 1.6.0 release, the metadata is limited to the ``server-tag``, which Kea 1.6.0 release, the metadata is limited to the ``server-tag``, which
describescthe association of the object with the particular server or describes the association of the object with a particular server or
all servers. The server tag is always set to ``all`` in the Kea 1.6.0 all servers. The server tag is always set to ``all`` in the Kea 1.6.0
beta release. beta release.
@ -138,22 +138,22 @@ command, which includes the metadata:
"count": 1 "count": 1
} }
} }
Client implementations must not assume that the metadata contains only Client implementations must not assume that the metadata contains only
the ``server-tag`` parameter. In the future releases this map will be the ``server-tag`` parameter. In future releases, this map will be
extended with additional information, e.g. object modification time, log extended with additional information, e.g. object modification time, log
message created during the last modification etc. message created during the last modification, etc.
.. _command-remote-global-parameter4-del: .. _command-remote-global-parameter4-del:
remote-global-parameter4-del, remote-global-parameter6-del commands The remote-global-parameter4-del, remote-global-parameter6-del Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to delete a global DHCP parameter from the These commands are used to delete a global DHCP parameter from the
configuration database. When the parameter is deleted from the database configuration database. When the parameter is deleted from the database,
the server will use the value specified in the configuration file for the server will use the value specified in the configuration file for
this parameter or a default value if the parameter is not specified in this parameter, or a default value if the parameter is not specified in
the configuration file. the configuration file.
The following command attempts to delete the DHCPv4 ``renew-timer`` The following command attempts to delete the DHCPv4 ``renew-timer``
@ -170,12 +170,12 @@ parameter from the database:
} }
} }
} }
.. _command-remote-global-parameter4-get: .. _command-remote-global-parameter4-get:
remote-global-parameter4-get, remote-global-parameter6-get commands The remote-global-parameter4-get, remote-global-parameter6-get Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to fetch a scalar global DHCP parameter from the These commands are used to fetch a scalar global DHCP parameter from the
configuration database. configuration database.
@ -194,13 +194,13 @@ parameter:
} }
} }
} }
The returned value has one of the four scalar types: string, integer, The returned value has one of the four scalar types: string, integer,
real or boolean. Non scalar global configuration parameters, such as map real, or boolean. Non-scalar global configuration parameters, such as map
or list, are not returned by this command. or list, are not returned by this command.
In case of the example above the string value is returned, e.g.: In the case of the example above, the string value is returned, e.g.:
:: ::
@ -217,7 +217,7 @@ In case of the example above the string value is returned, e.g.:
"count": 1 "count": 1
} }
} }
The example response for the integer value is: The example response for the integer value is:
@ -236,7 +236,7 @@ The example response for the integer value is:
"count": 1 "count": 1
} }
} }
The real value: The real value:
@ -255,7 +255,7 @@ The real value:
"count": 1 "count": 1
} }
} }
Finally, the boolean value: Finally, the boolean value:
@ -274,26 +274,26 @@ Finally, the boolean value:
"count": 1 "count": 1
} }
} }
.. _command-remote-global-parameter4-get-all: .. _command-remote-global-parameter4-get-all:
remote-global-parameter4-get-all, remote-global-parameter6-get-all commands The remote-global-parameter4-get-all, remote-global-parameter6-get-all Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to fetch all global DHCP parameters from the These commands are used to fetch all global DHCP parameters from the
database. They include no arguments besides the optional ``remote`` map. database. They include no arguments besides the optional ``remote`` map.
.. _command-remote-global-parameter4-set: .. _command-remote-global-parameter4-set:
remote-global-parameter4-set The remote-global-parameter4-set Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to create scalar global DHCP parameters in the This command is used to create scalar global DHCP parameters in the
database. If any of the parameters already exists, its value is replaced database. If any of the parameters already exists, its value is replaced
as a result of this command. It is possible to set multiple parameters as a result of this command. It is possible to set multiple parameters
within a single command, each having one of the four types: a string, within a single command, each having one of the four types: string,
integer, real and boolean. For example: integer, real, and boolean. For example:
:: ::
@ -311,26 +311,26 @@ integer, real and boolean. For example:
} }
} }
} }
An error is returned if any of the parameters is not supported by the An error is returned if any of the parameters is not supported by the
DHCP server or its type does not match. Care should be taken when DHCP server or its type does not match. Care should be taken when
multiple parameters are specified in a single command because it is multiple parameters are specified in a single command, because it is
possible that only some of the parameters are stored successfully and possible that only some of the parameters are stored successfully and
some fail. If an error occurred when processing this command, it is some fail. If an error occurs when processing this command, it is
recommended to use ``remote-global-parameter[46]-get-all`` to check recommended to use ``remote-global-parameter[46]-get-all`` to check
which of the parameters have been stored/updated successfully and which which of the parameters have been stored/updated successfully and which
failed. have failed.
.. _command-remote-network4-del: .. _command-remote-network4-del:
remote-network4-del, remote-network6-del commands The remote-network4-del, remote-network6-del Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to delete an IPv4 or IPv6 shared network from These commands are used to delete an IPv4 or IPv6 shared network from
the database. The optional parameter ``subnets-action`` determines the database. The optional parameter ``subnets-action`` determines
whether the subnets belonging to the deleted shared network should also whether the subnets belonging to the deleted shared network should also
be deleted or preserved. The ``subnets-action`` defaults to ``keep``, be deleted or preserved. The ``subnets-action`` parameter defaults to ``keep``,
which preserves the subnets. If it is set to ``delete``, the subnets are which preserves the subnets. If it is set to ``delete``, the subnets are
deleted along with the shared network. deleted along with the shared network.
@ -352,22 +352,22 @@ The following command:
} }
} }
} }
deletes the "level3" IPv6 shared network. The subnets are preserved but
deletes the "level3" IPv6 shared network. The subnets are preserved, but
they are disassociated from the deleted shared network and become they are disassociated from the deleted shared network and become
global. This behavior corresponds to the behavior of the global. This behavior corresponds to the behavior of the
``network[46]-del`` commands with respect to the ``subnets-action``. ``network[46]-del`` commands with respect to the ``subnets-action`` parameter.
.. _command-remote-network4-get: .. _command-remote-network4-get:
remote-network4-get, remote-network6-get commands The remote-network4-get, remote-network6-get Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to retrieve the information about an IPv4 or These commands are used to retrieve information about an IPv4 or
IPv6 shared network. The optional parameter ``subnets-include`` denotes IPv6 shared network. The optional parameter ``subnets-include`` denotes
whether the subnets belonging to the shared network should also be whether the subnets belonging to the shared network should also be
returned. This parameter defaults to ``no`` in which case the subnets returned. This parameter defaults to ``no``, in which case the subnets
are not returned. If this parameter is set to ``full``, the subnets are are not returned. If this parameter is set to ``full``, the subnets are
returned together with the shared network. returned together with the shared network.
@ -390,17 +390,17 @@ with the full information about the subnets belonging to it:
} }
} }
} }
.. _command-remote-network4-list: .. _command-remote-network4-list:
remote-network4-list, remote-network6-list commands The remote-network4-list, remote-network6-list Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to list all IPv4 or IPv6 shared networks in the These commands are used to list all IPv4 or IPv6 shared networks in the
particular database. The returned information about each shared network particular database. The returned information about each shared network
merely contains the shared network name and the metadata. In order to merely contains the shared network name and the metadata. To
fetch the detailed information about the selected shared network, use fetch detailed information about the selected shared network, use
the ``remote-network[46]-get`` command. the ``remote-network[46]-get`` command.
The ``remote-network[46]-list`` takes no argument except the optional The ``remote-network[46]-list`` takes no argument except the optional
@ -408,20 +408,20 @@ The ``remote-network[46]-list`` takes no argument except the optional
.. _command-remote-network4-set: .. _command-remote-network4-set:
remote-network4-set The remote-network4-set, remote-network6-set Commands
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands creates new or replaces an existing IPv4 or IPv6 shared These commands create a new or replace an existing IPv4 or IPv6 shared
network in the database. The structure of the shared network information network in the database. The structure of the shared network information
is the same as in the Kea configuration file (see is the same as in the Kea configuration file (see
`??? <#shared-network4>`__ and `??? <#shared-network6>`__ for details), :ref:`shared-network4` and :ref:`shared-network6` for details),
except that it is not allowed to specify subnets along with the shared except that specifying subnets along with the shared
network information. Including the ``subnet4`` or ``subnet6`` parameter network information is not allowed. Including the ``subnet4`` or ``subnet6`` parameter
within the shared network information will result in an error. within the shared network information will result in an error.
These commands are intended to be used for managing the shared network These commands are intended to be used for managing the shared
specific information and DHCP options. In order to associate and network-specific information and DHCP options. In order to associate and
disassociate the subnets with the shared networks the disassociate the subnets with the shared networks, the
``remote-subnet[46]-set`` commands should be used. ``remote-subnet[46]-set`` commands should be used.
The following command adds the IPv6 shared network "level3" to the The following command adds the IPv6 shared network "level3" to the
@ -447,10 +447,10 @@ database:
} }
} }
} }
This command includes the ``interface`` parameter which sets the shared
network level interface name. Remaining shared network level parameters, This command includes the ``interface`` parameter, which sets the shared
network-level interface name. Any remaining shared network-level parameters,
which are not specified with the command, will be marked as which are not specified with the command, will be marked as
"unspecified" in the database. The DHCP server will use the global "unspecified" in the database. The DHCP server will use the global
values for unspecified parameters or, if the global values are not values for unspecified parameters or, if the global values are not
@ -458,18 +458,18 @@ specified, the default values will be used.
**Note** **Note**
Same as for other "set" commands, this command replaces the entire As with other "set" commands, this command replaces all the
information about the given shared network in the database if the information about the given shared network in the database, if the
shared network already exists. Therefore, when sending this command, shared network already exists. Therefore, when sending this command,
make sure to always include all parameters that must be specified for make sure to always include all parameters that must be specified for
the updated shared network instance. Any unspecified parameter will the updated shared-network instance. Any unspecified parameter will
be marked unspecified in the database, even if its value was present be marked unspecified in the database, even if its value was present
prior to sending the command. prior to sending the command.
.. _command-remote-option-def4-del: .. _command-remote-option-def4-del:
remote-option-def4-del, remote-option-def6-del commands The remote-option-def4-del, remote-option-def6-del Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to delete a DHCP option definition from the These commands are used to delete a DHCP option definition from the
database. The option definition is identified by an option code and database. The option definition is identified by an option code and
@ -491,21 +491,21 @@ option space. For example:
} }
} }
} }
deletes the definition of the option having the code of 1 and belonging deletes the definition of the option having the code of 1 and belonging
to the option space "isc". The default option spaces are "dhcp4" and to the option space "isc". The default option spaces are "dhcp4" and
"dhcp6" for the DHCPv4 and DHCPv6 top level options respectively. "dhcp6" for the DHCPv4 and DHCPv6 top-level options, respectively.
.. _command-remote-option-def4-get: .. _command-remote-option-def4-get:
remote-option-def4-get, remote-option-def6-get commands The remote-option-def4-get, remote-option-def6-get Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to fetch a specified DHCP option definition from These commands are used to fetch a specified DHCP option definition from
the database. The option definition is identified by the option code and the database. The option definition is identified by the option code and
option space. The default option spaces are "dhcp4" and "dhcp6" for the option space. The default option spaces are "dhcp4" and "dhcp6" for the
DHCPv4 and DHCPv6 top level options respectively. DHCPv4 and DHCPv6 top-level options, respectively.
The following command retrieves a DHCPv4 option definition having the The following command retrieves a DHCPv4 option definition having the
code of 1 and belonging to option space "isc": code of 1 and belonging to option space "isc":
@ -526,27 +526,27 @@ code of 1 and belonging to option space "isc":
} }
} }
} }
.. _command-remote-option-def4-get-all: .. _command-remote-option-def4-get-all:
remote-option-def4-get-all, remote-option-def6-get-all commands The remote-option-def4-get-all, remote-option-def6-get-all Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to fetch all DHCP option definitions from the These commands are used to fetch all DHCP option definitions from the
database. It takes no arguments except the optional ``remote`` map. database. They take no arguments except the optional ``remote`` map.
.. _command-remote-option-def4-set: .. _command-remote-option-def4-set:
remote-option-def4-set, remote-option-def6-set commands The remote-option-def4-set, remote-option-def6-set Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands create a new DHCP option definition or replace an These commands create a new DHCP option definition or replace an
existing option definition in the database. The structure of the option existing option definition in the database. The structure of the option
definition information is the same as in the Kea configuration file (see definition information is the same as in the Kea configuration file (see
`??? <#dhcp4-custom-options>`__ and `??? <#dhcp6-custom-options>`__). :ref:`dhcp4-custom-options` and :ref:`dhcp6-custom-options`).
The following command creates the DHCPv4 option definition in the top The following command creates the DHCPv4 option definition in the
level "dhcp4" option space: top-level "dhcp4" option space:
:: ::
@ -569,12 +569,12 @@ level "dhcp4" option space:
} }
} }
} }
.. _command-remote-option4-global-del: .. _command-remote-option4-global-del:
remote-option4-global-del, remote-option6-global-del commands The remote-option4-global-del, remote-option6-global-del Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to delete a global DHCP option from the These commands are used to delete a global DHCP option from the
database. The option is identified by an option code and option space. database. The option is identified by an option code and option space.
@ -596,20 +596,20 @@ For example:
} }
} }
} }
The "dhcp4" is the top level option space where the standard DHCPv4
The "dhcp4" is the top-level option space where the standard DHCPv4
options belong. options belong.
.. _command-remote-option4-global-get: .. _command-remote-option4-global-get:
remote-option4-global-get, remote-option6-global-get commands The remote-option4-global-get, remote-option6-global-get Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to fetch a global DHCP option from the database. These commands are used to fetch a global DHCP option from the database.
The option is identified by the code and option space. The top level The option is identified by the code and option space. The top-level
option spaces where DHCP standard options belong are called "dhcp4" and option spaces where DHCP standard options belong are called "dhcp4" and
"dhcp6" for the DHCPv4 and DHCPv6 servers respectively. "dhcp6" for the DHCPv4 and DHCPv6 servers, respectively.
The following command retrieves the IPv6 "DNS Servers" (code 23) option: The following command retrieves the IPv6 "DNS Servers" (code 23) option:
@ -629,26 +629,26 @@ The following command retrieves the IPv6 "DNS Servers" (code 23) option:
} }
} }
} }
.. _command-remote-option4-global-get-all: .. _command-remote-option4-global-get-all:
remote-option4-global-get-all, remote-option6-global-get-all commands The remote-option4-global-get-all, remote-option6-global-get-all Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to fetch all global DHCP options from the These commands are used to fetch all global DHCP options from the
configuration database. It takes no arguments except the optional configuration database. They take no arguments except the optional
``remote`` map. ``remote`` map.
.. _command-remote-option4-global-set: .. _command-remote-option4-global-set:
remote-option4-global-set, remote-option6-global-set command The remote-option4-global-set, remote-option6-global-set Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands create a new global DHCP option or replace an existing These commands create a new global DHCP option or replace an existing
option in the database. The structure of the option information is the option in the database. The structure of the option information is the
same as in the Kea configuration file (see `??? <#dhcp4-std-options>`__ same as in the Kea configuration file (see :ref:`dhcp4-std-options`
and see `??? <#dhcp4-std-options>`__). For example: and :ref:`dhcp4-std-options`). For example:
:: ::
@ -666,11 +666,11 @@ and see `??? <#dhcp4-std-options>`__). For example:
} }
} }
} }
Note that specifying an option name instead of the option code only Note that specifying an option name instead of the option code only
works reliably for the standard DHCP options. When specifying a value works reliably for the standard DHCP options. When specifying a value
for the user defined DHCP option, the option code should be specified for the user-defined DHCP option, the option code should be specified
instead of the name. For example: instead of the name. For example:
:: ::
@ -687,16 +687,16 @@ instead of the name. For example:
] ]
} }
} }
.. _command-remote-subnet4-del-by-id: .. _command-remote-subnet4-del-by-id:
remote-subnet4-del-by-id, remote-subnet6-del-by-id command The remote-subnet4-del-by-id, remote-subnet6-del-by-id Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the first variant of the commands used to delete an IPv4 or IPv6 This is the first variant of the commands used to delete an IPv4 or IPv6
subnet from the database. It uses subnet ID to identify the subnet. For subnet from the database. It uses the subnet ID to identify the subnet. For
example, in order to delete the IPv4 subnet with ID of 5: example, to delete the IPv4 subnet with an ID of 5:
:: ::
@ -713,12 +713,12 @@ example, in order to delete the IPv4 subnet with ID of 5:
} }
} }
} }
.. _command-remote-subnet4-del-by-prefix: .. _command-remote-subnet4-del-by-prefix:
remote-subnet4-del-by-prefix, remote-subnet6-del-by-prefix commands The remote-subnet4-del-by-prefix, remote-subnet6-del-by-prefix Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the second variant of the commands used to delete an IPv4 or This is the second variant of the commands used to delete an IPv4 or
IPv6 subnet from the database. It uses the subnet prefix to identify the IPv6 subnet from the database. It uses the subnet prefix to identify the
@ -739,12 +739,12 @@ subnet. For example:
} }
} }
} }
.. _command-remote-subnet4-get-by-id: .. _command-remote-subnet4-get-by-id:
remote-subnet4-get-by-id, remote-subnet6-get-by-id commands The remote-subnet4-get-by-id, remote-subnet6-get-by-id Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the first variant of the commands used to fetch an IPv4 or IPv6 This is the first variant of the commands used to fetch an IPv4 or IPv6
subnet from the database. It uses a subnet ID to identify the subnet. subnet from the database. It uses a subnet ID to identify the subnet.
@ -765,12 +765,12 @@ For example:
} }
} }
} }
.. _command-remote-subnet4-get-by-prefix: .. _command-remote-subnet4-get-by-prefix:
remote-subnet4-get-by-prefix, remote-subnet6-get-by-prefix command The remote-subnet4-get-by-prefix, remote-subnet6-get-by-prefix Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the second variant of the commands used to fetch an IPv4 or IPv6 This is the second variant of the commands used to fetch an IPv4 or IPv6
subnet from the database. It uses a subnet prefix to identify the subnet from the database. It uses a subnet prefix to identify the
@ -791,35 +791,35 @@ subnet. For example:
} }
} }
} }
.. _command-remote-subnet4-list: .. _command-remote-subnet4-list:
remote-subnet4-list, remote-subnet6-list commands The remote-subnet4-list, remote-subnet6-list Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to list all IPv4 or IPv6 subnets from the These commands are used to list all IPv4 or IPv6 subnets from the
database. It takes no parameters except the optional ``remote`` map. The database. They take no parameters except the optional ``remote`` map. The
returned information about each subnet is limited to subnet identifier, returned information about each subnet is limited to subnet identifier,
prefix and associated shared network name. In order to retrieve full prefix, and associated shared network name. To retrieve full
information about the selected subnet use the information about the selected subnet, use the
``remote-subnet[46]-get-by-id`` or ``remote-subnet[46]-get-by-prefix``. ``remote-subnet[46]-get-by-id`` or ``remote-subnet[46]-get-by-prefix`` command.
.. _command-remote-subnet4-set: .. _command-remote-subnet4-set:
remote-subnet4-set, remote-subnet6-set commands The remote-subnet4-set, remote-subnet6-set Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to create a new IPv4 or IPv6 subnet or replace These commands are used to create a new IPv4 or IPv6 subnet or replace
an existing subnet in the database. Setting the subnet also associates an existing subnet in the database. Setting the subnet also associates
or disassociates the subnet with a shared network. or disassociates the subnet with a shared network.
The structure of the subnet information is similar to the structure used The structure of the subnet information is similar to the structure used
in the configuration file (see `??? <#dhcp4-configuration>`__ and in the configuration file (see :ref:`dhcp4-configuration` and
`??? <#dhcp6-configuration>`__). The subnet information conveyed in the :ref:`dhcp6-configuration`). The subnet information conveyed in the
``remote-subnet[46]-set`` must include additional parameter ``remote-subnet[46]-set`` command must include the additional parameter
``shared-network-name`` which denotes whether the subnet belongs to a ``shared-network-name``, which denotes whether the subnet belongs to a
shared network or not. shared network.
Consider the following example: Consider the following example:
@ -845,14 +845,14 @@ Consider the following example:
} }
} }
} }
It creates the subnet and associates the subnet with the "level3" shared
network. The "level3" must be created with the ``remote-network4-set``
prior to creating the subnet.
If the created subnet must be global (not associated with any shared It creates the subnet and associates it with the "level3" shared
network), the ``shared-network-name`` must be explicitly set to network. The "level3" shared network must be created with the ``remote-network4-set``
command prior to creating the subnet.
If the created subnet must be global - that is, not associated with any shared
network - the ``shared-network-name`` must be explicitly set to
``null``: ``null``:
:: ::
@ -874,17 +874,17 @@ network), the ``shared-network-name`` must be explicitly set to
] ]
} }
} }
The subnet created in the previous example is replaced with the new The subnet created in the previous example is replaced with the new
subnet having the same parameters but it becomes global. subnet having the same parameters, but it becomes global.
The ``shared-network-name`` parameter is mandatory for the The ``shared-network-name`` parameter is mandatory for the
``remote-subnet4-set`` command. ``remote-subnet4-set`` command.
**Note** **Note**
Same as for other "set" commands, this command replaces the entire As with other "set" commands, this command replaces all the
information about the particular subnet in the database, if the information about the particular subnet in the database, if the
subnet information is already present. Therefore, when sending this subnet information is already present. Therefore, when sending this
command, make sure to always include all parameters that must be command, make sure to always include all parameters that must be

32
doc/guide/hooks-class-cmds.rst
View File

@ -11,20 +11,20 @@ list client classes configured for a given server.
**Note** **Note**
This library may only be loaded by the ``kea-dhcp4`` or the This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process. ``kea-dhcp6`` process.
The Class Commands hooks library is available to premium Kea customers The Class Commands hooks library is currently available only to ISC
only. customers with a paid support contract.
.. _command-class-add: .. _command-class-add:
class-add Command The class-add Command
----------------- ---------------------
The ``class-add`` command adds a new client class to the DHCP server The ``class-add`` command adds a new client class to the DHCP server
configuration. This class is appended at the end of the list of classes configuration. This class is appended at the end of the list of classes
used by the server and may depend on any of the already configured used by the server and may depend on any of the already-configured
client classes. client classes.
The following example demonstrates how to add a new client class to the The following example demonstrates how to add a new client class to the
@ -61,12 +61,12 @@ Here is the response to the ``class-add`` command in our example:
.. _command-class-update: .. _command-class-update:
class-update Command The class-update Command
-------------------- ------------------------
The ``class-update`` command updates an existing client class in the The ``class-update`` command updates an existing client class in the
DHCP server configuration. If the client class with the given name DHCP server configuration. If the client class with the given name
doesn't exist, the server returns the result code of 3, which means that does not exist, the server returns the result code of 3, which means that
the server configuration is not modified and the client class does not the server configuration is not modified and the client class does not
exist. The ``class-add`` command must be used instead to create the new exist. The ``class-add`` command must be used instead to create the new
client class. client class.
@ -110,10 +110,10 @@ the new name will be added at the end of the list of configured classes.
.. _command-class-del: .. _command-class-del:
class-del Command The class-del Command
----------------- ---------------------
The ``class-del`` is used to remove a particular class from the server The ``class-del`` command is used to remove a particular class from the server
configuration. The class to be removed is identified by name. The class configuration. The class to be removed is identified by name. The class
is not removed if there are other classes depending on it; to remove is not removed if there are other classes depending on it; to remove
such a class, the dependent classes must be removed first. such a class, the dependent classes must be removed first.
@ -145,8 +145,8 @@ If the class doesn't exist, the result of 3 is returned.
.. _command-class-list: .. _command-class-list:
class-list Command The class-list Command
------------------ ----------------------
``class-list`` is used to retrieve a list of all client classes. This ``class-list`` is used to retrieve a list of all client classes. This
command includes no arguments: command includes no arguments:
@ -183,8 +183,8 @@ merely class names. To retrieve full class information, the
.. _command-class-get: .. _command-class-get:
class-get Command The class-get Command
----------------- ---------------------
``class-get`` is used to retrieve detailed information about a specified ``class-get`` is used to retrieve detailed information about a specified
class. The command structure is very simple: class. The command structure is very simple:

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

@ -11,7 +11,7 @@ but is now part of the open source Kea, available to all users.
**Note** **Note**
This library may only be loaded by the ``kea-dhcp4`` or the This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process. ``kea-dhcp6`` process.
High Availability (HA) of the DHCP service is provided by running High Availability (HA) of the DHCP service is provided by running
@ -44,13 +44,13 @@ Supported Configurations
------------------------ ------------------------
The Kea HA hook library supports two configurations, also known as HA The Kea HA hook library supports two configurations, also known as HA
modes: load balancing and hot standby. In the load-balancing mode, two modes: load-balancing and hot-standby. In the load-balancing mode, two
servers respond to DHCP requests. The load-balancing function is servers respond to DHCP requests. The load-balancing function is
implemented as described in `RFC implemented as described in `RFC
3074 <http://tools.ietf.org/html/rfc3074>`__, with each server 3074 <https://tools.ietf.org/html/rfc3074>`__, with each server
responding to half the received DHCP queries. When one of the servers responding to half the received DHCP queries. When one of the servers
allocates a lease for a client, it notifies the partner server over the allocates a lease for a client, it notifies the partner server over the
control channel (RESTful API), so the partner can save the lease control channel (the RESTful API), so the partner can save the lease
information in its own database. If the communication with the partner information in its own database. If the communication with the partner
is unsuccessful, the DHCP query is dropped and the response is not is unsuccessful, the DHCP query is dropped and the response is not
returned to the DHCP client. If the lease update is successful, the returned to the DHCP client. If the lease update is successful, the
@ -70,7 +70,7 @@ the primary server to complete the lease database synchronization before
it starts the synchronization. it starts the synchronization.
In the hot-standby configuration, one of the servers is also designated In the hot-standby configuration, one of the servers is also designated
as "primary" and the second as "secondary". However, during normal as "primary" and the second as "secondary." However, during normal
operation, the primary server is the only one that responds to DHCP operation, the primary server is the only one that responds to DHCP
requests. The secondary or standby server receives lease updates from requests. The secondary or standby server receives lease updates from
the primary over the control channel; however, it does not respond to the primary over the control channel; however, it does not respond to
@ -79,13 +79,13 @@ until the secondary considers the primary to be offline. If the
secondary server detects the failure of the primary, it starts secondary server detects the failure of the primary, it starts
responding to all DHCP queries. responding to all DHCP queries.
In the configurations described above, the primary, secondary, and In the configurations described above, the primary and secondary/standby
standby are referred to as "active" servers, because they receive lease are referred to as "active" servers, because they receive lease
updates and can automatically react to the partner's failures by updates and can automatically react to the partner's failures by
responding to the DHCP queries which would normally be handled by the responding to the DHCP queries which would normally be handled by the
partner. The HA hook library supports another server type/role: backup partner. The HA hook library supports another server type/role: backup
server. The use of a backup server is optional. They can be used in both server. The use of a backup server is optional, and can be implemented in both
load balancing and hot standby setup, in addition to the active servers. load-balancing and hot-standby setup, in addition to the active servers.
There is no limit on the number of backup servers in the HA setup; There is no limit on the number of backup servers in the HA setup;
however, the presence of backup servers increases the latency of DHCP however, the presence of backup servers increases the latency of DHCP
responses, because not only do active servers send lease updates to each responses, because not only do active servers send lease updates to each
@ -97,7 +97,7 @@ Clocks on Active Servers
Synchronized clocks are essential for the HA setup to operate reliably. Synchronized clocks are essential for the HA setup to operate reliably.
The servers share lease information via lease updates and during The servers share lease information via lease updates and during
synchronization of the databases. The lease information includes the synchronization of the databases. The lease information includes the
time when the lease has been allocated and when it expires. Some clock time when the lease was allocated and when it expires. Some clock
skew between the servers participating in the HA setup usually exists; skew between the servers participating in the HA setup usually exists;
this is acceptable as long as the clock skew is relatively low, compared this is acceptable as long as the clock skew is relatively low, compared
to the lease lifetimes. However, if the clock skew becomes too high, the to the lease lifetimes. However, if the clock skew becomes too high, the
@ -115,7 +115,7 @@ partner and receiving this response by the server which sent the
heartbeat command. If the clock skew exceeds 30 seconds, a warning log heartbeat command. If the clock skew exceeds 30 seconds, a warning log
message is issued. The administrator may correct this problem by message is issued. The administrator may correct this problem by
synchronizing the clocks (e.g. using NTP); the servers should notice the synchronizing the clocks (e.g. using NTP); the servers should notice the
clock skew correction and stop issuing the warning clock skew correction and stop issuing the warning.
If the clock skew is not corrected and exceeds 60 seconds, the HA If the clock skew is not corrected and exceeds 60 seconds, the HA
service on each of the servers is terminated, i.e. the state machine service on each of the servers is terminated, i.e. the state machine
@ -135,10 +135,10 @@ state of the server can be retrieved by its peers using the
``ha-heartbeat`` command sent over the RESTful API. If the partner ``ha-heartbeat`` command sent over the RESTful API. If the partner
server doesn't respond to the ``ha-heartbeat`` command within the server doesn't respond to the ``ha-heartbeat`` command within the
specified amount of time, the communication is considered interrupted specified amount of time, the communication is considered interrupted
and the server may (depending on the configuration) use additional and the server may, depending on the configuration, use additional
measures (described later in this document) to verify that the partner measures (described later in this document) to verify that the partner
is still operating. If it finds that the partner is not operating, the is still operating. If it finds that the partner is not operating, the
server transitions to the ``partner-down`` state to handle the entire server transitions to the ``partner-down`` state to handle all the
DHCP traffic directed to the system. DHCP traffic directed to the system.
In this case, the surviving server continues to send the In this case, the surviving server continues to send the
@ -181,7 +181,7 @@ The following is the list of all possible server states:
leases from the active partner and update the local lease database. leases from the active partner and update the local lease database.
When in this state, the server issues the ``dhcp-disable`` command to When in this state, the server issues the ``dhcp-disable`` command to
disable the DHCP service of the partner from which the leases are disable the DHCP service of the partner from which the leases are
fetched. The DHCP service is disabled for the maximum time of 60 fetched. The DHCP service is disabled for a maximum time of 60
seconds, after which it is automatically re-enabled, in case the seconds, after which it is automatically re-enabled, in case the
syncing partner was unable to re-enable the service. If the syncing partner was unable to re-enable the service. If the
synchronization is completed, the syncing server issues the synchronization is completed, the syncing server issues the
@ -204,8 +204,8 @@ The following is the list of all possible server states:
exchanged and the heartbeats are not sent. Once a server has entered exchanged and the heartbeats are not sent. Once a server has entered
the "terminated" state, it will remain in this state until it is the "terminated" state, it will remain in this state until it is
restarted. The administrator must correct the issue which caused this restarted. The administrator must correct the issue which caused this
situation prior to restarting the server (e.g. synchronize clocks). situation prior to restarting the server (e.g. synchronize the clocks);
Otherwise, the server will return to the "terminated" state once it otherwise, the server will return to the "terminated" state once it
finds that the issue persists. finds that the issue persists.
- ``waiting`` - each started server instance enters this state. The - ``waiting`` - each started server instance enters this state. The
@ -271,12 +271,12 @@ the scopes can be found below.
The DHCP service scopes require some explanation. The HA configuration The DHCP service scopes require some explanation. The HA configuration
must specify a unique name for each server within the HA setup. This must specify a unique name for each server within the HA setup. This
document uses the following convention within provided examples: document uses the following convention within the provided examples:
``server1`` for a primary server, ``server2`` for the secondary or ``server1`` for a primary server, ``server2`` for the secondary or
standby server, and ``server3`` for the backup server. In real life any standby server, and ``server3`` for the backup server. In real life any
names can be used as long as they remain unique. names can be used as long as they remain unique.
In the load-balancing mode there are two scopes named after the active In the load-balancing mode there are two scopes specified for the active
servers: ``HA_server1`` and ``HA_server2``. The DHCP queries servers: ``HA_server1`` and ``HA_server2``. The DHCP queries
load-balanced to ``server1`` belong to the ``HA_server1`` scope and the load-balanced to ``server1`` belong to the ``HA_server1`` scope and the
queries load-balanced to ``server2`` belong to the ``HA_server2`` scope. queries load-balanced to ``server2`` belong to the ``HA_server2`` scope.
@ -452,9 +452,9 @@ behavior with respect to HA:
it is greater than the duration of multiple ``heartbeat-delay`` it is greater than the duration of multiple ``heartbeat-delay``
values. When the server detects that communication is interrupted, it values. When the server detects that communication is interrupted, it
may transition to the ``partner-down`` state (when may transition to the ``partner-down`` state (when
``max-unacked-clients`` is 0) or trigger the failure- detection ``max-unacked-clients`` is 0) or trigger the failure-detection
procedure using the values of the two parameters below. The default procedure using the values of the two parameters below. The default
value of this parameter is 60000. value of this parameter is 60000 ms.
- ``max-ack-delay`` - is one of the parameters controlling partner - ``max-ack-delay`` - is one of the parameters controlling partner
failure-detection. When communication with the partner is failure-detection. When communication with the partner is
@ -485,7 +485,7 @@ low a value for the ``max-unacked-clients`` parameter may result in a
transition to the ``partner-down`` state even though the partner is transition to the ``partner-down`` state even though the partner is
still operating. On the other hand, selecting too high a value may still operating. On the other hand, selecting too high a value may
result in never transitioning to the ``partner-down`` state if the DHCP result in never transitioning to the ``partner-down`` state if the DHCP
traffic in the network is very low (e.g. nighttime), because the number traffic in the network is very low (e.g. at nighttime), because the number
of distinct clients trying to communicate with the server could be lower of distinct clients trying to communicate with the server could be lower
than the ``max-unacked-clients`` setting. than the ``max-unacked-clients`` setting.
@ -544,7 +544,7 @@ received DHCP queries. In many cases, HA will be needed in deployments
which already use some other client classification. which already use some other client classification.
Suppose there is a system which classifies devices into two groups: Suppose there is a system which classifies devices into two groups:
phones and laptops, based on some classification criteria specified in phones and laptops, based on some classification criteria specified in the
Kea configuration file. Both types of devices are allocated leases from Kea configuration file. Both types of devices are allocated leases from
different address pools. Introducing HA in the load-balancing mode different address pools. Introducing HA in the load-balancing mode
results in a further split of each of those pools, as each server results in a further split of each of those pools, as each server
@ -561,7 +561,7 @@ the existing pools to be split between ``HA_server1`` and
- laptops_server2 - laptops_server2
The corresponding server configuration using advanced classification The corresponding server configuration using advanced classification
(and ``member`` expression) is provided below. For brevity's sake, the (and the ``member`` expression) is provided below. For brevity's sake, the
HA hook library configuration has been removed from this example. HA hook library configuration has been removed from this example.
:: ::
@ -657,14 +657,14 @@ pools: two pools dedicated to server1 and two to server2. Each server
can assign leases to both phones and laptops. Both groups of devices are can assign leases to both phones and laptops. Both groups of devices are
assigned addresses from different pools. The ``HA_server1`` and assigned addresses from different pools. The ``HA_server1`` and
``HA_server2`` classes are built-in (see ``HA_server2`` classes are built-in (see
`??? <#classification-using-vendor>`__) and do not need to be declared. :ref:`classification-using-vendor`) and do not need to be declared.
They are assigned dynamically by the HA hook library as a result of the They are assigned dynamically by the HA hook library as a result of the
load-balancing algorithm. ``phones_*`` and ``laptop_*`` evaluate to load-balancing algorithm. ``phones_*`` and ``laptop_*`` evaluate to
"true" when the query belongs to a given combination of other classes, "true" when the query belongs to a given combination of other classes,
e.g. ``HA_server1`` and ``phones``. The pool is selected accordingly as e.g. ``HA_server1`` and ``phones``. The pool is selected accordingly as
a result of such an evaluation. a result of such an evaluation.
Consult `??? <#classify>`__ for details on how to use the ``member`` Consult :ref:`classify` for details on how to use the ``member``
expression and class dependencies. expression and class dependencies.
.. _ha-hot-standby-config: .. _ha-hot-standby-config:
@ -750,8 +750,7 @@ hot-standby configuration:
} }
This configuration is very similar to the load-balancing configuration This configuration is very similar to the load-balancing configuration
described in `Load-Balancing described in :ref:`ha-load-balancing-config`, with a few notable
Configuration <#ha-load-balancing-config>`__, with a few notable
differences. differences.
The ``mode`` is now set to ``hot-standby``, in which only one server The ``mode`` is now set to ``hot-standby``, in which only one server
@ -789,7 +788,7 @@ In some cases, though, it is desirable to disable lease updates and/or
database synchronization between the active servers, if the exchange of database synchronization between the active servers, if the exchange of
information about the allocated leases is performed using some other information about the allocated leases is performed using some other
mechanism. Kea supports various database types that can be used to store mechanism. Kea supports various database types that can be used to store
leases, including MySQL, Postgres, and Cassandra. Those databases leases, including MySQL, PostgreSQL, and Cassandra. Those databases
include built-in solutions for data replication which are often used by include built-in solutions for data replication which are often used by
Kea administrators to provide redundancy. Kea administrators to provide redundancy.
@ -859,11 +858,11 @@ Controlling Lease-Page Size Limit
An HA-enabled server initiates synchronization of the lease database An HA-enabled server initiates synchronization of the lease database
after downtime or upon receiving the ``ha-sync`` command. The server after downtime or upon receiving the ``ha-sync`` command. The server
uses commands described in `??? <#lease-get-page-cmds>`__ to fetch uses commands described in :ref:`lease-get-page-cmds` to fetch
leases from its partner server (lease queries). The size of the results leases from its partner server (lease queries). The size of the results
page (the maximum number of leases to be returned in a single response page (the maximum number of leases to be returned in a single response
to one of these commands) can be controlled via HA hooks library to one of these commands) can be controlled via configuration of the HA hooks
configuration. Increasing the page size decreases the number of lease library. Increasing the page size decreases the number of lease
queries sent to the partner server, but it causes the partner server to queries sent to the partner server, but it causes the partner server to
generate larger responses, which lengthens transmission time as well as generate larger responses, which lengthens transmission time as well as
increases memory and CPU utilization on both servers. Decreasing the increases memory and CPU utilization on both servers. Decreasing the
@ -885,8 +884,7 @@ lease-database synchronization after a server failure may be a
time-consuming operation. The synchronizing server must gather all time-consuming operation. The synchronizing server must gather all
leases from its partner, which yields a large response over the RESTful leases from its partner, which yields a large response over the RESTful
interface. The server receives leases using the paging mechanism interface. The server receives leases using the paging mechanism
described in `Controlling Lease-Page Size described in :ref:`ha-syncing-page-limit`. Before the page of leases is fetched,
Limit <#ha-syncing-page-limit>`__. Before the page of leases is fetched,
the synchronizing server sends a ``dhcp-disable`` command to disable the the synchronizing server sends a ``dhcp-disable`` command to disable the
DHCP service on the partner server. If the service is already disabled, DHCP service on the partner server. If the service is already disabled,
this command will reset the timeout for the DHCP service being disabled. this command will reset the timeout for the DHCP service being disabled.
@ -897,7 +895,7 @@ service. The connection of the synchronizing server with its partner is
also protected by the timeout. If the synchronization of a single page also protected by the timeout. If the synchronization of a single page
of leases takes longer than the specified time, the synchronizing server of leases takes longer than the specified time, the synchronizing server
terminates the connection and the synchronization fails. Both timeout terminates the connection and the synchronization fails. Both timeout
values are controlled by a single configuration parameter: values are controlled by a single configuration parameter,
``sync-timeout``. The following configuration snippet demonstrates how ``sync-timeout``. The following configuration snippet demonstrates how
to modify the timeout for automatic re-enabling of the DHCP service on to modify the timeout for automatic re-enabling of the DHCP service on
the partner server and how to increase the timeout for fetching a single the partner server and how to increase the timeout for fetching a single
@ -960,7 +958,7 @@ Pausing HA State Machine
------------------------ ------------------------
The high-availability state machine includes many different states The high-availability state machine includes many different states
described in detail in `Server States <#ha-server-states>`__. The server described in detail in :ref:`ha-server-states`. The server
enters each state when certain conditions are met, most often taking enters each state when certain conditions are met, most often taking
into account the partner server's state. In some states the server into account the partner server's state. In some states the server
performs specific actions, e.g. synchronization of the lease database in performs specific actions, e.g. synchronization of the lease database in
@ -970,7 +968,7 @@ configured mode of operation in the ``load-balancing`` and
By default, transitions between the states are performed automatically By default, transitions between the states are performed automatically
and the server administrator has no direct control when the transitions and the server administrator has no direct control when the transitions
take place; in most cases, the administrator doesn't need such control. take place; in most cases, the administrator does not need such control.
In some situations, however, the administrator may want to "pause" the In some situations, however, the administrator may want to "pause" the
HA state machine in a selected state to perform some additional HA state machine in a selected state to perform some additional
administrative actions before the server transitions to the next state. administrative actions before the server transitions to the next state.
@ -981,7 +979,7 @@ enters the ``syncing`` state by querying the partner server for leases,
but it is possible that the partner was also experiencing a failure and but it is possible that the partner was also experiencing a failure and
lacks lease information. In this case, it may be required to reconstruct lacks lease information. In this case, it may be required to reconstruct
lease databases on both servers from some external source, e.g. a backup lease databases on both servers from some external source, e.g. a backup
server. If the lease database is to be reconstructed via RESTful API, server. If the lease database is to be reconstructed via the RESTful API,
the servers should be started in the initial, i.e. ``waiting``, state the servers should be started in the initial, i.e. ``waiting``, state
and remain in this state while leases are being added. In particular, and remain in this state while leases are being added. In particular,
the servers should not attempt to synchronize their lease databases nor the servers should not attempt to synchronize their lease databases nor
@ -1041,14 +1039,13 @@ following configuration causes the HA state machine to pause in the
The ``pause`` parameter value ``once`` denotes that the state machine The ``pause`` parameter value ``once`` denotes that the state machine
should be paused upon the first transition to the ``waiting`` state; should be paused upon the first transition to the ``waiting`` state;
later transitions to this state will not cause the state machine to later transitions to this state will not cause the state machine to
pause. Two other supported values of the ``pause`` parameter are: pause. Two other supported values of the ``pause`` parameter are
``always`` and ``never``. The latter is the default value for each ``always`` and ``never``. The latter is the default value for each
state, which instructs the server never to pause the state machine. state, which instructs the server never to pause the state machine.
In order to "unpause" the state machine, the ``ha-continue`` command In order to "unpause" the state machine, the ``ha-continue`` command
must be sent to the paused server. This command does not take any must be sent to the paused server. This command does not take any
arguments. See `Control Commands for High arguments. See :ref:`ha-control-commands` for details about commands
Availability <#ha-control-commands>`__ for details about commands
specific to the HA hooks library. specific to the HA hooks library.
It is possible to configure the state machine to pause in more than one It is possible to configure the state machine to pause in more than one
@ -1108,7 +1105,7 @@ This configuration instructs the server to pause the state machine every
time it transitions to the ``ready`` state and upon the first transition time it transitions to the ``ready`` state and upon the first transition
to the ``partner-down`` state. to the ``partner-down`` state.
Refer to `Server States <#ha-server-states>`__ for a complete list of Refer to :ref:`ha-server-states` for a complete list of
server states. The state machine can be paused in any of the supported server states. The state machine can be paused in any of the supported
states; however, it is not practical for the ``backup`` and states; however, it is not practical for the ``backup`` and
``terminated`` states because the server never transitions out of these ``terminated`` states because the server never transitions out of these
@ -1138,9 +1135,9 @@ states anyway.
Control Agent Configuration Control Agent Configuration
--------------------------- ---------------------------
`??? <#kea-ctrl-agent>`__ describes in detail the Kea daemon, which :ref:`kea-ctrl-agent` describes in detail the Kea daemon, which
provides a RESTful interface to control Kea servers. The same provides a RESTful interface to control the Kea servers. The same
functionality is used by the High Availability hook library to establish functionality is used by the High Availability hooks library to establish
communication between the HA peers. Therefore, the HA library requires communication between the HA peers. Therefore, the HA library requires
that the Control Agent (CA) be started for each DHCP instance within the that the Control Agent (CA) be started for each DHCP instance within the
HA setup. If the Control Agent is not started, the peers will not be HA setup. If the Control Agent is not started, the peers will not be
@ -1186,18 +1183,18 @@ trigger lease-database synchronization on demand. It may also be useful
to manually set the HA scopes that are being served. to manually set the HA scopes that are being served.
Note that the backup server can sometimes be used to handle DHCP traffic Note that the backup server can sometimes be used to handle DHCP traffic
if both active servers are down. The backup servers do not perform if both active servers are down. The backup server does not perform
failover function automatically. Thus, in order to use the backup server failover function automatically; thus, in order to use the backup server
to respond to DHCP queries, the server administrator must enable this to respond to DHCP queries, the server administrator must enable this
function manually. function manually.
The following sections describe commands supported by the HA hook The following sections describe commands supported by the HA hooks
library which are available for the administrator. library which are available for the administrator.
.. _command-ha-sync: .. _command-ha-sync:
ha-sync Command The ha-sync Command
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
The ``ha-sync`` command instructs the server to synchronize its local The ``ha-sync`` command instructs the server to synchronize its local
lease database with the selected peer. The server fetches all leases lease database with the selected peer. The server fetches all leases
@ -1207,7 +1204,7 @@ do not exist in the local database. All leases that are not returned by
the peer but are in the local database are preserved. The database the peer but are in the local database are preserved. The database
synchronization is unidirectional; only the database on the server to synchronization is unidirectional; only the database on the server to
which the command has been sent is updated. In order to synchronize the which the command has been sent is updated. In order to synchronize the
peer's database a separate ``ha-sync`` has to be issued to that peer. peer's database a separate ``ha-sync`` command must be issued to that peer.
Database synchronization may be triggered for both active and backup Database synchronization may be triggered for both active and backup
server types. The ``ha-sync`` command has the following structure server types. The ``ha-sync`` command has the following structure
@ -1229,13 +1226,13 @@ of the server from which it will be fetching leases, by sending the
``dhcp-disable`` command to that server. The ``max-period`` parameter ``dhcp-disable`` command to that server. The ``max-period`` parameter
specifies the maximum duration (in seconds) for which the DHCP service specifies the maximum duration (in seconds) for which the DHCP service
should be disabled. If the DHCP service is successfully disabled, the should be disabled. If the DHCP service is successfully disabled, the
synchronizing server will fetch leases from the remote server by issuing synchronizing server fetches leases from the remote server by issuing
one or more ``lease4-get-page`` commands. When the lease- database one or more ``lease4-get-page`` commands. When the lease-database
synchronization is complete, the synchronizing server sends the synchronization is complete, the synchronizing server sends the
``dhcp-enable`` command to the peer to re-enable its DHCP service. ``dhcp-enable`` command to the peer to re-enable its DHCP service.
The ``max-period`` value should be sufficiently long to guarantee that The ``max-period`` value should be sufficiently long to guarantee that
it doesn't elapse before the synchronization is completed. Otherwise, it does not elapse before the synchronization is completed. Otherwise,
the DHCP server will automatically enable its DHCP function while the the DHCP server will automatically enable its DHCP function while the
synchronization is still in progress. If the DHCP server subsequently synchronization is still in progress. If the DHCP server subsequently
allocates any leases during the synchronization, those new (or updated) allocates any leases during the synchronization, those new (or updated)
@ -1244,13 +1241,12 @@ database inconsistencies.
.. _command-ha-scopes: .. _command-ha-scopes:
ha-scopes Command The ha-scopes Command
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
This command allows modification of the HA scopes that the server is This command allows modification of the HA scopes that the server is
serving. Consult `Load-Balancing serving. Consult :ref:`ha-load-balancing-config` and
Configuration <#ha-load-balancing-config>`__ and `Hot-Standby :ref:`ha-hot-standby-config` to learn what scopes are
Configuration <#ha-hot-standby-config>`__ to learn what scopes are
available for different HA modes of operation. The ``ha-scopes`` command available for different HA modes of operation. The ``ha-scopes`` command
has the following structure (DHCPv4 server case): has the following structure (DHCPv4 server case):
@ -1264,8 +1260,8 @@ has the following structure (DHCPv4 server case):
} }
} }
This command configures the server to handle traffic from both This command configures the server to handle traffic from both the
``HA_server1`` and ``HA_server2`` scopes. In order to disable all scopes ``HA_server1`` and ``HA_server2`` scopes. To disable all scopes
specify an empty list: specify an empty list:
:: ::
@ -1280,12 +1276,11 @@ specify an empty list:
.. _command-ha-continue: .. _command-ha-continue:
ha-continue Command The ha-continue Command
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
This command is used to resume the operation of the paused HA state This command is used to resume the operation of the paused HA state
machine, as described in `Pausing HA State machine, as described in :ref:`ha-pause-state-machine`. It takes no arguments, so the
Machine <#ha-pause-state-machine>`__. It takes no arguments, so the
command structure is as simple as: command structure is as simple as:
:: ::

100
doc/guide/hooks-lease-cmds.rst
View File

@ -5,12 +5,12 @@ lease_cmds: Lease Commands
This section describes the hook library with commands used to manage This section describes the hook library with commands used to manage
leases. Kea provides a way to store lease information in several leases. Kea provides a way to store lease information in several
backends (memfile, MySQL, PostgreSQL and Cassandra), and this library backends (memfile, MySQL, PostgreSQL, and Cassandra), and this library
provides a interface that can manipulate leases in a unified, safe way. provides an interface that can manipulate leases in a unified, safe way.
In particular, it allows things previously impossible: lease In particular, it allows things previously impossible: lease
manipulation in memfile while Kea is running, sanity check changes, manipulation in memfile while Kea is running, sanity check changes,
lease existence checks, and removal of all leases belonging to a lease existence checks, and removal of all leases belonging to a
specific subnet. It can also catch more obscure errors, like an attempt specific subnet. The hook library can also catch more obscure errors, like an attempt
to add a lease with a subnet-id that does not exist in the to add a lease with a subnet-id that does not exist in the
configuration, or configuring a lease to use an address that is outside configuration, or configuring a lease to use an address that is outside
of the subnet to which it is supposed to belong. The library also of the subnet to which it is supposed to belong. The library also
@ -25,57 +25,57 @@ leases.
There are many use cases where an administrative command may be useful; There are many use cases where an administrative command may be useful;
for example, during migration between servers or different vendors, when for example, during migration between servers or different vendors, when
a certain network is being retired, or when a device has been a certain network is being retired, or when a device has been
disconnected and the sysadmin knows for sure that it will not be coming disconnected and the system administrator knows that it will not be coming
back. The "get" queries may be useful for automating certain management back. The "get" queries may be useful for automating certain management
and monitoring tasks. They can also act as preparatory steps for lease and monitoring tasks. They can also act as preparatory steps for lease
updates and removals. updates and removals.
This library provides the following commands: This library provides the following commands:
- ``lease4-add`` - adds a new IPv4 lease; - ``lease4-add`` - adds a new IPv4 lease.
- ``lease6-add`` - adds a new IPv6 lease; - ``lease6-add`` - adds a new IPv6 lease.
- ``lease4-get`` - checks whether an IPv4 lease with the specified - ``lease4-get`` - checks whether an IPv4 lease with the specified
parameters exists and returns it if it does; parameters exists and returns it if it does.
- ``lease6-get`` - checks whether an IPv6 lease with the specified - ``lease6-get`` - checks whether an IPv6 lease with the specified
parameters exists and returns it if it does; parameters exists and returns it if it does.
- ``lease4-get-all`` - returns all IPv4 leases or all IPv4 leases for - ``lease4-get-all`` - returns all IPv4 leases or all IPv4 leases for
the specified subnets; the specified subnets.
- ``lease6-get-all`` - returns all IPv6 leases or all IPv6 leases for - ``lease6-get-all`` - returns all IPv6 leases or all IPv6 leases for
the specified subnets; the specified subnets.
- ``lease4-get-page`` - returns a set ("page") of leases from the list - ``lease4-get-page`` - returns a set ("page") of leases from the list
of all IPv4 leases in the database. By iterating through the pages it of all IPv4 leases in the database. By iterating through the pages it
is possible to retrieve all the leases; is possible to retrieve all the leases.
- ``lease6-get-page`` - returns a set ("page") of leases from the list - ``lease6-get-page`` - returns a set ("page") of leases from the list
of all IPv6 leases in the database. By iterating through the pages it of all IPv6 leases in the database. By iterating through the pages it
is possible to retrieve all the leases; is possible to retrieve all the leases.
- ``lease4-del`` - deletes an IPv4 lease with the specified parameters; - ``lease4-del`` - deletes an IPv4 lease with the specified parameters.
- ``lease6-del`` - deletes an IPv6 lease with the specified parameters; - ``lease6-del`` - deletes an IPv6 lease with the specified parameters.
- ``lease4-update`` - updates an IPv4 lease; - ``lease4-update`` - updates an IPv4 lease.
- ``lease6-update`` - updates an IPv6 lease; - ``lease6-update`` - updates an IPv6 lease.
- ``lease4-wipe`` - removes all leases from a specific IPv4 subnet or - ``lease4-wipe`` - removes all leases from a specific IPv4 subnet or
from all subnets; from all subnets.
- ``lease6-wipe`` - removes all leases from a specific IPv6 subnet or - ``lease6-wipe`` - removes all leases from a specific IPv6 subnet or
from all subnets; from all subnets.
The lease commands library is part of the open source code and is The lease commands library is part of the open source code and is
available to every Kea user. available to every Kea user.
All commands use JSON syntax and can be issued either using control All commands use JSON syntax and can be issued either using the control
channel (see `??? <#ctrl-channel>`__) or Control Agent (see channel (see :ref:`ctrl-channel`) or Control Agent (see
`??? <#kea-ctrl-agent>`__). :ref:`kea-ctrl-agent`).
The library can be loaded in the same way as other hook libraries, and The library can be loaded in the same way as other hook libraries, and
it does not take any parameters. It supports both DHCPv4 and DHCPv6 it does not take any parameters. It supports both DHCPv4 and DHCPv6
@ -83,19 +83,19 @@ servers.
:: ::
"Dhcp6": { "Dhcp6": {
"hooks-libraries": [ "hooks-libraries": [
{ {
"library": "/path/libdhcp_lease_cmds.so" "library": "/path/libdhcp_lease_cmds.so"
} }
... ...
] ]
} }
.. _command-lease4-add: .. _command-lease4-add:
lease4-add, lease6-add Commands The lease4-add, lease6-add Commands
------------------------------- -----------------------------------
The ``lease4-add`` and ``lease6-add`` commands allow for the creation of The ``lease4-add`` and ``lease6-add`` commands allow for the creation of
a new lease. Typically Kea creates a lease when it first sees a new a new lease. Typically Kea creates a lease when it first sees a new
@ -141,7 +141,7 @@ subnet. For example:
``lease6-add`` can also be used to add leases for IPv6 prefixes. In this ``lease6-add`` can also be used to add leases for IPv6 prefixes. In this
case there are three additional parameters that must be specified: case there are three additional parameters that must be specified:
subnet-id, type (set to value of "IA_PD"), and prefix length. The actual subnet-id, type (set to value of "IA_PD"), and prefix length. The actual
prefix is set using ip-address field. Note that Kea cannot guess prefix is set using the ip-address field. Note that Kea cannot guess
subnet-id values for prefixes; they must be specified explicitly. For subnet-id values for prefixes; they must be specified explicitly. For
example, to configure a lease for prefix 2001:db8:abcd::/48, the example, to configure a lease for prefix 2001:db8:abcd::/48, the
following command can be used: following command can be used:
@ -160,19 +160,19 @@ following command can be used:
} }
} }
The commands can take a number of additional optional parameters: The commands can take several additional optional parameters:
- ``valid-lft`` - specifies the lifetime of the lease, expressed in - ``valid-lft`` - specifies the lifetime of the lease, expressed in
seconds. If not specified, the value configured in the subnet related seconds. If not specified, the value configured in the subnet related
to the specified subnet-id is used. to the specified subnet-id is used.
- ``expire`` - creates a timestamp of the lease expiration time, - ``expire`` - creates a timestamp of the lease expiration time,
expressed in unix format (seconds since 1 Jan 1970). If not expressed in UNIX format (seconds since 1 Jan 1970). If not
specified, the default value is now + the lease lifetime (the value specified, the default value is now + the lease lifetime (the value
of valid-lft). of valid-lft).
- ``fqdn-fwd`` - specifies whether the lease should be marked as if a - ``fqdn-fwd`` - specifies whether the lease should be marked as if a
forward DNS update were conducted. Note this only affects the the forward DNS update were conducted. Note this only affects the
data stored in the lease database, and no DNS update will be data stored in the lease database, and no DNS update will be
performed. If configured, a DNS update to remove the A or AAAA performed. If configured, a DNS update to remove the A or AAAA
records will be conducted when the lease is removed due to expiration records will be conducted when the lease is removed due to expiration
@ -228,8 +228,8 @@ Here is an example of a more complex lease addition:
} }
} }
The command returns a status that indicates either a success (result 0) The command returns a status that indicates either success (result 0)
or a failure (result 1). A failed command always includes a text or failure (result 1). A failed command always includes a text
parameter that explains the cause of failure. For example: parameter that explains the cause of failure. For example:
:: ::
@ -244,14 +244,14 @@ Example failure:
.. _command-lease4-get: .. _command-lease4-get:
lease4-get, lease6-get Commands The lease4-get, lease6-get Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``lease4-get`` or ``lease6-get`` can be used to query the lease database ``lease4-get`` or ``lease6-get`` can be used to query the lease database
and retrieve existing leases. There are two types of parameters the and retrieve existing leases. There are two types of parameters the
``lease4-get`` command supports: (address) or (subnet-id, ``lease4-get`` command supports: (address) or (subnet-id,
identifier-type, identifier). There are also two types for identifier-type, identifier). There are also two types for
``lease6-get``: (address,type) or (subnet-id, identifier-type, ``lease6-get``: (address, type) or (subnet-id, identifier-type,
identifier, IAID, type). The first type of query is used when the identifier, IAID, type). The first type of query is used when the
address (either IPv4 or IPv6) is known, but the details of the lease are address (either IPv4 or IPv6) is known, but the details of the lease are
not; one common use case of this type of query is to find out whether a not; one common use case of this type of query is to find out whether a
@ -359,8 +359,8 @@ An example result returned when the host was found:
.. _command-lease4-get-all: .. _command-lease4-get-all:
lease4-get-all, lease6-get-all Commands The lease4-get-all, lease6-get-all Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``lease4-get-all`` and ``lease6-get-all`` are used to retrieve all IPv4 ``lease4-get-all`` and ``lease6-get-all`` are used to retrieve all IPv4
or IPv6 leases, or all leases for the specified set of subnets. All or IPv6 leases, or all leases for the specified set of subnets. All
@ -373,7 +373,7 @@ command, as in the following example:
"command": "lease4-get-all" "command": "lease4-get-all"
} }
If the arguments are provided, it is expected that they contain the If arguments are provided, it is expected that they contain the
"subnets" parameter, which is a list of subnet identifiers for which the "subnets" parameter, which is a list of subnet identifiers for which the
leases should be returned. For example, in order to retrieve all IPv6 leases should be returned. For example, in order to retrieve all IPv6
leases belonging to the subnets with identifiers 1, 2, 3, and 4: leases belonging to the subnets with identifiers 1, 2, 3, and 4:
@ -444,8 +444,8 @@ following format:
.. _lease-get-page-cmds: .. _lease-get-page-cmds:
lease4-get-page, lease6-get-page Commands The lease4-get-page, lease6-get-page Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``lease4-get-all`` and ``lease6-get-all`` commands may result in The ``lease4-get-all`` and ``lease6-get-all`` commands may result in
very large responses; generating such a response may consume CPU very large responses; generating such a response may consume CPU
@ -567,11 +567,11 @@ leases were found.
.. _command-lease4-del: .. _command-lease4-del:
lease4-del, lease6-del Commands The lease4-del, lease6-del Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``leaseX-del`` can be used to delete a lease from the lease database. ``leaseX-del`` can be used to delete a lease from the lease database.
There are two types of parameters this command supports, similar to There are two types of parameters this command supports, similar to the
leaseX-get commands: (address) for both v4 and v6, (subnet-id, leaseX-get commands: (address) for both v4 and v6, (subnet-id,
identifier-type, identifier) for v4, and (subnet-id, identifier-type, identifier-type, identifier) for v4, and (subnet-id, identifier-type,
identifier, type, IAID) for v6. The first type of query is used when the identifier, type, IAID) for v6. The first type of query is used when the
@ -579,7 +579,7 @@ address (either IPv4 or IPv6) is known, but the details of the lease are
not. One common use case is where an administrator wants a specified not. One common use case is where an administrator wants a specified
address to no longer be used. The second form of the command uses address to no longer be used. The second form of the command uses
identifiers. For maximum flexibility, this interface uses identifiers as identifiers. For maximum flexibility, this interface uses identifiers as
a pair of values: type and the actual identifier. The currently a pair of values: the type and the actual identifier. The currently
supported identifiers are "hw-address" (IPv4 only), "client-id" (IPv4 supported identifiers are "hw-address" (IPv4 only), "client-id" (IPv4
only), and "duid" (IPv6 only). only), and "duid" (IPv6 only).
@ -614,8 +614,8 @@ properly, but the object (a lease in this case) has not been found.
.. _command-lease4-update: .. _command-lease4-update:
lease4-update, lease6-update Commands The lease4-update, lease6-update Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``lease4-update`` and ``lease6-update`` commands can be used to The ``lease4-update`` and ``lease6-update`` commands can be used to
update existing leases. Since all lease database backends are indexed by update existing leases. Since all lease database backends are indexed by
@ -629,8 +629,8 @@ subnet-selection procedure. If specified, however, its value must match
the existing subnet. the existing subnet.
The optional boolean parameter "force-create" specifies whether the The optional boolean parameter "force-create" specifies whether the
lease should be created if it doesn't exist in the database. It defaults lease should be created if it does not exist in the database. It defaults
to false, which indicates that the lease is not created if it doesn't to false, which indicates that the lease is not created if it does not
exist. In such a case, an error is returned as a result of trying to exist. In such a case, an error is returned as a result of trying to
update a non-existing lease. If the "force-create" parameter is set to update a non-existing lease. If the "force-create" parameter is set to
true and the updated lease does not exist, the new lease is created as a true and the updated lease does not exist, the new lease is created as a
@ -669,13 +669,13 @@ An example of a command to update an IPv6 lease is:
.. _command-lease4-wipe: .. _command-lease4-wipe:
lease4-wipe, lease6-wipe Commands The lease4-wipe, lease6-wipe Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``lease4-wipe`` and ``lease6-wipe`` are designed to remove all leases ``lease4-wipe`` and ``lease6-wipe`` are designed to remove all leases
associated with a given subnet. This administrative task is expected to associated with a given subnet. This administrative task is expected to
be used when an existing subnet is being retired. Note that the leases be used when an existing subnet is being retired. Note that the leases
are not properly expired: no DNS updates are carried out, no log are not properly expired; no DNS updates are carried out, no log
messages are created, and hooks are not called for the leases being messages are created, and hooks are not called for the leases being
removed. removed.

1085
doc/guide/hooks.rst
View File

File diff suppressed because it is too large Load Diff

6
doc/guide/install.rst
View File

@ -1,3 +1,5 @@
.. _installation:
************ ************
Installation Installation
************ ************
@ -365,9 +367,9 @@ DHCP Database Installation and Configuration
Kea stores its leases in a lease database. The software has been written Kea stores its leases in a lease database. The software has been written
in a way that makes it possible to choose which database product should in a way that makes it possible to choose which database product should
be used to store the lease information. Kea supports four be used to store the lease information. Kea supports four
database backends: MySQL, PostgreSQL, Cassandra, and Memfile. To limit database backends: MySQL, PostgreSQL, Cassandra, and memfile. To limit
external dependencies, MySQL, PostgreSQL, and Cassandra support are external dependencies, MySQL, PostgreSQL, and Cassandra support are
disabled by default and only Memfile is available. Support for the disabled by default and only memfile is available. Support for the
optional external database backend must be explicitly included when Kea optional external database backend must be explicitly included when Kea
is built. This section covers the building of Kea with one of the is built. This section covers the building of Kea with one of the
optional backends and the creation of the lease database. optional backends and the creation of the lease database.

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

@ -14,7 +14,7 @@ Kea, can be found in ISC's `Knowledgebase <https://kb.isc.org/docs/kea-administr
.. toctree:: .. toctree::
:numbered: :numbered:
:maxdepth: 3 :maxdepth: 5
intro intro
quickstart quickstart