mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-22 09:57:41 +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
@ -538,7 +538,7 @@ Year 2038 Issue
The lease expiration time is stored in the SQL database for each lease
as a timestamp value. Kea developers observed that the MySQL database
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
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

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
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.
@ -49,7 +49,7 @@ The classification process is conducted in several steps:
2. Vendor class options are processed.
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
configuration; the boolean expression is evaluated and, if it
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.
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
in the configuration; the boolean expression is evaluated and, if it
returns true ("match"), the incoming packet is associated with the
@ -128,10 +128,10 @@ value is obtained is unspecified.
.. _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
incoming DHCPv4 packet includes the vendor class identifier option (60)
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,
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.
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\_
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.
.. _classification-using-expressions:
@ -186,7 +186,7 @@ in the operator returning an empty string.
Dependencies between classes are also checked. For instance, forward
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.
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
class "foobar". To avoid dependency loops, the configuration file
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",
"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
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
and it specifies which storage for leases the server should use. The
value of ``"memfile"`` indicates that the file should be used as the
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
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
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
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
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
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
and it specifies which storage for leases the server should use. The
value of ``"memfile"`` indicates that the file should be used as the
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
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
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
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
indirectly) and not only-if-required is evaluated.
@ -4411,7 +4411,7 @@ configuration:
This very simple configuration provides DNS server information to
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.
.. _dhcp6-rfc7550:

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

