mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-22 09:57:41 +00:00
Converting from docbook to sphinx: fixing links, editing grammar and style as needed
This commit is contained in:
Suzanne Goldlust
Michal Nowikowski
parent
edfeb3f498
commit
0228c239c1
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -141,19 +141,19 @@ command, which includes the metadata:
|
||||
|
||||
|
||||
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``
|
||||
@ -174,8 +174,8 @@ 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.
|
||||
@ -197,10 +197,10 @@ 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.:
|
||||
|
||||
::
|
||||
|
||||
@ -278,22 +278,22 @@ Finally, the boolean value:
|
||||
|
||||
.. _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:
|
||||
|
||||
::
|
||||
|
||||
@ -315,22 +315,22 @@ 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.
|
||||
|
||||
@ -354,20 +354,20 @@ 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.
|
||||
|
||||
@ -394,13 +394,13 @@ 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
|
||||
@ -449,8 +449,8 @@ 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
|
||||
@ -495,17 +495,17 @@ 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":
|
||||
@ -530,23 +530,23 @@ 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:
|
||||
|
||||
::
|
||||
|
||||
@ -573,8 +573,8 @@ 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.
|
||||
@ -598,18 +598,18 @@ 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:
|
||||
|
||||
@ -633,22 +633,22 @@ 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:
|
||||
|
||||
::
|
||||
|
||||
@ -670,7 +670,7 @@ 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:
|
||||
|
||||
::
|
||||
@ -691,12 +691,12 @@ 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:
|
||||
|
||||
::
|
||||
|
||||
@ -717,8 +717,8 @@ 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
|
||||
@ -743,8 +743,8 @@ 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.
|
||||
@ -769,8 +769,8 @@ 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
|
||||
@ -795,31 +795,31 @@ 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:
|
||||
|
||||
@ -847,12 +847,12 @@ 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.
|
||||
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 (not associated with any shared
|
||||
network), the ``shared-network-name`` must be explicitly set to
|
||||
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``:
|
||||
|
||||
::
|
||||
@ -877,14 +877,14 @@ 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
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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:
|
||||
|
||||
::
|
||||
|
||||
@ -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
|
||||
@ -94,8 +94,8 @@ servers.
|
||||
|
||||
.. _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
1085
doc/guide/hooks.rst
File diff suppressed because it is too large
Load Diff
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user