@ -3,22 +3,22 @@
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
library must be used in conjuction with the available CB hooks libraries
implementing the common APIs to create, read, update and delete (CRUD)
library must be used in conjunction with the available CB hooks libraries
implementing the common APIs to create, read, update, and delete (CRUD)
the configuration information in the respective databases. For example:
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
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.
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.
**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.
Commands Structure
@ -26,23 +26,23 @@ Commands Structure
There are 5 types of commands supported by this library:
- ``del`` - delete selected object from the database, e.g.
``remote-global-parameter4-del``
- ``del`` - delete the selected object from the database, e.g.
``remote-global-parameter4-del``.
- ``get`` - fetch selected object from the database, e.g.
``remote-subnet4-get``,
- ``get`` - fetch the selected object from the database, e.g.
``remote-subnet4-get``.
- ``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,
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
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:
::
@ -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
fetch the list of subnets from. All parameters in the ``remote`` are
optional. The ``port`` parameter can be only specified in conjuction
with the ``host``. If no parameters in the ``remote`` parameter are to
fetch the list of subnets from. All parameters in the ``remote`` argument are
optional. The ``port`` parameter can be only specified in conjunction
with the ``host``. If no options in the ``remote`` parameter are to
be specified, the parameter should be omitted. In this case, the server
will use the first backend listed in the ``config-control`` map within
the configuration of the server receiving the command.
**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
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
``remote`` parameter may be omitted in the commands because the
cb_cmds hooks library will use by default the sole backend.
``remote`` parameter may be omitted in the commands, because the
cb_cmds hooks library will use the sole backend by default.
.. _cb-cmds-dhcp:
@ -83,23 +83,23 @@ Control Commands for DHCP Servers
This section describes and gives some examples of the control commands
implemented by the ``cb_cmds`` hooks library, to manage the
configuration information of the DHCPv4 and DHCPv6 servers. Many of the
commands are almost identical between DHCPv4 and DHCPv6, i.e. only
differ by the command name. Other commands slightly differ by the
structure of the inserted data, e.g. the structure of the IPv4 subnet
information is different than the structure of the IPv6 subnet.
Nevertheless, they still share the structure of the command arguments
commands are almost identical between DHCPv4 and DHCPv6; they only
differ by the command name. Other commands differ slightly by the
structure of the inserted data; for example, the structure of the IPv4 subnet
information is different than that of the IPv6 subnet.
Nevertheless, they still share the structure of their command arguments
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
DHCPv6 variants of the particular command we sometimes use the following
notation - the ``remote-subnet[46]-set`` is the wildcard name for the
DHCPv6 variants of the particular command, we sometimes use the following
notation: the ``remote-subnet[46]-set`` is the wildcard name for the
two commands: ``remote-subnet4-set`` and ``remote-subnet6-set``.
In addition, whenever the text in the subsequent sections refers to a
DHCP command or DHCP parameter, it refers to both DHCPv4 and DHCPv6
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.
.. _cb-cmds-metadata:
@ -108,13 +108,13 @@ Metadata
~~~~~~~~
The typical response to the ``get`` or ``list`` command includes a list
of returned objects (e.g. subnets) and each such object contains the
``metadata`` map with some database specific information describing this
of returned objects (e.g. subnets), and each such object contains the
``metadata`` map with some database-specific information describing this
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
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
beta release.
@ -138,22 +138,22 @@ command, which includes the metadata:
"count": 1
}
}
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
message created during the last modification etc.
message created during the last modification, etc.
.. _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
configuration database. When the parameter is deleted from the database
These commands are used to delete a global DHCP parameter from the
configuration database. When the parameter is deleted from the database,
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 following command attempts to delete the DHCPv4 ``renew-timer``
@ -170,12 +170,12 @@ parameter from the database:
}
}
}
.. _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
configuration database.
@ -194,13 +194,13 @@ parameter:
}
}
}
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.
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
}
}
The example response for the integer value is:
@ -236,7 +236,7 @@ The example response for the integer value is:
"count": 1
}
}
The real value:
@ -255,7 +255,7 @@ The real value:
"count": 1
}
}
Finally, the boolean value:
@ -274,26 +274,26 @@ Finally, the boolean value:
"count": 1
}
}
.. _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
database. They include no arguments besides the optional ``remote`` map.
.. _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
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
within a single command, each having one of the four types: a string,
integer, real and boolean. For example:
within a single command, each having one of the four types: string,
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
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
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
which of the parameters have been stored/updated successfully and which
failed.
have failed.
.. _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
the database. The optional parameter ``subnets-action`` determines
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
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
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:
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
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
returned together with the shared network.
@ -390,17 +390,17 @@ with the full information about the subnets belonging to it:
}
}
}
.. _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
particular database. The returned information about each shared network
merely contains the shared network name and the metadata. In order to
fetch the detailed information about the selected shared network, use
merely contains the shared network name and the metadata. To
fetch detailed information about the selected shared network, use
the ``remote-network[46]-get`` command.
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:
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
is the same as in the Kea configuration file (see
`??? <#shared-network4>`__ and `??? <#shared-network6>`__ for details),
except that it is not allowed to specify subnets along with the shared
network information. Including the ``subnet4`` or ``subnet6`` parameter
:ref:`shared-network4` and :ref:`shared-network6` for details),
except that specifying subnets along with the shared
network information is not allowed. Including the ``subnet4`` or ``subnet6`` parameter
within the shared network information will result in an error.
These commands are intended to be used for managing the shared network
specific information and DHCP options. In order to associate and
disassociate the subnets with the shared networks the
These commands are intended to be used for managing the shared
network-specific information and DHCP options. In order to associate and
disassociate the subnets with the shared networks, the
``remote-subnet[46]-set`` commands should be used.
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
"unspecified" in the database. The DHCP server will use the global
values for unspecified parameters or, if the global values are not
@ -458,18 +458,18 @@ specified, the default values will be used.
**Note**
Same as for other "set" commands, this command replaces the entire
information about the given shared network in the database if the
As with other "set" commands, this command replaces all the
information about the given shared network in the database, if the
shared network already exists. Therefore, when sending this command,
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
prior to sending the command.
.. _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
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
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:
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
the database. The option definition is identified by the option code and
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
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:
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
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:
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
existing option definition in the database. The structure of the option
definition information is the same as in the Kea configuration file (see
`??? <#dhcp4-custom-options>`__ and `??? <#dhcp6-custom-options>`__).
The following command creates the DHCPv4 option definition in the top
level "dhcp4" option space:
:ref:`dhcp4-custom-options` and :ref:`dhcp6-custom-options`).
The following command creates the DHCPv4 option definition in the
top-level "dhcp4" option space:
::
@ -569,12 +569,12 @@ level "dhcp4" option space:
}
}
}
.. _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
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.
.. _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.
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
"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:
@ -629,26 +629,26 @@ The following command retrieves the IPv6 "DNS Servers" (code 23) option:
}
}
}
.. _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
configuration database. It takes no arguments except the optional
configuration database. They take no arguments except the optional
``remote`` map.
.. _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
option in the database. The structure of the option information is the
same as in the Kea configuration file (see `??? <#dhcp4-std-options>`__
and see `??? <#dhcp4-std-options>`__). For example:
same as in the Kea configuration file (see :ref:`dhcp4-std-options`
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
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:
::
@ -687,16 +687,16 @@ instead of the name. For example:
]
}
}
.. _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
subnet from the database. It uses subnet ID to identify the subnet. For
example, in order to delete the IPv4 subnet with ID of 5:
subnet from the database. It uses the subnet ID to identify the subnet. For
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:
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
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:
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
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:
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
subnet from the database. It uses a subnet prefix to identify the
@ -791,35 +791,35 @@ subnet. For example:
}
}
}
.. _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
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,
prefix and associated shared network name. In order to retrieve full
information about the selected subnet use the
``remote-subnet[46]-get-by-id`` or ``remote-subnet[46]-get-by-prefix``.
prefix, and associated shared network name. To retrieve full
information about the selected subnet, use the
``remote-subnet[46]-get-by-id`` or ``remote-subnet[46]-get-by-prefix`` command.
.. _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
an existing subnet in the database. Setting the subnet also associates
or disassociates the subnet with a shared network.
The structure of the subnet information is similar to the structure used
in the configuration file (see `??? <#dhcp4-configuration>`__ and
`??? <#dhcp6-configuration>`__). The subnet information conveyed in the
``remote-subnet[46]-set`` must include additional parameter
``shared-network-name`` which denotes whether the subnet belongs to a
shared network or not.
in the configuration file (see :ref:`dhcp4-configuration` and
:ref:`dhcp6-configuration`). The subnet information conveyed in the
``remote-subnet[46]-set`` command must include the additional parameter
``shared-network-name``, which denotes whether the subnet belongs to a
shared network.
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
network), the ``shared-network-name`` must be explicitly set to
It creates the subnet and associates it with the "level3" shared
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``:
::
@ -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
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
``remote-subnet4-set`` command.
**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
subnet information is already present. Therefore, when sending this
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**
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.
The Class Commands hooks library is available to premium Kea customers
only.
The Class Commands hooks library is currently available only to ISC
customers with a paid support contract.
.. _command-class-add:
class-add Command
-----------------
The class-add Command
---------------------
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
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.
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:
class-update Command
--------------------
The class-update Command
------------------------
The ``class-update`` command updates an existing client class in the
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
exist. The ``class-add`` command must be used instead to create the new
client class.
@ -110,10 +110,10 @@ the new name will be added at the end of the list of configured classes.
.. _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
is not removed if there are other classes depending on it; to remove
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:
class-list Command
------------------
The class-list Command
----------------------
``class-list`` is used to retrieve a list of all client classes. This
command includes no arguments:
@ -183,8 +183,8 @@ merely class names. To retrieve full class information, the
.. _command-class-get:
class-get Command
-----------------
The class-get Command
---------------------
``class-get`` is used to retrieve detailed information about a specified
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**
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.
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
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
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
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
is unsuccessful, the DHCP query is dropped and the response is not
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.
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
requests. The secondary or standby server receives lease updates from
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
responding to all DHCP queries.
In the configurations described above, the primary, secondary, and
standby are referred to as "active" servers, because they receive lease
In the configurations described above, the primary and secondary/standby
are referred to as "active" servers, because they receive lease
updates and can automatically react to the partner's failures by
responding to the DHCP queries which would normally be handled by the
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
load balancing and hot standby setup, in addition to the active servers.
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.
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
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.
The servers share lease information via lease updates and during
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;
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
@ -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
message is issued. The administrator may correct this problem by
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
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
server doesn't respond to the ``ha-heartbeat`` command within the
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
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.
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.
When in this state, the server issues the ``dhcp-disable`` command to
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
syncing partner was unable to re-enable the service. If 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
the "terminated" state, it will remain in this state until it is
restarted. The administrator must correct the issue which caused this
situation prior to restarting the server (e.g. synchronize clocks).
Otherwise, the server will return to the "terminated" state once it
situation prior to restarting the server (e.g. synchronize the clocks);
otherwise, the server will return to the "terminated" state once it
finds that the issue persists.
- ``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
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
standby server, and ``server3`` for the backup server. In real life any
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
load-balanced to ``server1`` belong to the ``HA_server1`` scope and the
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``
values. When the server detects that communication is interrupted, it
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
value of this parameter is 60000.
value of this parameter is 60000 ms.
- ``max-ack-delay`` - is one of the parameters controlling partner
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
still operating. On the other hand, selecting too high a value may
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
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.
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
different address pools. Introducing HA in the load-balancing mode
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
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.
::
@ -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
assigned addresses from different pools. The ``HA_server1`` and
``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
load-balancing algorithm. ``phones_*`` and ``laptop_*`` evaluate to
"true" when the query belongs to a given combination of other classes,
e.g. ``HA_server1`` and ``phones``. The pool is selected accordingly as
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.
.. _ha-hot-standby-config:
@ -750,8 +750,7 @@ hot-standby configuration:
}
This configuration is very similar to the load-balancing configuration
described in `Load-Balancing
Configuration <#ha-load-balancing-config>`__, with a few notable
described in :ref:`ha-load-balancing-config`, with a few notable
differences.
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
information about the allocated leases is performed using some other
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
Kea administrators to provide redundancy.
@ -859,11 +858,11 @@ Controlling Lease-Page Size Limit
An HA-enabled server initiates synchronization of the lease database
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
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
configuration. Increasing the page size decreases the number of lease
to one of these commands) can be controlled via configuration of the HA hooks
library. Increasing the page size decreases the number of lease
queries sent to the partner server, but it causes the partner server to
generate larger responses, which lengthens transmission time as well as
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
leases from its partner, which yields a large response over the RESTful
interface. The server receives leases using the paging mechanism
described in `Controlling Lease-Page Size
Limit <#ha-syncing-page-limit>`__. Before the page of leases is fetched,
described in :ref:`ha-syncing-page-limit`. Before the page of leases is fetched,
the synchronizing server sends a ``dhcp-disable`` command to disable the
DHCP service on the partner server. If the service is already 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
of leases takes longer than the specified time, the synchronizing server
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
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
@ -960,7 +958,7 @@ Pausing HA State Machine
------------------------
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
into account the partner server's state. In some states the server
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
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
HA state machine in a selected state to perform some additional
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
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
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
and remain in this state while leases are being added. In particular,
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
should be paused upon the first transition to the ``waiting`` state;
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
state, which instructs the server never to pause the state machine.
In order to "unpause" the state machine, the ``ha-continue`` command
must be sent to the paused server. This command does not take any
arguments. See `Control Commands for High
Availability <#ha-control-commands>`__ for details about commands
arguments. See :ref:`ha-control-commands` for details about commands
specific to the HA hooks library.
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
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
states; however, it is not practical for the ``backup`` and
``terminated`` states because the server never transitions out of these
@ -1138,9 +1135,9 @@ states anyway.
Control Agent Configuration
---------------------------
`??? <#kea-ctrl-agent>`__ describes in detail the Kea daemon, which
provides a RESTful interface to control Kea servers. The same
functionality is used by the High Availability hook library to establish
:ref:`kea-ctrl-agent` describes in detail the Kea daemon, which
provides a RESTful interface to control the Kea servers. The same
functionality is used by the High Availability hooks library to establish
communication between the HA peers. Therefore, the HA library requires
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
@ -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.
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
failover function automatically. Thus, in order to use the backup server
if both active servers are down. The backup server does not perform
failover function automatically; thus, in order to use the backup server
to respond to DHCP queries, the server administrator must enable this
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.
.. _command-ha-sync:
ha-sync Command
~~~~~~~~~~~~~~~
The ha-sync Command
~~~~~~~~~~~~~~~~~~~
The ``ha-sync`` command instructs the server to synchronize its local
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
synchronization is unidirectional; only the database on the server to
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
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
specifies the maximum duration (in seconds) for which the DHCP service
should be disabled. If the DHCP service is successfully disabled, the
synchronizing server will fetch leases from the remote server by issuing
one or more ``lease4-get-page`` commands. When the lease- database
synchronizing server fetches leases from the remote server by issuing
one or more ``lease4-get-page`` commands. When the lease-database
synchronization is complete, the synchronizing server sends the
``dhcp-enable`` command to the peer to re-enable its DHCP service.
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
synchronization is still in progress. If the DHCP server subsequently
allocates any leases during the synchronization, those new (or updated)
@ -1244,13 +1241,12 @@ database inconsistencies.
.. _command-ha-scopes:
ha-scopes Command
~~~~~~~~~~~~~~~~~
The ha-scopes Command
~~~~~~~~~~~~~~~~~~~~~
This command allows modification of the HA scopes that the server is
serving. Consult `Load-Balancing
Configuration <#ha-load-balancing-config>`__ and `Hot-Standby
Configuration <#ha-hot-standby-config>`__ to learn what scopes are
serving. Consult :ref:`ha-load-balancing-config` and
:ref:`ha-hot-standby-config` to learn what scopes are
available for different HA modes of operation. The ``ha-scopes`` command
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
``HA_server1`` and ``HA_server2`` scopes. In order to disable all scopes
This command configures the server to handle traffic from both the
``HA_server1`` and ``HA_server2`` scopes. To disable all scopes
specify an empty list:
::
@ -1280,12 +1276,11 @@ specify an empty list:
.. _command-ha-continue:
ha-continue Command
~~~~~~~~~~~~~~~~~~~
The ha-continue Command
~~~~~~~~~~~~~~~~~~~~~~~
This command is used to resume the operation of the paused HA state
machine, as described in `Pausing HA State
Machine <#ha-pause-state-machine>`__. It takes no arguments, so the
machine, as described in :ref:`ha-pause-state-machine`. It takes no arguments, so the
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
leases. Kea provides a way to store lease information in several
backends (memfile, MySQL, PostgreSQL and Cassandra), and this library
provides a interface that can manipulate leases in a unified, safe way.
backends (memfile, MySQL, PostgreSQL, and Cassandra), and this library
provides an interface that can manipulate leases in a unified, safe way.
In particular, it allows things previously impossible: lease
manipulation in memfile while Kea is running, sanity check changes,
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
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
@ -25,57 +25,57 @@ leases.
There are many use cases where an administrative command may be useful;
for example, during migration between servers or different vendors, when
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
and monitoring tasks. They can also act as preparatory steps for lease
updates and removals.
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
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
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
the specified subnets;
the specified subnets.
- ``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
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
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
from all subnets;
from all subnets.
- ``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
available to every Kea user.
All commands use JSON syntax and can be issued either using control
channel (see `??? <#ctrl-channel>`__) or Control Agent (see
`??? <#kea-ctrl-agent>`__).
All commands use JSON syntax and can be issued either using the control
channel (see :ref:`ctrl-channel`) or Control Agent (see
:ref:`kea-ctrl-agent`).
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
@ -83,19 +83,19 @@ servers.
::
"Dhcp6": {
"Dhcp6": {
"hooks-libraries": [
{
"library": "/path/libdhcp_lease_cmds.so"
}
...
]
]
}
.. _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
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
case there are three additional parameters that must be specified:
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
example, to configure a lease for prefix 2001:db8:abcd::/48, the
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
seconds. If not specified, the value configured in the subnet related
to the specified subnet-id is used.
- ``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
of valid-lft).
- ``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
performed. If configured, a DNS update to remove the A or AAAA
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)
or a failure (result 1). A failed command always includes a text
The command returns a status that indicates either success (result 0)
or failure (result 1). A failed command always includes a text
parameter that explains the cause of failure. For example:
::
@ -244,14 +244,14 @@ Example failure:
.. _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
and retrieve existing leases. There are two types of parameters the
``lease4-get`` command supports: (address) or (subnet-id,
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
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
@ -359,8 +359,8 @@ An example result returned when the host was found:
.. _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
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"
}
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
leases should be returned. For example, in order to retrieve all IPv6
leases belonging to the subnets with identifiers 1, 2, 3, and 4:
@ -444,8 +444,8 @@ following format:
.. _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
very large responses; generating such a response may consume CPU
@ -567,11 +567,11 @@ leases were found.
.. _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.
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,
identifier-type, identifier) for v4, and (subnet-id, identifier-type,
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
address to no longer be used. The second form of the command uses
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
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:
lease4-update, lease6-update Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The lease4-update, lease6-update Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``lease4-update`` and ``lease6-update`` commands can be used to
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 optional boolean parameter "force-create" specifies whether the
lease should be created if it doesn't exist in the database. It defaults
to false, which indicates that the lease is not created if it doesn't
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 does not
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
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:
lease4-wipe, lease6-wipe Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The lease4-wipe, lease6-wipe Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``lease4-wipe`` and ``lease6-wipe`` are designed to remove all leases
associated with a given subnet. This administrative task is expected to
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
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
************
@ -365,9 +367,9 @@ DHCP Database Installation and Configuration
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
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
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
is built. This section covers the building of Kea with one of the
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::
:numbered:
:maxdepth: 3
:maxdepth: 5
intro
quickstart