Backend versions are specified in a major.minor format. The minor number
is increased when there are backwards-compatible changes introduced; for
example, the addition of a new index. It is desirable but not mandatory
-to apply such a change; you can run an older backend version if you want
-to. (Although, in the example given, running without the new index may
+to apply such a change; running an older backend version is possible.
+(Although, in the example given, running without the new index may
introduce a performance penalty.) On the other hand, the
major number is increased when an incompatible change is introduced; for
-example, an extra column is added to a table. If you try to run Kea on a
+example, an extra column is added to a table. If Kea is run on a
backend that is too old (as signified by a mismatched backend major
version number), Kea will refuse to run; administrative action will be
required to upgrade the backend.
- ``cql`` — Information is stored in an Apache Cassandra database.
-Additional parameters may be needed, depending on your setup and
+Additional parameters may be needed, depending on the setup and
specific operation: username, password, and database name or the
directory where specific files are located. See the appropriate manual
page for details (``man 8 kea-admin``).
The following table presents the capabilities of available backends.
Please refer to the specific sections dedicated to each backend to
better understand their capabilities and limitations. Choosing the right
-backend may be essential for the success of your deployment.
+backend may be essential for the success of the deployment.
.. table:: List of available backends
need arise. When upgrading, any values not present in the original lease
files will be assigned appropriate default values. When downgrading, any
data present in the files but not in the server's schema will be
-dropped. If you wish to convert the files manually prior to starting the
-servers, you may do so by running the LFC process yourself. See
-:ref:`kea-lfc` for more information.
+dropped. To convert the files manually prior to starting the
+servers, run the LFC process. See :ref:`kea-lfc` for more information.
.. _mysql-database:
MySQL is able to store leases, host reservations, options defined on a
per-host basis, and a subset of the server configuration parameters
(serving as a configuration backend). This section can be safely ignored
-if you choose to store the data in other backends.
+if the data will be stored in other backends.
.. _mysql-database-create:
First-Time Creation of the MySQL Database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you are setting the MySQL database for the first time, you need to
-create the database area within MySQL and set up the MySQL user ID under
-which Kea will access the database. This needs to be done manually;
-``kea-admin`` cannot do this for you.
+When setting up the MySQL database for the first time, the
+database area must be created within MySQL, and the MySQL user ID under
+which Kea will access the database must be set up. This needs to be done manually,
+rather than via ``kea-admin``.
To create the database:
mysql> CREATE DATABASE database-name;
- (database-name is the name you have chosen for the database.)
+ (database-name is the name chosen for the database.)
3. Create the user under which Kea will access the database (and give it
a password), then grant it access to the database tables:
mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password';
mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost';
- (user-name and password are the user ID and password you are using to
+ (user-name and password are the user ID and password being used to
allow Kea access to the MySQL instance. All apostrophes in the
command lines above are required.)
-4. At this point, you may elect to create the database tables.
- (Alternatively, you can exit MySQL and create the tables using the
+4. At this point, administrators may elect to create the database tables.
+ (Alternatively, the tables can be created by exiting MySQL and using the
``kea-admin`` tool, as explained below.) To do this:
::
mysql> CONNECT database-name;
mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql
- (path-to-kea is the location where you installed Kea.)
+ (path-to-kea is the location where Kea is installed.)
5. Exit MySQL:
Bye
$
-If you elected not to create the tables in Step 4, you can do so now by
-running the ``kea-admin`` tool:
+If the tables were not created in Step 4, run the ``kea-admin`` tool
+to create them now:
::
$ kea-admin lease-init mysql -u database-user -p database-password -n database-name
-Do not do this if you did create the tables in Step 4. ``kea-admin``
+Do not do this if the tables were created in Step 4. ``kea-admin``
implements rudimentary checks; it will refuse to initialize a database
-that contains any existing tables. If you want to start from scratch,
-you must remove all data manually. (This process is a manual operation
+that contains any existing tables. To start from scratch,
+all must be removed data manually. (This process is a manual operation
on purpose, to avoid possibly irretrievable mistakes by ``kea-admin``.)
.. _mysql-upgrade:
----------
PostgreSQL is able to store leases, host reservations, and options
-defined on a per-host basis. This step can be safely ignored if you are
-using other database backends.
+defined on a per-host basis. This step can be safely ignored if
+other database backends will be used.
.. _pgsql-database-create:
CREATE DATABASE
postgres=#
- (database-name is the name you have chosen for the database.)
+ (database-name is the name chosen for the database.)
3. Create the user under which Kea will access the database (and give it
a password), then grant it access to the database:
Bye
$
-5. At this point you are ready to create the database tables. This can
- be done using the ``kea-admin`` tool as explained in the next section
+5. At this point, create the database tables either
+ using the ``kea-admin`` tool, as explained in the next section
(recommended), or manually. To create the tables manually, enter the
- following command. Note that PostgreSQL will prompt you to enter the
- new user's password you specified in Step 3. When the command
- completes, you will be returned to the shell prompt. You should see
- output similar to the following:
+ following command. Note that PostgreSQL will prompt the administrator to enter the
+ new user's password that was specified in Step 3. When the command
+ completes, Kea will return to the shell prompt. The
+ output should be similar to the following:
::
COMMIT
$
- (path-to-kea is the location where you installed Kea.)
+ (path-to-kea is the location where Kea is installed.)
- If instead you encounter an error like:
+ If instead an error is encountered, such as:
::
psql: FATAL: no pg_hba.conf entry for host "[local]", user "user-name", database "database-name", SSL off
- ... you will need to alter the PostgreSQL configuration. Kea uses
+ ... the PostgreSQL configuration will need to be altered. Kea uses
password authentication when connecting to the database and must have
the appropriate entries added to PostgreSQL's pg_hba.conf file. This
- file is normally located in the primary data directory for your
- PostgreSQL server. The precise path may vary depending on your
+ file is normally located in the primary data directory for the
+ PostgreSQL server. The precise path may vary depending on the
operating system and version, but the default location for PostgreSQL
9.3 on Centos 6.5 is: ``/var/lib/pgsql/9.3/data/pg_hba.conf``.
These edits are primarily intended as a starting point, and are not a
definitive reference on PostgreSQL administration or database
- security. Please consult your PostgreSQL user manual before making
- these changes, as they may expose other databases that you run. It
+ security. Please consult the PostgreSQL user manual before making
+ these changes, as they may expose other databases that are running. It
may be necessary to restart PostgreSQL in order for the changes to
take effect.
Initialize the PostgreSQL Database Using kea-admin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you elected not to create the tables manually, you can do so now by
+If the tables were not created manually, do so now by
running the ``kea-admin`` tool:
::
$ kea-admin lease-init pgsql -u database-user -p database-password -n database-name
-Do not do this if you already created the tables manually. ``kea-admin``
+Do not do this if the tables were already created manually. ``kea-admin``
implements rudimentary checks; it will refuse to initialize a database
-that contains any existing tables. If you want to start from scratch,
-you must remove all data manually. (This process is a manual operation
+that contains any existing tables. To start from scratch,
+all data must be removed manually. (This process is a manual operation
on purpose, to avoid possibly irretrievable mistakes by ``kea-admin``.)
.. _pgsql-upgrade:
is able to store leases, host reservations, and options defined on a
per-host basis.
-Cassandra must be properly set up if you want Kea to store information
-in it. This section can be safely ignored if you choose to store the
-data in other backends.
+Cassandra must be properly set up if Kea is to store information
+in it. This section can be safely ignored if the
+data will be stored in other backends.
.. _cql-database-create:
First-Time Creation of the Cassandra Database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you are setting up the Cassandra database for the first time, you
-need to create the keyspace area within it. This needs to be done
-manually; ``kea-admin`` cannot do this for you.
+When setting up the Cassandra database for the first time,
+the keyspace area within it must be created. This needs to be done
+manually; it cannot be performed by ``kea-admin``.
To create the database:
cql> CREATE KEYSPACE keyspace-name WITH replication = {'class' : 'SimpleStrategy','replication_factor' : 1};
- (keyspace-name is the name you have chosen for the keyspace)
+ (keyspace-name is the name chosen for the keyspace.)
-4. At this point, you may elect to create the database tables.
- (Alternatively, you can exit Cassandra and create the tables using
+4. At this point, the database tables can be created.
+ (It is also possible to exit Cassandra and create the tables using
the ``kea-admin`` tool, as explained below.) To do this:
::
cqslh -k keyspace-name -f path-to-kea/share/kea/scripts/cql/dhcpdb_create.cql
- (path-to-kea is the location where you installed Kea)
+ (path-to-kea is the location where Kea is installed.)
-If you elected not to create the tables in Step 4, you can do so now by
+If the tables were not created in Step 4, do so now by
running the ``kea-admin`` tool:
::
$ kea-admin lease-init cql -n database-name
-Do not do this if you did create the tables in Step 4. ``kea-admin``
+Do not do this if the tables were created in Step 4. ``kea-admin``
implements rudimentary checks; it will refuse to initialize a database
-that contains any existing tables. If you want to start from scratch,
-you must remove all data manually. (This process is a manual operation
+that contains any existing tables. To start from scratch,
+all data must be removed manually. (This process is a manual operation
on purpose, to avoid possibly irretrievable mistakes by ``kea-admin``.)
.. _cql-upgrade:
.. _agent-overview:
-Overview
-========
+Overview of the Kea Control Agent
+=================================
The Kea Control Agent (CA) is a daemon which exposes a RESTful control
interface for managing Kea servers. The daemon can receive control
Hooks libraries can be loaded by the Control Agent in the same way as
they are loaded by the DHCPv4 and DHCPv6 servers. The CA currently
-supports one hook point - 'control_command_receive' - which makes it
+supports one hook point - "control_command_receive" - which makes it
possible to delegate processing of some commands to the hooks library.
The ``hooks-libraries`` list contains the list of hooks libraries that
should be loaded by the CA, along with their configuration information
# openssl x509 -req -days 365 -in kea-client.csr -CA ca.crt \
# -CAkey ca.key -set_serial 01 -out kea-client.crt
#
- # Note that the 'common name' value used when generating the client
+ # Note that the "common name" value used when generating the client
# and the server certificates must differ from the value used
# for the CA certificate.
#
# The client certificate must be deployed on the client system.
- # In order to test the proxy configuration with 'curl' run a
+ # In order to test the proxy configuration with "curl", run a
# command similar to the following:
#
# curl -k --key kea-client.key --cert kea-client.crt -X POST \
``subnet6-add`` , ``subnet6-del`` , ``subnet6-get`` , ``subnet6-list`` ,
``subnet6-update`` , ``version-get`` .
-Commands supported by kea-ctrl-agent daemon: ``build-report`` ,
+Commands supported by the kea-ctrl-agent daemon: ``build-report`` ,
``config-get`` , ``config-reload`` , ``config-set`` , ``config-test`` ,
``config-write`` , ``list-commands`` , ``shutdown`` , ``version-get`` .
-Commands supported by kea-dhcp-ddns daemon: ``build-report`` ,
+Commands supported by the kea-dhcp-ddns daemon: ``build-report`` ,
``config-get`` , ``config-reload`` , ``config-set`` , ``config-test`` ,
``config-write`` , ``list-commands`` , ``shutdown`` , ``version-get`` .
-Commands supported by kea-dhcp4 daemon: ``build-report`` ,
+Commands supported by the kea-dhcp4 daemon: ``build-report`` ,
``cache-clear`` , ``cache-get`` , ``cache-get-by-id`` , ``cache-insert``
, ``cache-load`` , ``cache-remove`` , ``cache-size`` , ``cache-write`` ,
``class-add`` , ``class-del`` , ``class-get`` , ``class-list`` ,
``subnet4-del`` , ``subnet4-get`` , ``subnet4-list`` ,
``subnet4-update`` , ``version-get`` .
-Commands supported by kea-dhcp6 daemon: ``build-report`` ,
+Commands supported by the kea-dhcp6 daemon: ``build-report`` ,
``cache-clear`` , ``cache-get`` , ``cache-get-by-id`` , ``cache-insert``
, ``cache-load`` , ``cache-remove`` , ``cache-size`` , ``cache-write`` ,
``class-add`` , ``class-del`` , ``class-get`` , ``class-list`` ,
``subnet6-del`` , ``subnet6-get`` , ``subnet6-list`` ,
``subnet6-update`` , ``version-get`` .
-Commands supported by cb_cmds hook library:
+.. _commands-cb_cmds-lib:
+
+Commands supported by the Configuration Backend Commands (cb_cmds) hooks library:
``remote-global-parameter4-del`` , ``remote-global-parameter4-get`` ,
``remote-global-parameter4-get-all`` , ``remote-global-parameter4-set``
, ``remote-global-parameter6-del`` , ``remote-global-parameter6-get`` ,
``remote-subnet6-get-by-id`` , ``remote-subnet6-get-by-prefix`` ,
``remote-subnet6-list`` , ``remote-subnet6-set`` .
-Commands supported by class_cmds hook library: ``class-add`` ,
+.. _commands-class_cmds-lib:
+
+Commands supported by the Class Commands (class_cmds) hooks library: ``class-add`` ,
``class-del`` , ``class-get`` , ``class-list`` , ``class-update`` .
-Commands supported by high_availability hook library: ``ha-continue`` ,
+.. _commands-high_availability-lib:
+
+Commands supported by the High Availability (high_availability) hooks library: ``ha-continue`` ,
``ha-heartbeat`` , ``ha-scopes`` , ``ha-sync`` .
-Commands supported by host_cache hook library: ``cache-clear`` ,
+.. _commands-host_cache-lib:
+
+Commands supported by the Host Cache (host_cache) hooks library: ``cache-clear`` ,
``cache-get`` , ``cache-get-by-id`` , ``cache-insert`` , ``cache-load``
, ``cache-remove`` , ``cache-size`` , ``cache-write`` .
-Commands supported by host_cmds hook library: ``reservation-add`` ,
+.. _commands-host_cmds-lib:
+
+Commands supported by the Host Commands (host_cmds) hooks library: ``reservation-add`` ,
``reservation-del`` , ``reservation-get`` , ``reservation-get-all`` ,
``reservation-get-page`` .
-Commands supported by lease_cmds hook library: ``lease4-add`` ,
+.. _commands-lease_cmds-lib:
+
+Commands supported by the Lease Commands (lease_cmds) hooks library: ``lease4-add`` ,
``lease4-del`` , ``lease4-get`` , ``lease4-get-all`` , ``lease4-update``
, ``lease4-wipe`` , ``lease6-add`` , ``lease6-del`` , ``lease6-get`` ,
``lease6-get-all`` , ``lease6-update`` , ``lease6-wipe`` .
-Commands supported by stat_cmds hook library: ``stat-lease4-get`` ,
+.. _commands-stat_cmds-lib:
+
+Commands supported by the Supplemental Statistics Commands (stat_cmds) hooks library: ``stat-lease4-get`` ,
``stat-lease6-get`` .
-Commands supported by subnet_cmds hook library: ``network4-add`` ,
+.. _commands-subnet_cmds-lib:
+
+Commands supported by the Subnet Commands (subnet_cmds) hooks library: ``network4-add`` ,
``network4-del`` , ``network4-get`` , ``network4-list`` ,
``network4-subnet-add`` , ``network4-subnet-del`` , ``network6-add`` ,
``network6-del`` , ``network6-get`` , ``network6-list`` ,
build-report reference
======================
-``build-report`` - Returns a list of compilation options that this
-particular binary was built with
+``build-report`` - returns a list of compilation options that this
+particular binary was built with.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
``kea-ctrl-agent``
Availability: 1.2.0 (built-in)
-Description and examples: See `??? <#command-build-report>`__
+Description and examples: see :ref:`command-build-report`
Command syntax:
cache-clear reference
=====================
-``cache-clear`` - This command removes all cached host reservations.
+``cache-clear`` - removes all cached host reservations.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.4.0 (`host_cache <#commands-host_cache-lib>`__ hook)
+Availability: 1.4.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
-Description and examples: See `??? <#command-cache-clear>`__
+Description and examples: see :ref:`command-cache-clear`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-cache-get:
cache-get reference
===================
-``cache-get`` - Returns full content of the host cache.
+``cache-get`` - returns full content of the host cache.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.4.0 (`host_cache <#commands-host_cache-lib>`__ hook)
+Availability: 1.4.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
-Description and examples: See `??? <#command-cache-get>`__
+Description and examples: see :ref:`command-cache-get`
Command syntax:
"arguments": <list of host reservations>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-cache-get-by-id:
cache-get-by-id reference
=========================
-``cache-get-by-id`` - Returns entries matching the given identifier from
+``cache-get-by-id`` - returns entries matching the given identifier from
the host cache.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.6.0 (`host_cache <#commands-host_cache-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
-Description and examples: See `??? <#command-cache-get-by-id>`__
+Description and examples: see :ref:`command-cache-get-by-id`
Command syntax:
"arguments": <list of host reservations>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-cache-insert:
cache-insert reference
======================
-``cache-insert`` - This command may be used to manually insert a host
-into the cache.
+``cache-insert`` - manually inserts a host into the cache.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.4.0 (`host_cache <#commands-host_cache-lib>`__ hook)
+Availability: 1.4.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
-Description and examples: See `??? <#command-cache-insert>`__
+Description and examples: see :ref:`command-cache-insert`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-cache-load:
cache-load reference
====================
-``cache-load`` - This command allows load the contents of a file on disk
+``cache-load`` - allows the contents of a file on disk to be loaded
into an in-memory cache.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.4.0 (`host_cache <#commands-host_cache-lib>`__ hook)
+Availability: 1.4.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
-Description and examples: See `??? <#command-cache-load>`__
+Description and examples: see :ref:`command-cache-load`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-cache-remove:
cache-remove reference
======================
-``cache-remove`` - The cache-remove command works similarly to
-reservation-get command.
+``cache-remove`` - works similarly to the reservation-get command.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.4.0 (`host_cache <#commands-host_cache-lib>`__ hook)
+Availability: 1.4.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
-Description and examples: See `??? <#command-cache-remove>`__
+Description and examples: see :ref:`command-cache-remove`
Command syntax:
}
}
- Another example that removes IPv6 host identifier by DUID and specific subnet-id is:
+ Another example that removes the IPv6 host identifier by DUID and specific subnet-id is:
{
"command": "cache-remove",
"arguments": {
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-cache-size:
cache-size reference
====================
-``cache-size`` - Returns number of entries of the host cache.
+``cache-size`` - returns the number of entries in the host cache.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.6.0 (`host_cache <#commands-host_cache-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
-Description and examples: See `??? <#command-cache-size>`__
+Description and examples: see :ref:`command-cache-size`
Command syntax:
"arguments": { "size": 123 }
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-cache-write:
cache-write reference
=====================
-``cache-write`` - Instructs Kea to write its host cache content to disk.
+``cache-write`` - instructs Kea to write its host cache content to disk.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.4.0 (`host_cache <#commands-host_cache-lib>`__ hook)
+Availability: 1.4.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
-Description and examples: See `??? <#command-cache-write>`__
+Description and examples: see :ref:`command-cache-write`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-class-add:
class-add reference
===================
-``class-add`` - This command is used to create and add a new class to
+``class-add`` - creates and adds a new class to
the existing server configuration.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.5.0 (`class_cmds <#commands-class_cmds-lib>`__ hook)
+Availability: 1.5.0 (:ref:`The Class Commands hooks library<commands-class_cmds-lib>`)
-Description and examples: See `??? <#command-class-add>`__
+Description and examples: see :ref:`command-class-add`
Command syntax:
}
}
-The ``next-server``, ``server-hostname`` and ``boot-file-name`` are
-DHCPv4 specific. Only one client class can be added with a single
+The ``next-server``, ``server-hostname``, and ``boot-file-name`` commands are
+DHCPv4-specific. Only one client class can be added with a single
command.
Response syntax:
class-del reference
===================
-``class-del`` - This command is used to remove a client class from the
-server configuration.
+``class-del`` - removes a client class from the server configuration.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.5.0 (`class_cmds <#commands-class_cmds-lib>`__ hook)
+Availability: 1.5.0 (:ref:`The Class Commands hooks library<commands-class_cmds-lib>`)
-Description and examples: See `??? <#command-class-del>`__
+Description and examples: see :ref:`command-class-del`
Command syntax:
}
The command will return a result of 3 (empty) if the client class
-doesn't exist. If the client class exists, the retured result is 0 if
+does not exist. If the client class exists, the returned result is 0 if
the deletion was successful and the result is 1 if the deletion is
unsuccessful.
class-get reference
===================
-``class-get`` - This command is used to return detailed information
-about an existing client class.
+``class-get`` - returns detailed information about an existing client class.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.5.0 (`class_cmds <#commands-class_cmds-lib>`__ hook)
+Availability: 1.5.0 (:ref:`The Class Commands hooks library<commands-class_cmds-lib>`)
-Description and examples: See `??? <#command-class-get>`__
+Description and examples: see :ref:`command-class-get`
Command syntax:
The returned information depends on the DHCP server type, i.e. some
parameters are specific to DHCPv4 server. Also, some parameters may not
-be returned if they are not set for the client class. If the class with
-specified name doesn't exist a result of 3 (empty) is returned. If the
+be returned if they are not set for the client class. If a class with the
+specified name does not exist, a result of 3 (empty) is returned. If the
client class is found, the result of 0 is returned. If there is an error
while processing the command, the result of 1 is returned.
class-list reference
====================
-``class-list`` - This command is used to retrieve a list of all client
+``class-list`` - retrieves a list of all client
classes from the server configuration.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.5.0 (`class_cmds <#commands-class_cmds-lib>`__ hook)
+Availability: 1.5.0 (:ref:`The Class Commands hooks library<commands-class_cmds-lib>`)
-Description and examples: See `??? <#command-class-list>`__
+Description and examples: see :ref:`command-class-list`
Command syntax:
The returned list of classes merely contains their names. In order to
retrieve full information about one of these classes use
-`??? <#command-class-get>`__. The returned result is 3 (empty) if no
+:ref:`command-class-get`. The returned result is 3 (empty) if no
classes are found. If the command is processed successfully and the list
of client classes is not empty, the result of 0 is returned. If there is
an error while processing the command, the result of 1 is returned.
class-update reference
======================
-``class-update`` - This command is used to update an existing client
+``class-update`` - updates an existing client
class in the server configuration.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.5.0 (`class_cmds <#commands-class_cmds-lib>`__ hook)
+Availability: 1.5.0 (:ref:`The Class Commands hooks library<commands-class_cmds-lib>`)
-Description and examples: See `??? <#command-class-update>`__
+Description and examples: see :ref:`command-class-update`
Command syntax:
}
}
-The ``next-server``, ``server-hostname`` and ``boot-file-name`` are
-DHCPv4 specific. Only one client class can be updated with a single
+The ``next-server``, ``server-hostname``, and ``boot-file-name`` commands are
+DHCPv4-specific. Only one client class can be updated with a single
command.
Response syntax:
}
The command will return the result of 3 (empty) if the client class
-doesn't exist. If the client class exists, the retured result is 0 if
-the update was successful and the result is 1 if the update is
-unsuccessful.
+does not exist. If the client class exists, the returned result is 0 if
+the update was successful and 1 if the update is unsuccessful.
.. _reference-config-get:
config-get reference
====================
-``config-get`` - Retrieves the current configuration used by the server.
-The configuration is roughtly equal to the configuration file, but
+``config-get`` - retrieves the current configuration used by the server.
+The configuration is roughly equal to the configuration file, but
includes additional changes made by other commands and due to parameters
inheritance.
Availability: 1.2.0 (built-in)
-Description and examples: See `??? <#command-config-get>`__
+Description and examples: see :ref:`command-config-get`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-config-reload:
config-reload reference
=======================
-``config-reload`` - The config-reload command instructs Kea to load
+``config-reload`` - instructs Kea to load
again the configuration file that was used previously.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
Availability: 1.2.0 (built-in)
-Description and examples: See `??? <#command-config-reload>`__
+Description and examples: see :ref:`command-config-reload`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-config-set:
config-set reference
====================
-``config-set`` - The config-set command instructs the server to replace
+``config-set`` - instructs the server to replace
its current configuration with the new configuration supplied in the
command's arguments.
Availability: 1.2.0 (built-in)
-Description and examples: See `??? <#command-config-set>`__
+Description and examples: see :ref:`command-config-set`
Command syntax:
}
}
-where <server> is the configuration element name for a given server such
+where <server> is the configuration element name for a given server, such
as "Dhcp4" or "Dhcp6"
Response syntax:
{"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-config-test:
config-test reference
=====================
-``config-test`` - The config-test command instructs the server to check
+``config-test`` - instructs the server to check
whether the new configuration supplied in the command's arguments can be
loaded.
Availability: 1.2.0 (built-in)
-Description and examples: See `??? <#command-config-test>`__
+Description and examples: see :ref:`command-config-test`
Command syntax:
}
}
-where >server< is the configuration element name for a given server such
+where <server> is the configuration element name for a given server, such
as "Dhcp4" or "Dhcp6"
Response syntax:
{"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-config-write:
config-write reference
======================
-``config-write`` - The config-write command instructs the Kea server to
+``config-write`` - instructs the Kea server to
write its current configuration to a file on disk.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
Availability: 1.2.0 (built-in)
-Description and examples: See `??? <#command-config-write>`__
+Description and examples: see :ref:`command-config-write`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-dhcp-disable:
dhcp-disable reference
======================
-``dhcp-disable`` - The dhcp-disable command globally disables the DHCP
-service.
+``dhcp-disable`` - globally disables the DHCP service.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
Availability: 1.4.0 (built-in)
-Description and examples: See `??? <#command-dhcp-disable>`__
+Description and examples: see :ref:`command-dhcp-disable`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-dhcp-enable:
dhcp-enable reference
=====================
-``dhcp-enable`` - The dhcp-enable command globally enables the DHCP
-service.
+``dhcp-enable`` - globally enables the DHCP service.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
Availability: 1.4.0 (built-in)
-Description and examples: See `??? <#command-dhcp-enable>`__
+Description and examples: see :ref:`command-dhcp-enable`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-ha-continue:
ha-continue reference
=====================
-``ha-continue`` - This command is used to resume the operation of the
+``ha-continue`` - resumes the operation of the
paused HA state machine.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.4.0
-(`high_availability <#commands-high_availability-lib>`__ hook)
+Availability: 1.4.0 (:ref:`The High Availability hooks library<commands-high_availability-lib>`)
-Description and examples: See `??? <#command-ha-continue>`__
+Description and examples: see :ref:`command-ha-continue`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-ha-heartbeat:
ha-heartbeat reference
======================
-``ha-heartbeat`` - This command is sent internally by Kea partner when
-operating in High Availability (HA) mode. It will retrieve the server HA
+``ha-heartbeat`` - is sent internally by a Kea partner when
+operating in High Availability (HA) mode; it retrieves the server HA
state and clock value.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.4.0
-(`high_availability <#commands-high_availability-lib>`__ hook)
+Availability: 1.4.0 (:ref:`The High Availability hooks library<commands-high_availability-lib>`)
-Description and examples: See `??? <#command-ha-heartbeat>`__
+Description and examples: see :ref:`ha-server-states`
Command syntax:
}
The response to this command is different from the typical command
-response. The response will include server state (see
-`??? <#ha-server-states>`__ plus the current clock value.
+response. The response will include the server state (see
+:ref:`ha-server-states` plus the current clock value.
.. _reference-ha-scopes:
ha-scopes reference
===================
-``ha-scopes`` - This command modifies the scope that the server is
+``ha-scopes`` - modifies the scope that the server is
responsible for serving when operating in High Availability (HA) mode.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.4.0
-(`high_availability <#commands-high_availability-lib>`__ hook)
+Availability: 1.4.0 (:ref:`The High Availability hooks library<commands-high_availability-lib>`)
-Description and examples: See `??? <#command-ha-scopes>`__
+Description and examples: see :ref:`command-ha-scopes`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-ha-sync:
ha-sync reference
=================
-``ha-sync`` - The command is issued to instruct the server running in HA
+``ha-sync`` - instructs the server running in HA
mode to synchronize its local lease database with the selected peer.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.4.0
-(`high_availability <#commands-high_availability-lib>`__ hook)
+Availability: 1.4.0 (:ref:`The High Availability hooks library<commands-high_availability-lib>`)
-Description and examples: See `??? <#command-ha-sync>`__
+Description and examples: see :ref:`command-ha-sync`
Command syntax:
{
"command": "ha-sync",
- "service": [ <service affected: "dhcp4" or "dhcp6" ],
+ "service": [ <service affected:> "dhcp4" or "dhcp6" ],
"arguments": {
"server-name": <name of the partner server>,
"max-period": <integer, in seconds>
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-lease4-add:
lease4-add reference
====================
-``lease4-add`` - The lease4-add command adds a new IPv4 lease
-administratively.
+``lease4-add`` - adds a new IPv4 lease administratively.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`lease_cmds <#commands-lease_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
-Description and examples: See `??? <#command-lease4-add>`__
+Description and examples: see :ref:`command-lease4-add`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-lease4-del:
lease4-del reference
====================
-``lease4-del`` - lease4-del can be used to delete a lease from the lease
-database.
+``lease4-del`` - deletes a lease from the lease database.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`lease_cmds <#commands-lease_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
-Description and examples: See `??? <#command-lease4-del>`__
+Description and examples: see :ref:`command-lease4-del`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-lease4-get:
lease4-get reference
====================
-``lease4-get`` - lease4-get can be used to query the lease database and
-retrieve existing leases.
+``lease4-get`` - queries the lease database and retrieves existing leases.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`lease_cmds <#commands-lease_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
-Description and examples: See `??? <#command-lease4-get>`__
+Description and examples: see :ref:`command-lease4-get`
Command syntax:
"text": "IPv4 lease found."
}
-lease4-get returns a result that indicates a result of the operation and
+``lease4-get`` returns a result that indicates a result of the operation and
lease details, if found. It has one of the following values: 0
-(success), 1 (error) or 2 (empty).
+(success), 1 (error), or 2 (empty).
.. _reference-lease4-get-all:
lease4-get-all reference
========================
-``lease4-get-all`` - lease4-get-all is used to retrieve all IPv4 leases
+``lease4-get-all`` - retrieves all IPv4 leases
or all leases for the specified set of subnets.
Supported by: ``kea-dhcp4``
-Availability: 1.4.0 (`lease_cmds <#commands-lease_cmds-lib>`__ hook)
+Availability: 1.4.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
-Description and examples: See `??? <#command-lease4-get-all>`__
+Description and examples: see :ref:`command-lease4-get-all`
Command syntax:
"arguments": "subnets"
}
-The lease4-get-all command may result in very large responses.
+The ``lease4-get-all`` command may result in very large responses.
Response syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-lease4-update:
lease4-update reference
=======================
-``lease4-update`` - The lease4-update command can be used to update
-existing leases.
+``lease4-update`` - updates existing leases.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`lease_cmds <#commands-lease_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
-Description and examples: See `??? <#command-lease4-update>`__
+Description and examples: see :ref:`command-lease4-update`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-lease4-wipe:
lease4-wipe reference
=====================
-``lease4-wipe`` - lease4-wipe is designed to remove all leases
-associated with a given subnet.
+``lease4-wipe`` - removes all leases associated with a given subnet.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`lease_cmds <#commands-lease_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
-Description and examples: See `??? <#command-lease4-wipe>`__
+Description and examples: see :ref:`command-lease4-wipe`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-lease6-add:
lease6-add reference
====================
-``lease6-add`` - The lease6-add command creates a new lease
-administratively.
+``lease6-add`` - creates a new lease administratively.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`lease_cmds <#commands-lease_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
-Description and examples: See `??? <#command-lease6-add>`__
+Description and examples: see :ref:`command-lease4-add`
Command syntax:
}
}
-lease6-add can be also used to add leases for IPv6 prefixes..
+``lease6-add`` can be also used to add leases for IPv6 prefixes.
Response syntax:
{ "result": 0, "text": "Lease added." }
{ "result": 1, "text": "missing parameter 'ip-address' (<string>:3:19)" }
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-lease6-del:
lease6-del reference
====================
-``lease6-del`` - lease6-del can be used to delete a lease from the lease
-database.
+``lease6-del`` - deletes a lease from the lease database.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`lease_cmds <#commands-lease_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
-Description and examples: See `??? <#command-lease6-del>`__
+Description and examples: see :ref:`command-lease4-del`
Command syntax:
}
}
-lease6-del returns a result that indicates a outcome of the operation.
-It has one of the following values: 0 (success), 1 (error) or 3 (empty).
+``lease6-del`` returns a result that indicates a outcome of the operation.
+It has one of the following values: 0 (success), 1 (error), or 3 (empty).
Response syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-lease6-get:
lease6-get reference
====================
-``lease6-get`` - lease6-get can be used to query the lease database and
-retrieve existing leases.
+``lease6-get`` - queries the lease database and retrieves existing leases.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`lease_cmds <#commands-lease_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
-Description and examples: See `??? <#command-lease6-get>`__
+Description and examples: see :ref:`command-lease4-get`
Command syntax:
}
}
-lease6-get returns a result that indicates a result of the operation and
+``lease6-get`` returns a result that indicates a result of the operation and
lease details, if found. It has one of the following values: 0
-(success), 1 (error) or 2 (empty).
+(success), 1 (error), or 2 (empty).
Response syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-lease6-get-all:
lease6-get-all reference
========================
-``lease6-get-all`` - lease6-get-all is used to retrieve all IPv6 leases
+``lease6-get-all`` - retrieves all IPv6 leases
or all leases for the specified set of subnets.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`lease_cmds <#commands-lease_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
-Description and examples: See `??? <#command-lease6-get-all>`__
+Description and examples: see :ref:`command-lease4-get-all`
Command syntax:
"text": "2 IPv6 lease(s) found."
}
-The lease6-get-all command may result in very large responses.
+The ``lease6-get-all`` command may result in very large responses.
.. _reference-lease6-update:
lease6-update reference
=======================
-``lease6-update`` - The lease6-update command can be used to update
-existing leases.
+``lease6-update`` - updates existing leases.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`lease_cmds <#commands-lease_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
-Description and examples: See `??? <#command-lease6-update>`__
+Description and examples: see :ref:`command-lease4-update`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-lease6-wipe:
lease6-wipe reference
=====================
-``lease6-wipe`` - lease6-wipe is designed to remove all leases
-associated with a given subnet.
+``lease6-wipe`` - removes all leases associated with a given subnet.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`lease_cmds <#commands-lease_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
-Description and examples: See `??? <#command-lease6-wipe>`__
+Description and examples: see :ref:`command-lease4-wipe`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-leases-reclaim:
leases-reclaim reference
========================
-``leases-reclaim`` - The leases-reclaim command instructs the server to
+``leases-reclaim`` - instructs the server to
reclaim all expired leases immediately.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
Availability: 1.0.0 (built-in)
-Description and examples: See `??? <#command-leases-reclaim>`__
+Description and examples: see :ref:`command-leases-reclaim`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-libreload:
libreload reference
===================
-``libreload`` - The libreload command will first unload and then load
-all currently loaded hook libraries.
+``libreload`` - unloads and then loads all currently loaded hook libraries.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
Availability: 1.2.0 (built-in)
-Description and examples: See `??? <#command-libreload>`__
+Description and examples: see :ref:`command-libreload`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-list-commands:
list-commands reference
=======================
-``list-commands`` - The list-commands command retrieves a list of all
-commands supported by the server.
+``list-commands`` - retrieves a list of all commands supported by the server.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
``kea-ctrl-agent``
Availability: 1.0.0 (built-in)
-Description and examples: See `??? <#command-list-commands>`__
+Description and examples: see :ref:`command-list-commands`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-network4-add:
network4-add reference
======================
-``network4-add`` - The network4-add command is used to add a new shared
-network.
+``network4-add`` - adds a new shared network.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-network4-add>`__
+Description and examples: see :ref:`command-network4-add`
Command syntax:
"text": "A new IPv4 shared network 'floor13' added"
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-network4-del:
network4-del reference
======================
-``network4-del`` - The network4-del command is used to delete existing
-shared networks.
+``network4-del`` - deletes existing shared networks.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-network4-del>`__
+Description and examples: see :ref:`command-network4-del`
Command syntax:
"text": "IPv4 shared network 'floor13' deleted"
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-network4-get:
network4-get reference
======================
-``network4-get`` - The network4-get command is used to retrieve detailed
+``network4-get`` - retrieves detailed
information about shared networks, including subnets currently being
part of a given network.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-network4-get>`__
+Description and examples: see :ref:`command-network4-get`
Command syntax:
network4-list reference
=======================
-``network4-list`` - The network4-list command is used to retrieve full
-list of currently configured shared networks.
+``network4-list`` - retrieves the full list of currently configured shared networks.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-network4-list>`__
+Description and examples: see :ref:`command-network4-list`
Command syntax:
"text": "2 IPv4 network(s) found"
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-network4-subnet-add:
network4-subnet-add reference
=============================
-``network4-subnet-add`` - The network4-subnet-add command is used to add
-existing subnets to existing shared networks.
+``network4-subnet-add`` - adds existing subnets to existing shared networks.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-network4-subnet-add>`__
+Description and examples: see :ref:`command-network4-subnet-add`
Command syntax:
"text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'"
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-network4-subnet-del:
network4-subnet-del reference
=============================
-``network4-subnet-del`` - The network4-subnet-del command is used to
-remove a subnet that is part of an existing shared network and demote it
-to a plain, stand-alone subnet.
+``network4-subnet-del`` - removes a subnet that is part of an existing shared
+network and demotes it to a plain, stand-alone subnet.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-network4-subnet-del>`__
+Description and examples: see :ref:`command-network4-subnet-del`
Command syntax:
"text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'"
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-network6-add:
network6-add reference
======================
-``network6-add`` - The network6-add command is used to add a new shared
-network.
+``network6-add`` - adds a new shared network.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-network6-add>`__
+Description and examples: see :ref:`command-network4-add`
Command syntax:
}
}
-The network6-add uses the same syntax for both the query and the
+The ``network6-add`` command uses the same syntax for both the query and the
response. However, there are some parameters that are IPv4-only (e.g.
-match-client-id) and some are IPv6-only (e.g. interface-id).
+match-client-id) and some that are IPv6-only (e.g. interface-id).
Response syntax:
"text": "A new IPv4 shared network 'floor13' added"
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-network6-del:
network6-del reference
======================
-``network6-del`` - The network6-del command is used to delete existing
-shared networks.
+``network6-del`` - deletes existing shared networks.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-network6-del>`__
+Description and examples: see :ref:`command-network4-del`
Command syntax:
}
}
-The network6-del command uses exactly the same syntax for both the
-command and the response.
+The ``network6-del`` command uses exactly the same syntax as ``network4-del``
+for both the command and the response.
Response syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-network6-get:
network6-get reference
======================
-``network6-get`` - The network6-get command is used to retrieve detailed
-information about shared networks, including subnets currently being
+``network6-get`` - retrieves detailed
+information about shared networks, including subnets that are currently
part of a given network.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-network6-get>`__
+Description and examples: see :ref:`command-network4-get`
Command syntax:
network6-list reference
=======================
-``network6-list`` - The network6-list command is used to retrieve full
-list of currently configured shared networks.
+``network6-list`` - retrieves the full list of currently configured shared networks.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-network6-list>`__
+Description and examples: see :ref:`command-network4-list`
Command syntax:
"command": "network4-list"
}
-network6-list follows exactly the same syntax for both the query and the
-response.
+The ``network6-list`` command follows exactly the same syntax as ``network4-list`` for
+both the query and the response.
Response syntax:
"text": "2 IPv4 network(s) found"
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-network6-subnet-add:
network6-subnet-add reference
=============================
-``network6-subnet-add`` - The network6-subnet-add command is used to add
-existing subnets to existing shared networks.
+``network6-subnet-add`` - adds existing subnets to existing shared networks.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-network6-subnet-add>`__
+Description and examples: see :ref:`command-network4-subnet-add`
Command syntax:
}
}
-The network6-subnet-add command uses exactly the same syntax for both
-the command and the response.
+The ``network6-subnet-add`` command uses exactly the same syntax as
+``network4-subnet-add`` for both the command and the response.
Response syntax:
"text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'"
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-network6-subnet-del:
network6-subnet-del reference
=============================
-``network6-subnet-del`` - The network6-subnet-del command is used to
-remove a subnet that is part of existing shared network and demote it to
-a plain, stand-alone subnet.
+``network6-subnet-del`` - removes a subnet that is part of an existing shared
+network and demotes it to a plain, stand-alone subnet.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-network6-subnet-del>`__
+Description and examples: see :ref:`command-network4-subnet-del`
Command syntax:
}
}
-The network6-subnet-del command uses exactly the same syntax for both
-the command and the response.
+The ``network6-subnet-del`` command uses exactly the same syntax as
+``network4-subnet-del`` for both the command and the response.
Response syntax:
"text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'"
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-global-parameter4-del:
remote-global-parameter4-del reference
======================================
-``remote-global-parameter4-del`` - This command is used to delete a
+``remote-global-parameter4-del`` - deletes a
global DHCPv4 parameter from the configuration database. The server will
use the value specified in the configuration file or a default value (if
the parameter is not specified in the configuration file) after deleting
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-global-parameter4-del>`__
+Description and examples: see :ref:`command-remote-global-parameter4-del`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-global-parameter4-get:
remote-global-parameter4-get reference
======================================
-``remote-global-parameter4-get`` - This command is used to fetch
+``remote-global-parameter4-get`` - fetches the
selected global parameter for the server from the specified database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-global-parameter4-get>`__
+Description and examples: see :ref:`command-remote-global-parameter4-get`
Command syntax:
}
The returned response contains a map with a global parameter name/value
-pair. The value may be a JSON string, integer, real or boolean. The
-metadata is included and it provides database specific information
+pair. The value may be a JSON string, integer, real, or boolean. The
+metadata is included and provides database-specific information
associated with the returned object.
.. _reference-remote-global-parameter4-get-all:
remote-global-parameter4-get-all reference
==========================================
-``remote-global-parameter4-get-all`` - This command is used to fetch all
+``remote-global-parameter4-get-all`` - fetches all
global parameters for the server from the specified database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-global-parameter4-get-all>`__
+Description and examples: see :ref:`command-remote-global-parameter4-get-all`
Command syntax:
The returned response contains a list of maps. Each map contains a
global parameter name/value pair. The value may be a JSON string,
-integer, real or boolean. The metadata is appended to each parameter and
-it provides database specific information associated with the returned
+integer, real, or boolean. The metadata is appended to each parameter and
+provides database-specific information associated with the returned
objects.
.. _reference-remote-global-parameter4-set:
remote-global-parameter4-set reference
======================================
-``remote-global-parameter4-set`` - This command is used to create or
-update one more global parameters in the configuration database.
+``remote-global-parameter4-set`` - creates or
+updates one or more global parameters in the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-global-parameter4-set>`__
+Description and examples: see :ref:`command-remote-global-parameter4-set`
Command syntax:
}
This command carries multiple global parameters with their values. Care
-should be taken when specifying more than one parameter because in some
+should be taken when specifying more than one parameter, because in some
cases only a subset of the parameters may be successfully stored in the
database and other parameters may fail to be stored. In such cases the
-``remote-global-parameter4-get-all`` may be useful to verify the
+``remote-global-parameter4-get-all`` command may be useful to verify the
contents of the database after the update.
Response syntax:
"text": "DHCPv4 global parameter(s) successfully set."
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-global-parameter6-del:
remote-global-parameter6-del reference
======================================
-``remote-global-parameter6-del`` - This command is used to delete a
+``remote-global-parameter6-del`` - deletes a
global DHCPv6 parameter from the configuration database. The server will
use the value specified in the configuration file or a default value (if
the parameter is not specified in the configuration file) after deleting
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-global-parameter6-del>`__
+Description and examples: see :ref:`command-remote-global-parameter4-del`
Command syntax:
"count": 1
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-global-parameter6-get:
remote-global-parameter6-get reference
======================================
-``remote-global-parameter6-get`` - This command is used to fetch
+``remote-global-parameter6-get`` - fetches the
selected global parameter for the server from the specified database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-global-parameter6-get>`__
+Description and examples: see :ref:`command-remote-global-parameter4-get`
Command syntax:
}
The returned response contains a map with a global parameter name/value
-pair. The value may be a JSON string, integer, real or boolean. The
-metadata is included and it provides database specific information
+pair. The value may be a JSON string, integer, real, or boolean. The
+metadata is included and provides database-specific information
associated with the returned object.
.. _reference-remote-global-parameter6-get-all:
remote-global-parameter6-get-all reference
==========================================
-``remote-global-parameter6-get-all`` - This command is used to fetch all
+``remote-global-parameter6-get-all`` - fetches all
global parameters for the server from the specified database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-global-parameter6-get-all>`__
+Description and examples: see :ref:`command-remote-global-parameter4-get-all`
Command syntax:
The returned response contains a list of maps. Each map contains a
global parameter name/value pair. The value may be a JSON string,
-integer, real or boolean. The metadata is appended to each parameter and
-it provides database specific information associated with the returned
+integer, real, or boolean. The metadata is appended to each parameter and
+provides database-specific information associated with the returned
objects.
.. _reference-remote-global-parameter6-set:
remote-global-parameter6-set reference
======================================
-``remote-global-parameter6-set`` - This command is used to create or
-update one more global DHCP parameters in the configuration database.
+``remote-global-parameter6-set`` - creates or
+updates one or more global DHCP parameters in the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-global-parameter6-set>`__
+Description and examples: see :ref:`command-remote-global-parameter4-set`
Command syntax:
}
This command carries multiple global parameters with their values. Care
-should be taken when specifying more than one parameter because in some
+should be taken when specifying more than one parameter, because in some
cases only a subset of the parameters may be successfully stored in the
database and other parameters may fail to be stored. In such cases the
-``remote-global-parameter6-get-all`` may be useful to verify the
+``remote-global-parameter6-get-all`` command may be useful to verify the
contents of the database after the update.
Response syntax:
"text": "DHCPv6 global parameter(s) successfully set."
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-network4-del:
remote-network4-del reference
=============================
-``remote-network4-del`` - This command is used to delete an IPv4 shared
+``remote-network4-del`` - deletes an IPv4 shared
network from the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-network4-del>`__
+Description and examples: see :ref:`command-remote-network4-del`
Command syntax:
}
This command includes a list with exactly one name of the shared network
-to be deleted. The ``subnets-action`` denotes whether the subnets in
+to be deleted. The ``subnets-action`` command denotes whether the subnets in
this shared network should be deleted or not.
Response syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-network4-get:
remote-network4-get reference
=============================
-``remote-network4-get`` - This command is used to fetch selected IPv4
+``remote-network4-get`` - fetches the selected IPv4
shared network for the server from the specified database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-network4-get>`__
+Description and examples: see :ref:`command-remote-network4-get`
Command syntax:
}
This command includes a list with exactly one name of the shared network
-to be returned. The ``subnets-include`` optional parameter allows for
-specifying whether the subnets belonging to the shared network should
+to be returned. The ``subnets-include`` optional parameter
+specifies whether the subnets belonging to the shared network should
also be returned.
Response syntax:
If the subnets are returned with the shared network they are carried in
the ``subnet4`` list within the shared network definition. The metadata
-is included in the returned shared network definition and it provides
-the database specific information associated with the returned object.
+is included in the returned shared network definition and provides
+the database-specific information associated with the returned object.
.. _reference-remote-network4-list:
remote-network4-list reference
==============================
-``remote-network4-list`` - This command is used to fetch a list of all
+``remote-network4-list`` - fetches a list of all
IPv4 shared networks from the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-network4-list>`__
+Description and examples: see :ref:`command-remote-network4-list`
Command syntax:
}
The returned response contains the list of maps. Each map contains the
-shared network name and the metadata which provides database specific
+shared network name and the metadata, which provides database-specific
information associated with the shared network. The returned list does
-not contain full definitions of the shared networks. Use
-``remote-network4-get`` to fetch the full information about the selected
+not contain full definitions of the shared networks; use
+``remote-network4-get`` to fetch the complete information about the selected
shared networks.
.. _reference-remote-network4-set:
remote-network4-set reference
=============================
-``remote-network4-set`` - This command is used to create or replace an
+``remote-network4-set`` - creates or replaces an
IPv4 shared network in the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-network4-set>`__
+Description and examples: see :ref:`command-remote-network4-set`
Command syntax:
}
The provided list must contain exactly one shared network specification.
-It must not contain subnets ("subnet4" parameter). The subnets are added
-to the shared network using ``remote-subnet4-set`` command.
+It must not contain subnets ("subnet4" parameter); the subnets are added
+to the shared network using the ``remote-subnet4-set`` command.
Response syntax:
"text": "IPv4 shared network successfully set."
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-network6-del:
remote-network6-del reference
=============================
-``remote-network6-del`` - This command is used to delete an IPv6 shared
+``remote-network6-del`` - deletes an IPv6 shared
network from the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-network6-del>`__
+Description and examples: see :ref:`command-remote-network4-del`
Command syntax:
}
This command includes a list with exactly one name of the shared network
-to be deleted. The ``subnets-action`` denotes whether the subnets in
+to be deleted. The ``subnets-action`` command denotes whether the subnets in
this shared network should be deleted or not.
Response syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-network6-get:
remote-network6-get reference
=============================
-``remote-network6-get`` - This command is used to fetch selected IPv6
+``remote-network6-get`` - fetches the selected IPv6
shared network for the server from the specified database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-network6-get>`__
+Description and examples: see :ref:`command-remote-network4-get`
Command syntax:
}
This command includes a list with exactly one name of the shared network
-to be returned. The ``subnets-include`` optional parameter allows for
-specifying whether the subnets belonging to the shared network should
+to be returned. The ``subnets-include`` optional parameter
+specifies whether the subnets belonging to the shared network should
also be returned.
Response syntax:
}
}
-If the subnets are returned with the shared network they are carried in
+If the subnets are returned with the shared network, they are carried in
the ``subnet6`` list within the shared network definition. The metadata
-is included in the returned shared network definition and it provides
-the database specific information associated with the returned object.
+is included in the returned shared network definition and provides
+the database-specific information associated with the returned object.
.. _reference-remote-network6-list:
remote-network6-list reference
==============================
-``remote-network6-list`` - This command is used to fetch a list of all
+``remote-network6-list`` - fetches a list of all
IPv6 shared networks from the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-network6-list>`__
+Description and examples: see :ref:`command-remote-network4-list`
Command syntax:
}
The returned response contains the list of maps. Each map contains the
-shared network name and the metadata which provides database specific
+shared network name and the metadata, which provides database-specific
information associated with the shared network. The returned list does
-not contain full definitions of the shared networks. Use
-``remote-network6-get`` to fetch the full information about the selected
+not contain full definitions of the shared networks; use
+``remote-network6-get`` to fetch the complete information about the selected
shared networks.
.. _reference-remote-network6-set:
remote-network6-set reference
=============================
-``remote-network6-set`` - This command is used to create or replace an
+``remote-network6-set`` - creates or replaces an
IPv6 shared network in the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-network6-set>`__
+Description and examples: see :ref:`command-remote-network4-set`
Command syntax:
}
The provided list must contain exactly one shared network specification.
-It must not contain subnets ("subnet6" parameter). The subnets are added
-to the shared network using ``remote-subnet6-set`` command.
+It must not contain subnets ("subnet6" parameter); the subnets are added
+to the shared network using the ``remote-subnet6-set`` command.
Response syntax:
"text": "IPv6 shared network successfully set."
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-option-def4-del:
remote-option-def4-del reference
================================
-``remote-option-def4-del`` - This command is used to delete a DHCPv4
+``remote-option-def4-del`` - deletes a DHCPv4
option definition from the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-option-def4-del>`__
+Description and examples: see :ref:`command-remote-option-def4-del`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-option-def4-get:
remote-option-def4-get reference
================================
-``remote-option-def4-get`` - This command is used to fetch a DHCPv4
+``remote-option-def4-get`` - fetches a DHCPv4
option definition from the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-option-def4-get>`__
+Description and examples: see :ref:`command-remote-option-def4-get`
Command syntax:
}
}
-The desired option definition is identified by the pair of the option
+The desired option definition is identified by the pair of option
code/space values.
Response syntax:
}
}
-The metadata is included and it provides database specific information
+The metadata is included and provides database-specific information
associated with the returned object.
.. _reference-remote-option-def4-get-all:
remote-option-def4-get-all reference
====================================
-``remote-option-def4-get-all`` - This command is used to fetch all
+``remote-option-def4-get-all`` - fetches all
DHCPv4 option definitions from the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-option-def4-get-all>`__
+Description and examples: see :ref:`command-remote-option-def4-get-all`
Command syntax:
}
The returned response contains a list of maps. Each map contains an
-option definition specification and the metadata including database
-specific information associated with the returned objects.
+option definition specification and the metadata, including
+database-specific information associated with the returned objects.
.. _reference-remote-option-def4-set:
remote-option-def4-set reference
================================
-``remote-option-def4-set`` - This command is used to create or replace
+``remote-option-def4-set`` - creates or replaces a
DHCPv4 option definition in the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-option-def4-set>`__
+Description and examples: see :ref:`command-remote-option-def4-set`
Command syntax:
"text": "DHCPv4 option definition set."
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-option-def6-del:
remote-option-def6-del reference
================================
-``remote-option-def6-del`` - This command is used to delete a DHCPv6
+``remote-option-def6-del`` - deletes a DHCPv6
option definition from the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-option-def6-del>`__
+Description and examples: see :ref:`command-remote-option-def4-del`
Command syntax:
"option-defs": [
{
"code": <option code>,
- "space": <option space
+ "space": <option space>
}
],
"remote": {
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-option-def6-get:
remote-option-def6-get reference
================================
-``remote-option-def6-get`` - This command is used to fetch a DHCPv6
+``remote-option-def6-get`` - fetches a DHCPv6
option definition from the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-option-def6-get>`__
+Description and examples: see :ref:`command-remote-option-def4-get`
Command syntax:
}
}
-The metadata is included and it provides database specific information
+The metadata is included and provides database-specific information
associated with the returned object.
.. _reference-remote-option-def6-get-all:
remote-option-def6-get-all reference
====================================
-``remote-option-def6-get-all`` - This command is used to fetch all
+``remote-option-def6-get-all`` - fetches all
DHCPv6 option definitions from the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-option-def6-get-all>`__
+Description and examples: see :ref:`command-remote-option-def4-get-all`
Command syntax:
}
The returned response contains a list of maps. Each map contains an
-option definition specification and the metadata including database
-specific information associated with the returned objects.
+option definition specification and the metadata, including
+database-specific information associated with the returned objects.
.. _reference-remote-option-def6-set:
remote-option-def6-set reference
================================
-``remote-option-def6-set`` - This command is used to create or replace
+``remote-option-def6-set`` - creates or replaces a
DHCPv6 option definition in the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-option-def6-set>`__
+Description and examples: see :ref:`command-remote-option-def4-set`
Command syntax:
"text": "DHCPv6 option definition set."
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-option4-global-del:
remote-option4-global-del reference
===================================
-``remote-option4-global-del`` - This command is used to delete a DHCPv4
+``remote-option4-global-del`` - deletes a DHCPv4
global option from the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-option4-global-del>`__
+Description and examples: see :ref:`command-remote-option4-global-del`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-option4-global-get:
remote-option4-global-get reference
===================================
-``remote-option4-global-get`` - This command is used to fetch a global
+``remote-option4-global-get`` - fetches a global
DHCPv4 option for the server from the specified database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-option4-global-get>`__
+Description and examples: see :ref:`command-remote-option4-global-get`
Command syntax:
}
}
-The metadata is included and it provides database specific information
+The metadata is included and provides database-specific information
associated with the returned object.
.. _reference-remote-option4-global-get-all:
remote-option4-global-get-all reference
=======================================
-``remote-option4-global-get-all`` - This command is used to fetch all
+``remote-option4-global-get-all`` - fetches all
DHCPv4 global options for the server from the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-option4-global-get-all>`__
+Description and examples: see :ref:`command-remote-option4-global-get-all`
Command syntax:
}
The returned response contains a list of maps. Each map contains a
-global option specification and the metadata including database specific
+global option specification and the metadata, including database-specific
information associated with the returned object.
.. _reference-remote-option4-global-set:
remote-option4-global-set reference
===================================
-``remote-option4-global-set`` - This command is used to create or
-replace a DHCPv4 global option in the configuration database.
+``remote-option4-global-set`` - creates or
+replaces a DHCPv4 global option in the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-option4-global-set>`__
+Description and examples: see :ref:`command-remote-option4-global-set`
Command syntax:
}
}
-The provided list must cotain exactly one option specification.
+The provided list must contain exactly one option specification.
Response syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-option6-global-del:
remote-option6-global-del reference
===================================
-``remote-option6-global-del`` - This command is used to delete a DHCPv6
+``remote-option6-global-del`` - deletes a DHCPv6
global option from the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-option6-global-del>`__
+Description and examples: see :ref:`command-remote-option4-global-del`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-option6-global-get:
remote-option6-global-get reference
===================================
-``remote-option6-global-get`` - This command is used to delete a DHCPv6
+``remote-option6-global-get`` - deletes a DHCPv6
global option from the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-option6-global-get>`__
+Description and examples: see :ref:`command-remote-option4-global-get`
Command syntax:
}
}
-The metadata is included and it provides database specific information
+The metadata is included and provides database-specific information
associated with the returned object.
.. _reference-remote-option6-global-get-all:
remote-option6-global-get-all reference
=======================================
-``remote-option6-global-get-all`` - This command is used to fetch all
+``remote-option6-global-get-all`` - fetches all
DHCPv6 global options for the server from the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-option6-global-get-all>`__
+Description and examples: see :ref:`command-remote-option4-global-get-all`
Command syntax:
}
The returned response contains a list of maps. Each map contains a
-global option specification and the metadata including database specific
+global option specification and the metadata, including database-specific
information associated with the returned object.
.. _reference-remote-option6-global-set:
remote-option6-global-set reference
===================================
-``remote-option6-global-set`` - This command is used to create or
-replace a DHCPv6 global option in the configuration database.
+``remote-option6-global-set`` - creates or
+replaces a DHCPv6 global option in the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-option6-global-set>`__
+Description and examples: see :ref:`command-remote-option4-global-set`
Command syntax:
}
}
-The provided list must cotain exactly one option specification.
+The provided list must contain exactly one option specification.
Response syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-subnet4-del-by-id:
remote-subnet4-del-by-id reference
==================================
-``remote-subnet4-del-by-id`` - This command is used to delete an IPv4
+``remote-subnet4-del-by-id`` - deletes an IPv4
subnet by ID from the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-subnet4-del-by-id>`__
+Description and examples: see :ref:`command-remote-subnet4-del-by-id`
Command syntax:
}
}
-This command includes a list with exactly one id of the subnet to be
+This command includes a list with exactly one ID of the subnet to be
deleted.
Response syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-subnet4-del-by-prefix:
remote-subnet4-del-by-prefix reference
======================================
-``remote-subnet4-del-by-prefix`` - This command is used to delete an
+``remote-subnet4-del-by-prefix`` - deletes an
IPv4 subnet by prefix from the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-subnet4-del-by-prefix>`__
+Description and examples: see :ref:`command-remote-subnet4-del-by-prefix`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-subnet4-get-by-id:
remote-subnet4-get-by-id reference
==================================
-``remote-subnet4-get-by-id`` - This command is used to fetch selected
+``remote-subnet4-get-by-id`` - fetches a selected
IPv4 subnet by ID for the server from the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-subnet4-get-by-id>`__
+Description and examples: see :ref:`command-remote-subnet4-get-by-id`
Command syntax:
}
}
-This command includes a list with exactly one id of the subnet to be
+This command includes a list with exactly one ID of the subnet to be
returned.
Response syntax:
If the shared network name is null, it means that the returned subnet
does not belong to any shared network (global subnet). The metadata is
-included in the returned subnet definition and it provides database
-specific information associated with the returned object.
+included in the returned subnet definition and provides
+database-specific information associated with the returned object.
.. _reference-remote-subnet4-get-by-prefix:
remote-subnet4-get-by-prefix reference
======================================
-``remote-subnet4-get-by-prefix`` - This command is used to fetch
+``remote-subnet4-get-by-prefix`` - fetches a
selected IPv4 subnet by prefix from the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-subnet4-get-by-prefix>`__
+Description and examples: see :ref:`command-remote-subnet4-get-by-prefix`
Command syntax:
If the shared network name is null, it means that the returned subnet
does not belong to any shared network (global subnet). The metadata is
-included in the returned subnet definition and it provides database
-specific information associated with the returned object.
+included in the returned subnet definition and provides
+database-specific information associated with the returned object.
.. _reference-remote-subnet4-list:
remote-subnet4-list reference
=============================
-``remote-subnet4-list`` - This command is used to fetch a list of all
+``remote-subnet4-list`` - fetches a list of all
IPv4 subnets from the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-subnet4-list>`__
+Description and examples: see :ref:`command-remote-subnet4-list`
Command syntax:
}
The returned response contains a list of maps. Each map contains a
-subnet identifier, prefix and shared network name to which the subnet
-belongs. If the subnet does not belong to a shared netork the name is
-null. The metadata includes database specific information associated
+subnet identifier, prefix, and shared network name to which the subnet
+belongs. If the subnet does not belong to a shared network, the name is
+null. The metadata includes database-specific information associated
with the subnets. The returned list does not contain full subnet
-definitions. Use ``remote-subnet4-get`` to fetch the full information
+definitions; use ``remote-subnet4-get`` to fetch the complete information
about the selected subnets.
.. _reference-remote-subnet4-set:
remote-subnet4-set reference
============================
-``remote-subnet4-set`` - This command is used to create or replace an
-IPv4 subnet the configuration database.
+``remote-subnet4-set`` - creates or replaces an
+IPv4 subnet in the configuration database.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-subnet4-set>`__
+Description and examples: see :ref:`command-remote-subnet4-set`
Command syntax:
}
The provided list must contain exactly one subnet specification. The
-``shared-network-name`` parameter is required for these commands. It
+``shared-network-name`` parameter is required for these commands; it
associates the subnet with the shared network by its name. If the subnet
must not belong to any shared network (global subnet), the ``null``
value must be specified for the shared network name.
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-subnet6-del-by-id:
remote-subnet6-del-by-id reference
==================================
-``remote-subnet6-del-by-id`` - This command is used to delete an IPv6
+``remote-subnet6-del-by-id`` - deletes an IPv6
subnet by ID from the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-subnet6-del-by-id>`__
+Description and examples: see :ref:`command-remote-subnet4-del-by-id`
Command syntax:
}
}
-This command includes a list with exactly one id of the subnet to be
+This command includes a list with exactly one ID of the subnet to be
deleted.
Response syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-subnet6-del-by-prefix:
remote-subnet6-del-by-prefix reference
======================================
-``remote-subnet6-del-by-prefix`` - This command is used to delete an
+``remote-subnet6-del-by-prefix`` - deletes an
IPv6 subnet by prefix from the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-subnet6-del-by-prefix>`__
+Description and examples: see :ref:`command-remote-subnet4-del-by-prefix`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-remote-subnet6-get-by-id:
remote-subnet6-get-by-id reference
==================================
-``remote-subnet6-get-by-id`` - This command is used to fetch selected
+``remote-subnet6-get-by-id`` - fetches a selected
IPv6 subnet by ID for the server from the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-subnet6-get-by-id>`__
+Description and examples: see :ref:`command-remote-subnet4-get-by-id`
Command syntax:
}
}
-This command includes a list with exactly one id of the subnet to be
+This command includes a list with exactly one ID of the subnet to be
returned.
Response syntax:
If the shared network name is null, it means that the returned subnet
does not belong to any shared network (global subnet). The metadata is
-included in the returned subnet definition and it provides database
-specific information associated with the returned object.
+included in the returned subnet definition and provides
+database-specific information associated with the returned object.
.. _reference-remote-subnet6-get-by-prefix:
remote-subnet6-get-by-prefix reference
======================================
-``remote-subnet6-get-by-prefix`` - This command is used to fetch
+``remote-subnet6-get-by-prefix`` - fetches a
selected IPv6 subnet by prefix from the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See
-`??? <#command-remote-subnet6-get-by-prefix>`__
+Description and examples: see :ref:`command-remote-subnet4-get-by-prefix`
Command syntax:
If the shared network name is null, it means that the returned subnet
does not belong to any shared network (global subnet). The metadata is
-included in the returned subnet definition and it provides database
-specific information associated with the returned object.
+included in the returned subnet definition and provides
+database-specific information associated with the returned object.
.. _reference-remote-subnet6-list:
remote-subnet6-list reference
=============================
-``remote-subnet6-list`` - This command is used to fetch a list of all
+``remote-subnet6-list`` - fetches a list of all
IPv6 subnets from the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-subnet6-list>`__
+Description and examples: see :ref:`command-remote-subnet4-list`
Command syntax:
}
The returned response contains a list of maps. Each map contains a
-subnet identifier, prefix and shared network name to which the subnet
-belongs. If the subnet does not belong to a shared netork the name is
-null. The metadata includes database specific information associated
+subnet identifier, prefix, and shared network name to which the subnet
+belongs. If the subnet does not belong to a shared network, the name is
+null. The metadata includes database-specific information associated
with the subnets. The returned list does not contain full subnet
-definitions. Use ``remote-subnet6-get`` to fetch the full information
+definitions; use ``remote-subnet6-get`` to fetch the complete information
about the selected subnets.
.. _reference-remote-subnet6-set:
remote-subnet6-set reference
============================
-``remote-subnet6-set`` - This command is used to create or replace an
-IPv4 subnet the configuration database.
+``remote-subnet6-set`` - creates or replaces an
+IPv4 subnet in the configuration database.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`cb_cmds <#commands-cb_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
-Description and examples: See `??? <#command-remote-subnet6-set>`__
+Description and examples: see :ref:`command-remote-subnet4-set`
Command syntax:
}
The provided list must contain exactly one subnet specification. The
-``shared-network-name`` parameter is required for these commands. It
+``shared-network-name`` parameter is required for these commands; it
associates the subnet with the shared network by its name. If the subnet
must not belong to any shared network (global subnet), the ``null``
value must be specified for the shared network name.
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-reservation-add:
=========================
``reservation-add`` - adds a new host reservation. The reservation may
-include IPv4 address, IPv6 addresses, IPv6 prefixes, various
+include an IPv4 address, IPv6 addresses, IPv6 prefixes, various
identifiers, a class the client will be assigned to, DHCPv4 and DHCPv6
-options and more.
+options, and more.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.2.0 (`host_cmds <#commands-host_cmds-lib>`__ hook)
+Availability: 1.2.0 (:ref:`The Host Commands hooks library<commands-host_cmds-lib>`)
-Description and examples: See `??? <#command-reservation-add>`__
+Description and examples: see :ref:`command-reservation-add`
Command syntax:
"duid": <string>,
"flex-id": <string>,
"ip-address": <string (IPv4 address)>,
- "ip-addresses": [ <comma separated strings> ],
+ "ip-addresses": [ <comma-separated strings> ],
"hw-address": <string>,
"hostname": <string>,
"next-server": <string (IPv4 address)>,
- "option-data-list": [ <comma separated structures defining options> ],
- "prefixes": [ <comma separated IPv6 prefixes> ],
- "reservation-client-classes": [ <comma separated strings> ],
+ "option-data-list": [ <comma-separated structures defining options> ],
+ "prefixes": [ <comma-separated IPv6 prefixes> ],
+ "reservation-client-classes": [ <comma-separated strings> ],
"server-hostname": <string>,
"subnet-id": <integer>,
"user-context": <any valid JSON>,
}
}
-Note the ip-address, client-id, next-server, server-hostname and
-boot-file-name are IPv4 specific. duid, ip-addresses and prefixes are
-IPv6 specific.
+Note that ip-address, client-id, next-server, server-hostname, and
+boot-file-name are IPv4-specific. duid, ip-addresses, and prefixes are
+IPv6-specific.
Response syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-reservation-del:
reservation-del reference
=========================
-``reservation-del`` - Deletes an existing host reservation.
+``reservation-del`` - deletes an existing host reservation.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.2.0 (`host_cmds <#commands-host_cmds-lib>`__ hook)
+Availability: 1.2.0 (:ref:`The Host Commands hooks library<commands-host_cmds-lib>`)
-Description and examples: See `??? <#command-reservation-del>`__
+Description and examples: see :ref:`command-reservation-del`
Command syntax:
}
}
-The host reservation can be identified by either (subnet-id, ip-address)
+The host reservation can be identified by either the (subnet-id, ip-address)
pair or a triplet of (subnet-id, identifier-type, identifier).
Response syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-reservation-get:
reservation-get reference
=========================
-``reservation-get`` - Attempts to retrieve an existing host reservation
+``reservation-get`` - attempts to retrieve an existing host reservation.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.2.0 (`host_cmds <#commands-host_cmds-lib>`__ hook)
+Availability: 1.2.0 (:ref:`The Host Commands hooks library<commands-host_cmds-lib>`)
-Description and examples: See `??? <#command-reservation-get>`__
+Description and examples: see :ref:`command-reservation-get`
Command syntax:
}
}
-The host reservation can be identified by either (subnet-id, ip-address)
+The host reservation can be identified by either a (subnet-id, ip-address)
pair or a triplet of (subnet-id, identifier-type, identifier).
Response syntax:
"duid": <string>,
"flex-id": <string>,
"ip-address": <string (IPv4 address)>,
- "ip-addresses": [ <comma separated strings> ],
+ "ip-addresses": [ <comma-separated strings> ],
"hw-address": <string>,
"hostname": <string>,
"next-server": <string (IPv4 address)>,
- "option-data-list": [ <comma separated structures defining options> ],
- "prefixes": [ <comma separated IPv6 prefixes> ],
- "reservation-client-classes": [ <comma separated strings> ],
+ "option-data-list": [ <comma-separated structures defining options> ],
+ "prefixes": [ <comma-separated IPv6 prefixes> ],
+ "reservation-client-classes": [ <comma-separated strings> ],
"server-hostname": <string>,
"subnet-id": <integer>,
"user-context": <any valid JSON>,
}
}
-Arguments object appear only if a host is found. Many fields in the
-arguments object appear only if specific field is set.
+The arguments object appears only if a host is found. Many fields in the
+arguments object appear only if a specific field is set.
.. _reference-reservation-get-all:
reservation-get-all reference
=============================
-``reservation-get-all`` - Retrieve all host reservations for a specified
+``reservation-get-all`` - retrieves all host reservations for a specified
subnet.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.6.0 (`host_cmds <#commands-host_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Host Commands hooks library<commands-host_cmds-lib>`)
-Description and examples: See `??? <#command-reservation-get-all>`__
+Description and examples: see :ref:`command-reservation-get-all`
Command syntax:
"text": <string>
}
-reservation-get-all command may result in very large responses.
+The ``reservation-get-all`` command may result in very large responses.
.. _reference-reservation-get-page:
reservation-get-page reference
==============================
-``reservation-get-page`` - Retrieve host reservations for a specified
+``reservation-get-page`` - retrieves host reservations for a specified
subnet by page.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
-Availability: 1.6.0 (`host_cmds <#commands-host_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Host Commands hooks library<commands-host_cmds-lib>`)
-Description and examples: See `??? <#command-reservation-get-page>`__
+Description and examples: see :ref:`command-reservation-get-page`
Command syntax:
}
}
-the subnet id and the page size limit are mandatory. The source index
-and from host id are optional and default to 0. Values to use to next
-the next page are returned in responses in a next map.
+The "subnet-id" and the "limit" arguments are mandatory. The "limit"
+specifies the maximum number of host reservations to be returned, and
+the "source-index" and "from" arguments should be set to 0 when retrieving
+the first page of host reservations (if they are not specified, they will
+default to 0). To fetch subsequent pages of host reservations, the returned
+values of "source-index" and "from" must be copied from the previous response.
Response syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-shutdown:
shutdown reference
==================
-``shutdown`` - The shutdown command instructs the server to initiate its
+``shutdown`` - instructs the server to initiate its
shutdown procedure.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
Availability: 1.0.0 (built-in)
-Description and examples: See `??? <#command-shutdown>`__
+Description and examples: see :ref:`command-shutdown`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-stat-lease4-get:
stat-lease4-get reference
=========================
-``stat-lease4-get`` - The stat-lease4-get command fetches lease
+``stat-lease4-get`` - fetches lease
statistics for a range of known IPv4 subnets.
Supported by: ``kea-dhcp4``
-Availability: 1.4.0 (`stat_cmds <#commands-stat_cmds-lib>`__ hook)
+Availability: 1.4.0 (:ref:`The Supplemental Statistics Commands hooks library<commands-stat_cmds-lib>`)
-Description and examples: See `??? <#command-stat-lease4-get>`__
+Description and examples: see :ref:`command-stat-lease4-get`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-stat-lease6-get:
stat-lease6-get reference
=========================
-``stat-lease6-get`` - The stat-lease6-get command fetches lease
+``stat-lease6-get`` - fetches lease
statistics for a range of known IPv6 subnets.
Supported by: ``kea-dhcp6``
-Availability: 1.4.0 (`stat_cmds <#commands-stat_cmds-lib>`__ hook)
+Availability: 1.4.0 (:ref:`The Supplemental Statistics Commands hooks library<commands-stat_cmds-lib>`)
-Description and examples: See `??? <#command-stat-lease6-get>`__
+Description and examples: see :ref:`command-stat-lease4-get`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-statistic-get:
statistic-get reference
=======================
-``statistic-get`` - The statistic-get command retrieves a single
-statistic. It takes a single string parameter called name that specifies
+``statistic-get`` - retrieves a single
+statistic. It takes a single string parameter, called "name", that specifies
the statistic name.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
Availability: 1.0.0 (built-in)
-Description and examples: See `??? <#command-statistic-get>`__
+Description and examples: see :ref:`command-statistic-get`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-statistic-get-all:
statistic-get-all reference
===========================
-``statistic-get-all`` - The statistic-get-all command retrieves all
-statistics recorded.
+``statistic-get-all`` - retrieves all statistics recorded.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
Availability: 1.0.0 (built-in)
-Description and examples: See `??? <#command-statistic-get-all>`__
+Description and examples: see :ref:`command-statistic-get-all`
Command syntax:
"arguments": { }
}
-The server will respond with details of all recorded statistics, with
-result set to 0 indicating that it iterated over all statistics (even
+The server will respond with details of all recorded statistics, with a
+result of 0 indicating that it iterated over all statistics (even
when the total number of statistics is zero).
Response syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-statistic-remove:
statistic-remove reference
==========================
-``statistic-remove`` - The statistic-remove command attempts to delete a
-single statistic. It takes a single string parameter called name that
+``statistic-remove`` - attempts to delete a
+single statistic. It takes a single string parameter, called "name", that
specifies the statistic name.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
Availability: 1.0.0 (built-in)
-Description and examples: See `??? <#command-statistic-remove>`__
+Description and examples: see :ref:`command-statistic-remove`
Command syntax:
}
If the specific statistic is found and its removal was successful, the
-server will respond with a status of 0, indicating success and an empty
-parameters field. If an error is encountered (e.g. requested statistic
+server will respond with a status of 0, indicating success, and an empty
+parameters field. If an error is encountered (e.g. the requested statistic
was not found), the server will return a status code of 1 (error) and
the text field will contain the error description.
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-statistic-remove-all:
statistic-remove-all reference
==============================
-``statistic-remove-all`` - The statistic-remove-all command attempts to
+``statistic-remove-all`` - attempts to
delete all statistics.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
Availability: 1.0.0 (built-in)
-Description and examples: See `??? <#command-statistic-remove-all>`__
+Description and examples: see :ref:`command-statistic-remove-all`
Command syntax:
}
If the removal of all statistics was successful, the server will respond
-with a status of 0, indicating success and an empty parameters field. If
+with a status of 0, indicating success, and an empty parameters field. If
an error is encountered, the server will return a status code of 1
(error) and the text field will contain the error description.
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-statistic-reset:
statistic-reset reference
=========================
-``statistic-reset`` - The statistic-reset command sets the specified
+``statistic-reset`` - sets the specified
statistic to its neutral value: 0 for integer, 0.0 for float, 0h0m0s0us
-for time duration and "" for string type. It takes a single string
-parameter called name that specifies the statistic name.
+for time duration, and "" for string type. It takes a single string
+parameter, called "name", that specifies the statistic name.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
Availability: 1.0.0 (built-in)
-Description and examples: See `??? <#command-statistic-reset>`__
+Description and examples: see :ref:`command-statistic-reset`
Command syntax:
}
}
-If the specific statistic is found and reset was successful, the server
-will respond with a status of 0, indicating success and an empty
-parameters field. If an error is encountered (e.g. requested statistic
+If the specific statistic is found and the reset was successful, the server
+will respond with a status of 0, indicating success, and an empty
+parameters field. If an error is encountered (e.g. the requested statistic
was not found), the server will return a status code of 1 (error) and
the text field will contain the error description.
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-statistic-reset-all:
statistic-reset-all reference
=============================
-``statistic-reset-all`` - The statistic-reset command sets all
+``statistic-reset-all`` - sets all
statistics to their neutral values: 0 for integer, 0.0 for float,
-0h0m0s0us for time duration and "" for string type.
+0h0m0s0us for time duration, and "" for string type.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``
Availability: 1.0.0 (built-in)
-Description and examples: See `??? <#command-statistic-reset-all>`__
+Description and examples: see :ref:`command-statistic-reset-all`
Command syntax:
}
If the operation is successful, the server will respond with a status of
-0, indicating success and an empty parameters field. If an error is
+0, indicating success, and an empty parameters field. If an error is
encountered, the server will return a status code of 1 (error) and the
text field will contain the error description.
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-subnet4-add:
subnet4-add reference
=====================
-``subnet4-add`` - This command is used to create and add a new subnet to
+``subnet4-add`` - creates and adds a new subnet to
the existing server configuration.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-subnet4-add>`__
+Description and examples: see :ref:`command-subnet4-add`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-subnet4-del:
subnet4-del reference
=====================
-``subnet4-del`` - This command is used to remove a subnet from the
+``subnet4-del`` - removes a subnet from the
server's configuration. This command has no effect on other configured
-subnets but removing a subnet has certain implications which the
-server's administrator should be aware of.
+subnets, but administrators should exercise caution when
+using this command as removing a subnet may have unintended consequences.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-subnet4-del>`__
+Description and examples: see :ref:`command-subnet4-del`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-subnet4-get:
subnet4-get reference
=====================
-``subnet4-get`` - This command is used to retrieve detailed information
+``subnet4-get`` - retrieves detailed information
about the specified subnet. This command usually follows the
-subnet4-list, which is used to discover available subnets with their
+``subnet4-list`` command, which is used to discover available subnets with their
respective subnet identifiers and prefixes.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-subnet4-get>`__
+Description and examples: see :ref:`command-subnet4-get`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-subnet4-list:
subnet4-list reference
======================
-``subnet4-list`` - This command is used to list all currently configured
+``subnet4-list`` - lists all currently configured
subnets. The subnets are returned in a brief form, i.e. a subnet
-identifier and subnet prefix is included for each subnet.
+identifier and subnet prefix are included for each subnet.
Supported by: ``kea-dhcp4``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-subnet4-list>`__
+Description and examples: see :ref:`command-subnet4-list`
Command syntax:
subnet4-update reference
========================
-``subnet4-update`` - This command is used to update a subnet in the
+``subnet4-update`` - updates a subnet in the
existing server configuration.
Supported by: ``kea-dhcp4``
-Availability: 1.6.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-subnet4-update>`__
+Description and examples: see :ref:`command-subnet4-update`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-subnet6-add:
subnet6-add reference
=====================
-``subnet6-add`` - This command is used to create and add new subnet to
+``subnet6-add`` - creates and adds a new subnet to
the existing server configuration. This operation has no impact on other
subnets.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-subnet6-add>`__
+Description and examples: see :ref:`command-subnet6-add`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-subnet6-del:
subnet6-del reference
=====================
-``subnet6-del`` - This command is used to remove a subnet from the
+``subnet6-del`` - removes a subnet from the
server's configuration. This command has no effect on other configured
-subnets but removing a subnet has certain implications which the
-server's administrator should be aware of.
+subnets, but administrators should exercise caution when
+using this command as removing a subnet may have unintended consequences.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-subnet6-del>`__
+Description and examples: see :ref:`command-subnet6-del`
Command syntax:
]
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-subnet6-get:
subnet6-get reference
=====================
-``subnet6-get`` - This command is used to retrieve detailed information
+``subnet6-get`` - retrieves detailed information
about the specified subnet. This command usually follows the
-subnet6-list, which is used to discover available subnets with their
+``subnet6-list`` command, which is used to discover available subnets with their
respective subnet identifiers and prefixes.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-subnet6-get>`__
+Description and examples: see :ref:`command-subnet6-get`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-subnet6-list:
subnet6-list reference
======================
-``subnet6-list`` - This command is used to list all currently configured
+``subnet6-list`` - lists all currently configured
subnets. The subnets are returned in a brief form, i.e. a subnet
-identifier and subnet prefix is included for each subnet.
+identifier and subnet prefix are included for each subnet.
Supported by: ``kea-dhcp6``
-Availability: 1.3.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-subnet6-list>`__
+Description and examples: see :ref:`command-subnet6-list`
Command syntax:
subnet6-update reference
========================
-``subnet6-update`` - This command is used to update a subnet in the
+``subnet6-update`` - updates a subnet in the
existing server configuration. This operation has no impact on other
subnets.
Supported by: ``kea-dhcp6``
-Availability: 1.6.0 (`subnet_cmds <#commands-subnet_cmds-lib>`__ hook)
+Availability: 1.6.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
-Description and examples: See `??? <#command-subnet6-update>`__
+Description and examples: see :ref:`command-subnet6-update`
Command syntax:
}
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _reference-version-get:
version-get reference
=====================
-``version-get`` - The version-get command returns extended information
-about Kea version. The returned string is the same as if Kea would be
-run with -V command line option.
+``version-get`` - returns extended information
+about the Kea version in operation. The returned string is the same as if Kea were
+run with the -V command-line option.
Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
``kea-ctrl-agent``
Availability: 1.2.0 (built-in)
-Description and examples: See `??? <#command-version-get>`__
+Description and examples: see :ref:`command-version-get`
Command syntax:
"text": <string>
}
-Result is an integer representation of the status. Currently supported
+The result is an integer representation of the status. Currently supported
statuses are:
- 0 - success
- 2 - unsupported
-- 3 - empty (command was completed successfully, but no data was
+- 3 - empty (command was completed successfully, but no data were
affected or returned)
.. _classification-using-vendor:
Built-in Client Classes
-======================
+=======================
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
-it does, the content of that option is prepended with "VENDOR_CLASS_"
+it does, the content of that option is prepended with "VENDOR_CLASS\_"
and the result is interpreted as a class. For example, modern cable
modems send this option with value "docsis3.0", so the packet belongs to
class "VENDOR_CLASS_docsis3.0".
-The "HA_" prefix is used by the High Availability hooks library to
+The "HA\_" prefix is used by the High Availability hooks library to
designate certain servers to process DHCP packets as a result of load
-balancing. The class name is constructed by prepending the "HA_" prefix
+balancing. The class name is constructed by prepending the "HA\_" prefix
to the name of the server which should process the DHCP packet. This
server uses an appropriate pool or subnet to allocate IP addresses
(and/or prefixes), based on the assigned client classes. The details can
capital letters.
Currently recognized built-in class names are ALL, KNOWN and UNKNOWN, and the
-prefixes VENDOR_CLASS_, HA_, AFTER_, and EXTERNAL_. Although the AFTER\_
+prefixes VENDOR_CLASS\_, HA\_, AFTER\_, and EXTERNAL\_. Although the AFTER\_
prefix is a provision for an as-yet-unwritten hook, the EXTERNAL\_
prefix can be freely used; built-in classes are implicitly defined so
they never raise warnings if they do not appear in the configuration.
- "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
- built-in, i.e., beginning by "VENDOR_CLASS_", "AFTER__" (for the
- to-come "after" hook) and "EXTERNAL_" or equal to "ALL", "KNOWN",
+ built-in, i.e., beginning by "VENDOR_CLASS\_", "AFTER\_" (for the
+ to-come "after" hook) and "EXTERNAL\_" or equal to "ALL", "KNOWN",
"UNKNOWN", etc.
"known" and "unknown" are shorthand for "member('KNOWN')" and "not
the expressions are overly complex, the time taken to execute them
may impact the performance of the server. Administrators who need complex or
time-consuming expressions should consider writing a
- `hook <#hooks-libraries>`__ to perform the necessary work.
+ :ref:`hook <hooks-libraries>` to perform the necessary work.
.. _classification-configuring:
better or more easily written as code. Once the hook has added the proper class name
to the packet, the rest of the classification system will work as expected
in choosing a subnet and selecting options. For a description of hooks,
-see :ref:`hooks-libraries>`__; for information on configuring classes,
+see :ref:`hooks-libraries`; for information on configuring classes,
see :ref:`classification-configuring` and :ref:`classification-subnets`.
Debugging Expressions
To understand the logging statements, it is essential to understand a bit
about how expressions are evaluated; for a more complete description,
refer to the design document at
-https://gitlab.isc.org/isc-projects/kea/wikis/design%20documents. In
+https://gitlab.isc.org/isc-projects/kea/wikis/designs/Design-documents. In
brief, there are two structures used during the evaluation of an
expression: a list of tokens which represent the expressions, and a value
stack which represents the values being manipulated.
-----------
Configuration files for the DHCPv4, DHCPv6, DDNS, Control Agent, and
-Netconf modules are defined in an extended JSON format. Basic JSON is
+NETCONF modules are defined in an extended JSON format. Basic JSON is
defined in `RFC 7159 <https://tools.ietf.org/html/rfc7159>`__ and `ECMA
404 <https://www.ecma-international.org/publications/standards/Ecma-404.htm>`__.
In particular, the only boolean values allowed are true or false (all
invalid for any reason, the server may refuse to start, which will
further extend the downtime period until the issue is resolved.
-To avoid such problems, the DHCPv4, DHCPv6 and D2 servers in Kea include
+To avoid such problems, the DHCPv4, DHCPv6, and D2 servers in Kea include
support for a mechanism that allows online reconfiguration without
requiring server shutdown. Both servers can be instructed to open
control sockets, which is a communications channel. The server is able
to receive commands on that channel, act on them, and report back
status.
-The DHCPv4, DHCPv6 and D2 servers receive commands over the UNIX domain
-sockets. The details how to configure these sockets, see
-`??? <#dhcp4-ctrl-channel>`__ and `??? <#dhcp6-ctrl-channel>`__. While
-it is possible to control the servers directly using unix domain sockets
-it requires that the controlling client be running on the same machine
+The DHCPv4, DHCPv6, and D2 servers receive commands over the UNIX domain
+sockets. For details on how to configure these sockets, see
+:ref:`dhcp4-ctrl-channel` and :ref:`dhcp6-ctrl-channel`. While
+it is possible to control the servers directly using UNIX domain sockets,
+that requires that the controlling client be running on the same machine
as the server. SSH is usually used to connect remotely to the controlled
machine.
Network administrators usually prefer using some form of a RESTful API
to control the servers, rather than using UNIX domain sockets directly.
-Therefore, Kea includes a component called Control Agent (or CA), which
+Therefore, Kea includes a component called the Control Agent (or CA), which
exposes a RESTful API to the controlling clients and can forward
commands to the respective Kea services over the UNIX domain sockets.
-The CA configuration has been described in
-`??? <#agent-configuration>`__.
+The CA configuration is described in
+:ref:`agent-configuration`.
The HTTP requests received by the CA contain the control commands
encapsulated within HTTP requests. Simply speaking, the CA is
will try to handle it on its own.
Control connections over both HTTP and UNIX domain sockets are guarded
-with timeouts. The default timeout value is set to 10s and is not
+with timeouts. The default timeout value is set to 10 seconds and is not
configurable.
.. _ctrl-channel-syntax:
}
``command`` is the name of the command to execute and is mandatory.
-``arguments`` is a map of parameters required to carry out the given
-command. The exact content and format of the map is command-specific.
+``arguments`` is a map of the parameters required to carry out the given
+command. The exact content and format of the map are command-specific.
``service`` is a list of the servers at which the control command is
targeted. In the example above, the control command is targeted at the
parameter or this list is empty, the CA simply processes this message on
its own. For example, a ``config-get`` command which includes no service
parameter returns the Control Agent's own configuration. The
-``config-get`` with a service value "dhcp4" is forwarded to the DHCPv4
+``config-get`` command with a service value "dhcp4" is forwarded to the DHCPv4
server and returns the DHCPv4 server's configuration.
The following list shows the mapping of the values carried within the
**Note**
- When sending commands via Control Agent, it is possible to specify
+ When sending commands via the Control Agent, it is possible to specify
multiple services at which the command is targeted. CA forwards this
command to each service individually. Thus, the CA response to the
controlling client contains an array of individual responses.
The easiest way to start interacting with the control API is to use
common UNIX/Linux tools such as ``socat`` and ``curl``.
-In order to control the given Kea service via UNIX domain socket, use
+In order to control the given Kea service via a UNIX domain socket, use
``socat`` in interactive mode as follows:
::
$ socat UNIX:/path/to/the/kea/socket -
or in batch mode, include the "ignoreeof" option as shown below to
-ensure socat waits long enough for the server to respond:
+ensure ``socat`` waits long enough for the server to respond:
::
It is also easy to open a UNIX socket programmatically. An example of a
simple client written in C is available in the Kea Developer's Guide, in
-the Control Channel Overview chapter, in the Using Control Channel
+the Control Channel Overview chapter, in the
+`Using Control Channel <https://jenkins.isc.org/job/Kea_doc/doxygen/d2/d96/ctrlSocket.html#ctrlSocketClient>`__
section.
-To use Kea's RESTful API with ``curl``, you may use the following:
+To use Kea's RESTful API with ``curl``, use the following:
::
.. _command-build-report:
-build-report
-------------
+The build-report Command
+------------------------
-The *build-report* command returns on the control channel what the
+The ``build-report`` command returns on the control channel what the
command line ``-W`` argument displays, i.e. the embedded content of the
``config.report`` file. This command does not take any parameters.
.. _command-config-get:
-config-get
-----------
+The config-get Command
+----------------------
-The *config-get* command retrieves the current configuration used by the
+The ``config-get`` command retrieves the current configuration used by the
server. This command does not take any parameters. The configuration
returned is roughly equal to the configuration that was loaded using the
--c command line option during server start-up or later set using
-config-set command. However, there may be certain differences, as
+-c command line option during server start-up or later set using the
+``config-set`` command. However, there may be certain differences, as
comments are not retained. If the original configuration used file
inclusion, the returned configuration will include all parameters from
all the included files.
.. _command-config-reload:
-config-reload
--------------
+The config-reload Command
+-------------------------
-The *config-reload* command instructs Kea to load again the
+The ``config-reload`` command instructs Kea to load again the
configuration file that was used previously. This operation is useful if
the configuration file has been changed by some external source; for
example, a sysadmin can tweak the configuration file and use this
command to force Kea pick up the changes.
-Caution should be taken when mixing this with config-set commands. Kea
+Caution should be taken when mixing this with ``config-set`` commands. Kea
remembers the location of the configuration file it was started with,
-and this configuration can be significantly changed using config-set
-command. When config-reload is issued after config-set, Kea will attempt
+and this configuration can be significantly changed using the ``config-set``
+command. When ``config-reload`` is issued after ``config-set``, Kea will attempt
to reload its original configuration from the file, possibly losing all
-changes introduced using config-set or other commands.
+changes introduced using ``config-set`` or other commands.
-*config-reload* does not take any parameters. An example command
+``config-reload`` does not take any parameters. An example command
invocation looks like this:
::
.. _command-config-test:
-config-test
------------
+The config-test Command
+-----------------------
-The *config-test* command instructs the server to check whether the new
+The ``config-test`` command instructs the server to check whether the new
configuration supplied in the command's arguments can be loaded. The
supplied configuration is expected to be the full configuration for the
target server, along with an optional Logger configuration. As for the
-``-t`` command, some sanity checks are not performed so it is possible a
+``-t`` command, some sanity checks are not performed, so it is possible a
configuration which successfully passes this command will still fail in
the ``config-set`` command or at launch time. The structure of the
command is as follows:
.. _command-config-write:
-config-write
-------------
+The config-write Command
+------------------------
-The *config-write* command instructs the Kea server to write its current
-configuration to a file on disk. It takes one optional argument called
-*filename* that specifies the name of the file to write the
+The ``config-write`` command instructs the Kea server to write its current
+configuration to a file on disk. It takes one optional argument, called
+"filename", that specifies the name of the file to write the
configuration to. If not specified, the name used when starting Kea
(passed as a -c argument) will be used. If a relative path is specified,
Kea will write its files only in the directory it is running.
.. _command-leases-reclaim:
-leases-reclaim
---------------
+The leases-reclaim Command
+--------------------------
-The *leases-reclaim* command instructs the server to reclaim all expired
+The ``leases-reclaim`` command instructs the server to reclaim all expired
leases immediately. The command has the following JSON syntax:
::
}
}
-The *remove* boolean parameter is mandatory and indicates whether the
+The ``remove`` boolean parameter is mandatory and indicates whether the
reclaimed leases should be removed from the lease database (if true), or
-left in the *expired-reclaimed* state (if false). The latter facilitates
+left in the "expired-reclaimed" state (if false). The latter facilitates
lease affinity, i.e. the ability to re-assign an expired lease to the
-same client which used this lease before. See `??? <#lease-affinity>`__
-for the details. Also, see `??? <#lease-reclamation>`__ for general
-information about the processing of expired leases (leases reclamation).
+same client that used this lease before. See :ref:`lease-affinity`
+for the details. Also, see :ref:`lease-reclamation` for general
+information about the processing of expired leases (lease reclamation).
.. _command-libreload:
-libreload
----------
+The libreload Command
+---------------------
-The *libreload* command first unloads and then loads all currently
-loaded hook libraries. This is primarily intended to allow one or more
-hook libraries to be replaced with newer versions without requiring Kea
-servers to be reconfigured or restarted. Note that the hook libraries
+The ``libreload`` command first unloads and then loads all currently
+loaded hooks libraries. This is primarily intended to allow one or more
+hooks libraries to be replaced with newer versions without requiring Kea
+servers to be reconfigured or restarted. Note that the hooks libraries
are passed the same parameter values (if any) that were passed when they
originally loaded.
.. _command-list-commands:
-list-commands
--------------
+The list-commands Command
+-------------------------
-The *list-commands* command retrieves a list of all commands supported
+The ``list-commands`` command retrieves a list of all commands supported
by the server. It does not take any arguments. An example command may
look like this:
.. _command-config-set:
-config-set
-----------
+The config-set Command
+----------------------
-The *config-set* command instructs the server to replace its current
+The ``config-set`` command instructs the server to replace its current
configuration with the new configuration supplied in the command's
arguments. The supplied configuration is expected to be the full
configuration for the target server, along with an optional Logger
.. _command-shutdown:
-shutdown
---------
+The shutdown Command
+--------------------
-The *shutdown* command instructs the server to initiate its shutdown
+The ``shutdown`` command instructs the server to initiate its shutdown
procedure. It is the equivalent of sending a SIGTERM signal to the
process. This command does not take any arguments. An example command
may look like this:
.. _command-dhcp-disable:
-dhcp-disable
-------------
+The dhcp-disable Command
+------------------------
-The *dhcp-disable* command globally disables the DHCP service. The
+The ``dhcp-disable`` command globally disables the DHCP service. The
server continues to operate, but it drops all received DHCP messages.
This command is useful when the server's maintenance requires that the
server temporarily stop allocating new leases and renew existing leases.
It is also useful in failover-like configurations during a
synchronization of the lease databases at startup, or recovery after a
-failure. The optional parameter *max-period* specifies the time in
+failure. The optional parameter "max-period" specifies the time in
seconds after which the DHCP service should be automatically re-enabled,
-if the *dhcp-enable* command is not sent before this time elapses.
+if the ``dhcp-enable`` command is not sent before this time elapses.
::
.. _command-dhcp-enable:
-dhcp-enable
------------
+The dhcp-enable Command
+-----------------------
-The *dhcp-enable* command globally enables the DHCP service.
+The ``dhcp-enable`` command globally enables the DHCP service.
::
.. _command-version-get:
-version-get
------------
+The version-get Command
+-----------------------
-The *version-get* command returns extended information about the Kea
+The ``version-get`` command returns extended information about the Kea
version. It is the same information available via the ``-V``
command-line argument. This command does not take any parameters.
"command": "version-get"
}
-Commands Supported by D2 Server
-===============================
+Commands Supported by the D2 Server
+===================================
The D2 server supports only a subset of DHCPv4 / DHCPv6 server commands:
.. _agent-commands:
-Commands Supported by Control Agent
-===================================
+Commands Supported by the Control Agent
+=======================================
-The following commands listed in `Commands Supported by Both the DHCPv4
-and DHCPv6 Servers <#commands-common>`__ are also supported by the
+The following commands listed in :ref:`commands-common` are also supported by the
Control Agent, i.e. when the ``service`` parameter is blank, the
commands are handled by the CA and they relate to the CA process itself:
.. _read-only-database-configuration4:
-Using Read-Only Databases for Host Reservations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Using Read-Only Databases for Host Reservations with DHCPv4
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In some deployments the database user whose name is specified in the
database backend configuration may not have write privileges to the
2. If none, the global definition;
-3. If none, the last-resort definition described in the next section
+3. If none, the last-resort definition described in the next section,
:ref:`dhcp4-vendor-opts` (backward-compatible with previous Kea versions).
..
.. _read-only-database-configuration6:
-Using Read-Only Databases for Host Reservations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Using Read-Only Databases for Host Reservations with DHCPv6
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In some deployments the database user whose name is specified in the
database backend configuration may not have write privileges to the
}
This example shows a configuration using an automatically generated
-"VENDOR_CLASS_" class. The administrator of the network has decided that
+"VENDOR_CLASS\_" class. The administrator of the network has decided that
addresses in the range 2001:db8:1::1 to 2001:db8:1::ffff are to be
managed by the DHCP6 server and that only clients belonging to the
eRouter1.0 client class are allowed to use that pool.
freebsd:
- 11.2: virtualbox
- 12.0: virtualbox
-
+
It is also possible to run the build locally, in the current system (if the OS
is supported).
./hammer.py ssh -p virtualbox -s freebsd -r 12.0
It is possible to speed up subsequent Hammer builds. To achieve this
-Hammer employs :ref:`ccache <https://ccache.samba.org/>`. During
+Hammer employs `ccache <https://ccache.samba.org/>`__. During
compilation, ccache stores objects in a shared folder. In subsequent runs,
instead of doing an actual compilation, ccache returns the stored earlier
objects. The cache with these objects for reuse needs to be stored outside of VM
::
./hammer.py build -p lxc -s ubuntu -r 18.04 --ccache-dir ~/kea-ccache
-
+
..
Pausing HA State Machine
------------------------
-The high-availability state machine includes many different states
+The high availability state machine includes many different states
described in detail in :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
=====================================
Some database backends, such as RADIUS, are considered slow and may take
-a long time to respond. Since Kea in general is synchronous, the backend
-performance directly affects the DHCP performance. To minimize the
+a long time to respond. Since Kea in general is synchronous, backend
+performance directly affects DHCP performance. To minimize the
impact and improve performance, the Host Cache library provides a way to
cache information from the database locally. This includes negative
caching, i.e. the ability to remember that there is no client
**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.
-In principle, this hook library can be used with any backend that may
-introduce performance degradation (MySQL, PostgreSQL, Cassandra,
+In principle, this hooks library can be used with any backend that may
+introduce performance degradation (MySQL, PostgreSQL, Cassandra, or
RADIUS). Host Cache must be loaded for the RADIUS accounting mechanism
to work.
-The Host Cache hook library is currently very simple. It takes only one
-optional parameter ("maximum") that defines the maximum number of hosts
+The Host Cache hooks library is currently very simple. It takes only one
+optional parameter ("maximum"), which defines the maximum number of hosts
to be cached. If not specified, the default value of 0 is used, which
-means there is no limit. The hook library can be loaded the same way as
-any other hook library; for example, this configuration could be used:
+means there is no limit. This hooks library can be loaded the same way as
+any other hooks library; for example, this configuration could be used:
::
Once loaded, the Host Cache hook library provides a number of new
commands which can be used either over the control channel (see
-`??? <#ctrl-channel-client>`__) or the REST API (see
-`??? <#agent-overview>`__). An example REST API client is described in
-`??? <#shell-overview>`__. The following sections describe the commands
+:ref:`ctrl-channel-client`) or the RESTful API (see
+:ref:`agent-overview`). An example RESTful API client is described in
+:ref:`shell-overview`. The following sections describe the commands
available.
.. _command-cache-flush:
-cache-flush Command
--------------------
+The cache-flush Command
+-----------------------
This command allows removal of a specified number of cached host
entries. It takes one parameter, which defines the number of hosts to be
"arguments": 1000
}
-This command will remove 1000 hosts. If you want to delete all cached
+This command will remove 1000 hosts. To delete all cached
hosts, please use cache-clear instead. The hosts are stored in FIFO
order, so the oldest entries are always removed.
.. _command-cache-clear:
-cache-clear Command
--------------------
+The cache-clear Command
+-----------------------
This command allows removal of all cached host entries. An example usage
looks as follows:
"command": "cache-clear"
}
-This command will remove all hosts. If you want to delete only a certain
+This command will remove all hosts. To delete only a certain
number of cached hosts, please use cache-flush instead.
.. _command-cache-size:
-cache-size Command
-------------------
+The cache-size Command
+----------------------
This command returns the number of host entries. An example usage looks
as follows:
.. _command-cache-write:
-cache-write Command
--------------------
+The cache-write Command
+-----------------------
In general, the cache content is considered a runtime state and the
server can be shut down or restarted as usual; the cache will then be
where the cached hosts also retain additional cached RADIUS attributes;
there is no easy way to obtain this information again, because renewing
clients send their packet to the DHCP server directly. Another use case
-is when you want to restart the server and for performance reasons you
-want it to start with a hot (populated) cache.
+is when an administrator wants to restart the server and, for performance reasons,
+wants it to start with a hot (populated) cache.
This command allows writing the contents of the in-memory cache to a
file on disk. It takes one parameter, which defines the filename. An
.. _command-cache-load:
-cache-load Command
-------------------
+The cache-load Command
+----------------------
See the previous section for a discussion of use cases where it may be
useful to write and load contents of the host cache to disk.
.. _command-cache-get:
-cache-get Command
------------------
+The cache-get Command
+---------------------
This command is similar to cache-write, but instead of writing the cache
contents to disk, it returns the contents to whoever sent the command.
.. _command-cache-get-by-id:
-cache-get-by-id Command
------------------------
+The cache-get-by-id Command
+---------------------------
This command is similar to cache-get, but instead of returning the whole
content it returns only the entries matching the given identifier.
.. _command-cache-insert:
-cache-insert Command
---------------------
+The cache-insert Command
+------------------------
This command may be used to manually insert a host into the cache; there
-are very few use cases when this command could be useful. This command
+are very few use cases when this command might be useful. This command
expects its arguments to follow the usual syntax for specifying host
-reservations (see `??? <#host-reservation-v4>`__ or
-`??? <#host-reservation-v6>`__), with one difference: the subnet-id
+reservations (see :ref:`host-reservation-v4` or
+:ref:`host-reservation-v6`), with one difference: the subnet-id
value must be specified explicitly.
An example command that will insert an IPv4 host into the host cache
.. _command-cache-remove:
-cache-remove Command
---------------------
+The cache-remove Command
+------------------------
Sometimes it is useful to remove a single entry from the host cache. A
good use case is a situation where the device is up, Kea has already
provided configuration, and the host entry is in cache. As a result of
-administrative action (e.g. customer hasn't paid their bills or has
+administrative action (e.g. the customer hasn't paid their bills or has
perhaps been upgraded to better service), the information in the backend
-(e.g. MySQL or RADIUS) is being updated. However, since cache is in use,
+(e.g. MySQL or RADIUS) is being updated. However, since the cache is in use,
Kea does not notice the change as the cached values are used. The
cache-remove command can solve this problem by removing a cached entry
after administrative changes.
This library may only be loaded by the ``kea-dhcp4`` or the
``kea-dhcp6`` process.
-The major feature of the hook library is the ability to use RADIUS
+The major feature of this hooks library is the ability to use RADIUS
authorization. When a DHCP packet is received, the Kea server sends an
Access-Request to the RADIUS server and waits for a response. The server
then sends back either an Access-Accept with specific client attributes,
The second case supported is the ability to assign clients to specific
pools based on a RADIUS response. In this case, the RADIUS server sends
-back an Access-Accept with Framed-Pool (IPv4) or Framed-IPv6-Pool
+back an Access-Accept with a Framed-Pool (IPv4) or Framed-IPv6-Pool
(IPv6). In both cases, Kea interprets those attributes as client
classes. With the addition of the ability to limit access to pools to
-specific classes (see `??? <#classification-pools>`__), RADIUS can be
+specific classes (see :ref:`classification-pools`), RADIUS can be
used to force the client to be assigned a dynamic address from a
specific pool. Furthermore, the same mechanism can be used to control
what kind of options the client will get if there are DHCP options
STEP 1: Install dependencies
-Several tools are needed to build dependencies and Kea itself. The
+Several tools are needed to build the dependencies and Kea itself. The
following commands should install them:
::
$ sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
$ sudo yum install gcc-g++ openssl-devel log4cplus-devel wget git
-STEP 2: FreeRADIUS installation
+STEP 2: Install FreeRADIUS
-The Kea RADIUS hook library uses the FreeRADIUS client library to
+The Kea RADIUS hooks library uses the FreeRADIUS client library to
conduct RADIUS communication. Unfortunately, the standard 1.1.7 release
-available from the project website http://freeradius.org/sub_projects/
+available from the project website https://freeradius.org/sub_projects/
has several serious deficiencies; ISC engineers observed a segmentation
fault during testing. Also, the base version of the library does not
offer asynchronous transmissions, which are essential for effective
$ make
$ sudo make install
-You may pass additional parameters to the configure script, if you need
-to. Once installed, the FreeRADIUS client will be installed in
+Additional parameters may be passed to the configure script, if needed.
+Once installed, the FreeRADIUS client will be installed in
/usr/local. This is the default path where Kea will be looking for it.
-You may install it in a different directory; if you choose to do so,
-make sure you add that path to the configure script when compiling Kea.
+It can be installed in a different directory; if so,
+make sure to add that path to the configure script when compiling Kea.
STEP 3: Install recent BOOST version
drwxr-xr-x 10 thomson staff 340 Apr 26 19:04 src
drwxr-xr-x 14 thomson staff 476 Apr 26 19:04 tools
-The makefiles must be regenerated using autoreconf.
+The makefiles must be regenerated using ``autoreconf``.
The next step is to configure Kea, and there are several essential steps
-necessary here. Running autoreconf -if is necessary to compile the
+necessary here. Running ``autoreconf -if`` is necessary to compile the
premium package that contains RADIUS. Also, the --with-freeradius option
is necessary to tell Kea where the FreeRADIUS client sources can be
found. Also, since the non-standard Boost is used, the path to it must
Kea-shell: no
Perfdhcp: no
-Please make sure that your compilation has the following:
+Please make sure that the compilation includes the following:
- RADIUS listed in Included Hooks;
- FreeRADIUS client directories printed and pointing to the right
- Boost version at least 1.65.1. The versions available in CentOS 7
(1.48 and and 1.53) are too old.
-Once your configuration is complete, compile Kea using make. If your
-system has more than one core, it is recommended that you use the "-j N"
-option to speed up the build.
+Once the configuration is complete, compile Kea using make. If the
+system has more than one core, using the "-j N"
+option is recommended to speed up the build.
::
-------------------------
The RADIUS hook is a library that has to be loaded by either DHCPv4 or
-DHCPv6 Kea servers. Unlike some other available hook libraries, this one
+DHCPv6 Kea servers. Unlike some other available hooks libraries, this one
takes many parameters. For example, this configuration could be used:
::
}
} ]
-RADIUS is a complicated environment. As such, it's not really possible
-to provide a default configuration that would work out of the box.
+RADIUS is a complicated environment. As such, it is not feasible
+to provide a default configuration that works for everyone.
However, we do have one example that showcases some of the more common
-features. Please see doc/examples/kea4/hooks-radius.json in your Kea
+features. Please see doc/examples/kea4/hooks-radius.json in the Kea
sources.
The RADIUS hook library supports the following global configuration
flags, which correspond to FreeRADIUS client library options:
-- ``bindaddr`` (default "*") specifies the address to be used by the
- hook library in communication with RADIUS servers. The "*" special
+- ``bindaddr`` (default "*") - specifies the address to be used by the
+ hooks library in communication with RADIUS servers. The "*" special
value tells the kernel to choose the address.
-- ``canonical-mac-address`` (default false) specifies whether MAC
+- ``canonical-mac-address`` (default false) - specifies whether MAC
addresses in attributes follow the canonical RADIUS format (lowercase
pairs of hexadecimal digits separated by '-').
-- ``client-id-pop0`` (default false), used with flex-id, removes the
+- ``client-id-pop0`` (default false) - used with flex-id, removes the
leading zero (or pair of zeroes in DHCPv6) type in client-id (aka
duid in DHCPv6). Implied by client-id-printable.
-- ``client-id-printable`` (default false) checks whether the
+- ``client-id-printable`` (default false) - checks whether the
client-id/duid content is printable and uses it as is instead of in
hexadecimal. Implies client-id-pop0 and extract-duid as 0 and 255 are
not printable.
use locks or atomics, it is recommended that you do not use this
feature when running in this mode.
-- ``dictionary`` (default set by configure at build time) is the
+- ``dictionary`` (default set by configure at build time) - is the
attribute and value dictionary. Note that it is a critical parameter.
-- ``extract-duid`` (default true) extracts the embedded duid from an
+- ``extract-duid`` (default true) - extracts the embedded duid from an
RFC 4361-compliant DHCPv4 client-id. Implied by client-id-printable.
-- ``identifier-type4`` (default client-id) specifies the identifier
+- ``identifier-type4`` (default client-id) - specifies the identifier
type to build the User-Name attribute. It should be the same as the
host identifier, and when the flex-id hook library is used the
replace-client-id must be set to true; client-id will be used with
client-id-pop0.
-- ``identifier-type6`` (default duid) specifies the identifier type to
+- ``identifier-type6`` (default duid) - specifies the identifier type to
build the User-Name attribute. It should be the same as the host
identifier, and when the flex-id hook library is used the
replace-client-id must be set to true; duid will be used with
client-id-pop0.
-- ``realm`` (default "") is the default realm.
+- ``realm`` (default "") - is the default realm.
-- ``reselect-subnet-address`` (default false) uses the Kea reserved
+- ``reselect-subnet-address`` (default false) - uses the Kea reserved
address/RADIUS Framed-IP-Address or Framed-IPv6-Address to reselect
subnets where the address is not in the subnet range.
-- ``reselect-subnet-pool`` (default false) uses the Kea
+- ``reselect-subnet-pool`` (default false) - uses the Kea
client-class/RADIUS Frame-Pool to reselect subnets where no available
pool can be found.
-- ``retries`` (default 3) is the number of retries before trying the
+- ``retries`` (default 3) - is the number of retries before trying the
next server. Note that it is not supported for asynchronous
communication.
-- ``session-history`` (default "") is the name of the file providing
+- ``session-history`` (default "") - is the name of the file providing
persistent storage for accounting session history.
-- ``timeout`` (default 10) is the number of seconds during which a
+- ``timeout`` (default 10) - is the number of seconds during which a
response is awaited.
When ``reselect-subnet-pool`` or ``reselect-subnet-address`` is set to
Two services are supported:
-- ``access`` - the authentication service
+- ``access`` - the authentication service.
-- ``accounting`` - the accounting service
+- ``accounting`` - the accounting service.
Configuration of services is divided into two parts:
-- servers that define RADIUS servers the library is expected to
+- Servers that define RADIUS servers that the library is expected to
contact. Each server may have the following items specified:
- - ``name``, which specifies the IP address of the server (it is
+ - ``name`` - specifies the IP address of the server (it is
possible to use a name which will be resolved, but it is not
recommended).
- - ``port`` (default RADIUS authentication or accounting service),
- which specifies the UDP port of the server. Note that the
+ - ``port`` (default RADIUS authentication or accounting service) -
+ specifies the UDP port of the server. Note that the
FreeRADIUS client library by default uses ports 1812
(authorization) and 1813 (accounting). Some server implementations
- use 1645 (authorization) and 1646 (accounting). You may use the
- "port" parameter to adjust as needed.
+ use 1645 (authorization) and 1646 (accounting). The
+ "port" parameter may be used to adjust as needed.
- - ``secret``, which authenticates messages.
+ - ``secret`` - authenticates messages.
There may be up to eight servers. Note that when no server is
specified, the service is disabled.
-- attributes which define additional information that the Kea server
+- Attributes which define additional information that the Kea server
will send to a RADIUS server. The parameter must be identified either
by a name or type. Its value can be specified in one of three
possible ways: data (which defines a plain text value), raw (which
defines the value in hex), or expr (which defines an expression,
which will be evaluated for each incoming packet independently).
- - ``name`` of the attribute.
+ - ``name`` - the name of the attribute.
- - ``type`` of the attribute. Either the type or the name must be
+ - ``type`` - the type of the attribute. Either the type or the name must be
provided, and the attribute must be defined in the dictionary.
- - ``data`` is the first of three ways to specify the attribute
+ - ``data`` - the first of three ways to specify the attribute
content. The data entry is parsed by the FreeRADIUS library, so
values defined in the dictionary of the attribute may be used.
- - ``raw`` is the second of three ways to specify the attribute
+ - ``raw`` - the second of three ways to specify the attribute
content; it specifies the content in hexadecimal. Note that it
does not work with integer-content attributes (date, integer, and
IPv4 address); a string-content attribute (string, IPv6 address,
and IPv6 prefix) is required.
- - ``expr`` is the last way to specify the attribute content. It
+ - ``expr`` - the last way to specify the attribute content. It
specifies an evaluation expression which must return a not-empty
string when evaluated with the DHCP query packet. Currently this
is restricted to the access service.
"data": "mysecretpassword"
},
{
- // It's also possible to specify an attribute using its type,
+ // It is also possible to specify an attribute using its type,
// rather than a name. 77 is Connect-Info. The value is specified
// using hex. Again, this is a static value. It will be sent the
// same for every packet and to every server.
}
-For the RADIUS hook library to operate properly in DHCPv4, it is
-necessary to also load the Host Cache hook library. The reason for this
+For the RADIUS hooks library to operate properly in DHCPv4,
+the Host Cache hooks library must also be loaded. The reason for this
is somewhat complex. In a typical deployment, the DHCP clients send
their packets via DHCP relay which inserts certain Relay Agent
Information options, such as circuit-id or remote-id. The values of
necessary attributes in the Access-Request message sent to the RADIUS
server. However, once the DHCP client gets its address, it then renews
by sending packets directly to the DHCP server. As a result, the relays
-are not able to insert their RAI options and the DHCP server can't send
+are not able to insert their RAI options, and the DHCP server cannot send
the Access-Request queries to the RADIUS server by using just the
information from incoming packets. Kea needs to keep the information
received during the initial Discover/Offer exchanges and use it again
later when sending accounting messages.
This mechanism is implemented based on user context in host
-reservations. (See `??? <#user-context>`__ for details about user
+reservations. (See :ref:`user-context` for details about user
context). The host cache mechanism allows the information retrieved by
RADIUS to be stored and later used for sending accounting and access
queries to the RADIUS server. In other words, the host-cache mechanism
-is mandatory, unless you do not want RADIUS communication for messages
+is mandatory, unless administrators do not want RADIUS communication for messages
other than Discover and the first Request from each client.
**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 commands currently provided by this library are:
-- ``stat-lease4-get`` - fetches DHCPv4 lease statistics
+- ``stat-lease4-get`` - fetches DHCPv4 lease statistics.
-- ``stat-lease6-get`` - fetches DHCPv6 lease statistics
+- ``stat-lease6-get`` - fetches DHCPv6 lease statistics.
-The Stat commands library is part of the open source code and is
+The stat 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 directly to the servers
-via either the control channel (see `??? <#ctrl-channel>`__) or the
-Control Agent (see `??? <#kea-ctrl-agent>`__).
+via either the control channel (see :ref:`ctrl-channel`) or the
+Control Agent (see :ref:`kea-ctrl-agent`).
-This library may be loaded by both kea-dhcp4 and kea-dhcp6 servers. It
+This library may be loaded by both the kea-dhcp4 and kea-dhcp6 servers. It
is loaded in the same way as other libraries and currently has no
parameters:
::
- "Dhcp6": {
+ "Dhcp6": {
"hooks-libraries": [
{
"library": "/path/libdhcp_stat_cmds.so"
}
...
- ]
+ ]
}
In a deployment with multiple Kea DHCP servers sharing a common lease
-storage, it may be loaded by any or all of the servers. However, one
+storage, this hooks library may be loaded by any or all of the servers. However, one
thing to keep in mind is that a server's response to a
-stat-lease{4/6}-get command will only contain data for subnets known to
+stat-lease[46]-get command will only contain data for subnets known to
that server. In other words, if a subnet does not appear in a server's
configuration, Kea will not retrieve statistics for it.
.. _command-stat-lease4-get:
-stat-lease4-get, stat-lease6-get Commands
------------------------------------------
+The stat-lease4-get, stat-lease6-get Commands
+---------------------------------------------
The ``stat-lease4-get`` and ``stat-lease6-get`` commands fetch lease
statistics for a range of known subnets. The range of subnets is
determined through the use of optional command input parameters:
-- ``subnet-id`` - The ID of the subnet for which lease statistics
+- ``subnet-id`` - the ID of the subnet for which lease statistics
should be fetched. Use this to get statistics for a single subnet. If
the subnet does not exist, the command result code is 3 (i.e.
CONTROL_RESULT_EMPTY).
-- ``subnet-range`` - A pair of subnet IDs which describe an inclusive
+- ``subnet-range`` - a pair of subnet IDs which describe an inclusive
range of subnets for which statistics should be retrieved. The range
- may include one or more IDs that correspond to no subnet: in this
+ may include one or more IDs that correspond to no subnet; in this
case, the command will only output lease statistics for those that
exist. However, if the range does not include any known subnets, the
command result code is 3 (i.e. CONTROL_RESULT_EMPTY).
- - ``first-subnet-id`` - The ID of the first subnet in the range.
+ - ``first-subnet-id`` - the ID of the first subnet in the range.
- - ``last-subnet-id`` - The ID of the last subnet in the range.
+ - ``last-subnet-id`` - the ID of the last subnet in the range.
The use of subnet-id and subnet-range are mutually exclusive. If no
parameters are given, the result will contain data for all known
- ``0`` - the command was successful;
- - ``1`` - an error occurred, an explanation will be the "text"
- element;
+ - ``1`` - an error occurred, and an explanation will be the "text"
+ element; or
- - ``2`` - the fetch found no matching data
+ - ``2`` - the fetch found no matching data.
- ``text`` - an explanation of the command outcome. When the command
succeeds it will contain the command name along with the number of
the element "result-set", which is patterned after SQL statement
responses:
- - ``columns`` - a list of text column labels The columns returned
+ - ``columns`` - a list of text column labels. The columns returned
for DHCPv4 are:
- - ``subnet-id`` - ID of the subnet.
+ - ``subnet-id`` - the ID of the subnet.
- - ``total-addresses`` - total number of addresses available for
+ - ``total-addresses`` - the total number of addresses available for
DHCPv4 management in the subnet. In other words, this is the
sum of all addresses in all the configured pools in the subnet.
- - ``assigned-addresses`` - number of addresses in the subnet that
+ - ``assigned-addresses`` - the number of addresses in the subnet that
are currently assigned to a client.
- - ``declined-addresses`` - number of addresses in the subnet that
+ - ``declined-addresses`` - the number of addresses in the subnet that
are currently declined and are thus unavailable for assignment.
- The columns returned for DHCPv6 are:
- - ``subnet-id`` - ID of the subnet.
+ - ``subnet-id`` - the ID of the subnet.
- - ``total-nas`` - number of NA addresses available for DHCPv6
+ - ``total-nas`` - the number of NA addresses available for DHCPv6
management in the subnet. In other words, this is the sum of
- all the NA addresses in the all configured NA pools in the
+ all the NA addresses in all the configured NA pools in the
subnet.
- - ``assigned-nas`` - number of NA addresses in a the subnet that
+ - ``assigned-nas`` - the number of NA addresses in the subnet that
are currently assigned to a client.
- - ``declined-nas`` - number of NA addresses that are currently
+ - ``declined-nas`` - the number of NA addresses that are currently
declined and are thus unavailable for assignment.
- - ``total-pds`` - total number of prefixes available of DHCPv6
+ - ``total-pds`` - the total number of prefixes available of DHCPv6
management in the subnet. In other words, this is the sum of
all prefixes in all the configured prefix pools in the subnet.
- - ``assigned-pds`` - number of prefixes in the subnet that are
+ - ``assigned-pds`` - the number of prefixes in the subnet that are
currently assigned to a client.
- ``rows`` - a list of rows, one per subnet ID. Each row contains a
data value corresponding to and in the same order as each column
listed in "columns" for a given subnet.
- - ``timestamp`` - textual date and time the data was fetched,
+ - ``timestamp`` - the textual date and time the data were fetched,
expressed as GMT.
The response to a DHCPv4 command might look as follows:
ISC provides several additional premium hooks in the form of packages, which
follow a similar installation procedure but with several additional steps.
-For your convenience, the premium hooks installation procedure is described in this section.
+For our users' convenience, the premium hooks installation procedure is described in this section.
1. Download the package; detailed instructions are provided separately on how
to get it. The package will be a file with a name similar to
$ tar zxvf kea-KEAVERSION.tar.gz
This will unpack the tarball into the kea-KEAVERSION subdirectory of
-your current working directory.
+the current working directory.
3. Unpack the Kea premium tarball into the directory into which Kea was
unpacked. Once Kea KEAVERSION has been unpacked into a kea-KEAVERSION
directory will always be called "premium", although its contents will vary
depending on the premium package.
-4. Run autoreconf tools. This step is necessary to update Kea's build
+4. Run ``autoreconf`` tools. This step is necessary to update Kea's build
script to include the additional directory. If this tool is not already
-available on the system, install the automake and autoconf
+available on the system, install the ``automake`` and ``autoconf``
tools. To generate the configure script, please use:
::
]
}
- **Note**
+Note that care should be taken when adjusting the expression. If the expression
+changes, then all the ``flex-id`` values may change, possibly rendering
+all reservations based on ``flex-id`` unusable until they are manually updated.
+It is strongly recommended that administrators start with the expression and a
+handful of reservations, and then adjust the expression as needed. Once
+the expression is confirmed to do what is desired of it, host reservations
+can be deployed on a broader scale.
- Care should be taken when adjusting the expression. If the expression
- changes, then all the ``flex-id`` values may change, possibly rendering
- all reservations based on ``flex-id`` unusable until they are manually updated.
- It is strongly recommended that administrators start with the expression and a
- handful of reservations, and then adjust the expression as needed. Once
- the expression is confirmed to do what is desired of it, host reservations
- can be deployed on a broader scale.
-
-flex-id values in host reservations can be specified in two ways. First,
+``flex-id`` values in host reservations can be specified in two ways. First,
they can be expressed as a hex string, e.g. bar string can be represented
as 626174. Alternatively, it can be expressed as a quoted value (using
double and single quotes), e.g. "'bar'". The former is more convenient
As ``reservation-add`` is expected to store the host, the hosts-databases
parameter must be specified in the configuration and databases must not
run in read-only mode. In future versions of Kea, it will be possible to
-modify the reservations read from a configuration file. Please contact
-ISC if you are interested in this functionality.
+modify the reservations read from a configuration file. Interested parties are
+encouraged to contact ISC for more information on developing this functionality.
.. _command-reservation-get:
consider using ``reservation-get-page`` instead (see
:ref:`command-reservation-get-page`).
-For a reference, see :ref:`ref-reservation-get-all`.
+For a reference, see :ref:`command-reservation-get-all`.
.. _command-reservation-get-page:
-reservation-get-page command
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The reservation-get-page command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``reservation-get-page`` can be used to query the host database and
retrieve all reservations in a specified subnet by pages. This command
small deployments with few reservations, it is easier to use
``reservation-get-all`` (see :ref:`command-reservation-get-all`.
-For a reference, see :ref:`ref-reservation-get-page`.
-
**Note**
Currently ``reservation-get-page`` is not supported by the Cassandra
.. _user-context:
-User contexts
+User Contexts
=============
-Hook libraries can have their own configuration parameters. That is
+Hooks libraries can have their own configuration parameters, which is
convenient if the parameter applies to the whole library. However,
-sometimes it is very useful if certain configuration entities are
-extended with additional configuration data. This is where the concept
-of user contexts comes in. A sysadmin can define an arbitrary set of
-data and attach it to Kea structures, as long as the data is specified
-as JSON map. In particular, it is possible to define fields that are
-integers, strings, boolean, lists and maps. It is possible to define
+sometimes it is very useful to extend certain configuration entities
+with additional configuration data. This is where the concept
+of user contexts comes in. A system administrator can define an arbitrary set of
+data and attach it to Kea structures, as long as the data are specified
+as a JSON map. In particular, it is possible to define fields that are
+integers, strings, boolean, lists, or maps. It is possible to define
nested structures of arbitrary complexity. Kea does not use that data on
-its own, simply stores and makes it available for the hook libraries.
+its own; it simply stores it and makes it available for the hooks libraries.
Another use case for user contexts may be storing comments and other
information that will be retained by Kea. Regular comments are discarded
-when configuration is loaded, but user contexts are retained. This is
-useful if you want your comments to survive config-set, config-get
-operations for example.
+when the configuration is loaded, but user contexts are retained. This is
+useful if administrators want their comments to survive config-set or config-get
+operations, for example.
If user context is supported in a given context, the parser translates
"comment" entries into user context with a "comment" entry. The pretty
print of a configuration does the opposite operation and puts "comment"
-entries at the beginning of maps as it seems to be the common usage.
+entries at the beginning of maps, as that seems to be the common usage.
As of Kea 1.3, the structures that allow user contexts are pools of all
types (addresses and prefixes) and subnets. Kea 1.4 extended user
context support to the global scope, interfaces config, shared networks,
subnets, client classes, option datas and definitions, host
reservations, control socket, dhcp ddns, loggers and server id. These
-are supported in both DHCPv4 and DHCPv6 at the exception of server id
+are supported in both DHCPv4 and DHCPv6, with the exception of server id
which is DHCPv6 only.
kea-netconf agent. This Kea module is built optionally and requires
Sysrepo software when used. Building Kea with NETCONF support
requires many dependencies to be installed, which are described in
- more detail in :ref: `netconf-install`.
+ more detail in :ref:`netconf-install`.
.. _kea_software:
- ``kea-ctrl-agent`` — Kea Control Agent (CA) is a daemon that exposes
a RESTful control interface for managing Kea servers.
-- ``kea-netconf`` - Kea-netconf is an agent that provides a
+- ``kea-netconf`` - kea-netconf is an agent that provides a
YANG/NETCONF interface for the Kea environment.
- ``kea-shell`` — This simple text client uses the REST interface to
NETCONF is an optional feature that is disabled by default and can be
enabled during compilation. If Kea was compiled without NETCONF
support, keactrl will do its best to not bother the user with
- information about it. The netconf entries will still be present in
- the keactrl.conf file, but netconf status will not be shown and other
+ information about it. The NETCONF entries will still be present in
+ the keactrl.conf file, but NETCONF status will not be shown and other
commands will ignore it.
**Note**
DHCPv4 server, the same parameters may be used for DHCPv6 server
configuration.
+.. _lease-reclamation:
+
Lease Reclamation
=================
During its operation Kea may produce many messages. They differ in
severity (some are more important than others) and source (different
-components (e.g. hooks) produce different messages). It is useful to
-understand which log messages are critical and which are not, and
-configure your logging appropriately. For example, debug-level messages
+components, like hooks, produce different messages). It is useful to
+understand which log messages are critical and which are not, and to
+configure logging appropriately. For example, debug-level messages
can be safely ignored in a typical deployment. They are, however, very
useful when debugging a problem.
The logging system in Kea is configured through the loggers entry in the
server section of your configuration file. In previous Kea releases this
-entry was in an independent Logging section, this is still supported for
+entry was in an independent Logging section; this is still supported for
backward compatibility.
Loggers
example, the DHCPv4 server uses one logger for messages about packet
reception and transmission, another logger for messages related to lease
allocation, and so on. Some of the libraries used by the Kea server,
-e.g. libdhcpsrv, use their own loggers.
+such as libdhcpsrv, use their own loggers.
Users implementing hooks libraries (code attached to the server at
runtime) are responsible for creating the loggers used by those
multiple loggers to log messages pertaining to different logical parts
of the library.
-In the server section of a configuration file you can specify the
+In the server section of a configuration file the
configuration for zero or more loggers (including loggers used by the
-proprietary hooks libraries). If there are no loggers specified, the
+proprietary hooks libraries) can be specified. If there are no loggers specified, the
code will use default values; these cause Kea to log messages of INFO
severity or greater to standard output. There is a small time window
after Kea has been started but before it has read its configuration;
logging in this short period can be controlled using environment
-variables. For details, see `Logging During Kea
-Startup <#logging-during-startup>`__.
+variables. For details, see :ref:`logging-during-startup`.
The three main elements of a logger configuration are: ``name`` (the
component that is generating the messages), ``severity`` (what to log),
element, which is only relevant if debug-level logging has been
selected.
-name (string)
-~~~~~~~~~~~~~
+The name (string) Logger
+~~~~~~~~~~~~~~~~~~~~~~~~
Each logger in the system has a name: that of the component binary file
-using it to log messages. For instance, if you want to configure logging
-for the DHCPv4 server, you add an entry for a logger named “kea-dhcp4”.
+using it to log messages. For instance, to configure logging
+for the DHCPv4 server, add an entry for a logger named “kea-dhcp4”.
This configuration will then be used by the loggers in the DHCPv4
-server, and all the libraries used by it (unless a library defines its
+server and all the libraries used by it, unless a library defines its
own logger and there is a specific logger configuration that applies to
-that logger).
+that logger.
When tracking down an issue with the server's operation, use of DEBUG
logging is required to obtain the verbose output needed for problem
The loggers are associated with a particular library or binary of Kea.
However, each library or binary may (and usually does) include multiple
loggers. For example, the DHCPv4 server binary contains separate loggers
-for packet parsing, for dropped packets, for callouts, etc.
+for packet parsing, dropped packets, callouts, etc.
The loggers form a hierarchy. For each program in Kea, there is a "root"
-logger, named after the program (e.g. the root logger for kea-dhcp (the
+logger, named after the program (e.g. the root logger for kea-dhcp, the
DHCPv4 server) is named kea-dhcp4. All other loggers are children of
this logger and are named accordingly, e.g. the allocation engine in the
DHCPv4 server logs messages using a logger called
for a given logger, any attributes specified override those of the root
logger, whereas any not specified are inherited from it.
-To illustrate this, suppose you are using the DHCPv4 server with the
+To illustrate this, suppose we are using the DHCPv4 server with the
root logger “kea-dhcp4” logging at the INFO level. In order to enable
-DEBUG verbosity for DHCPv4 packet drops, you must create a configuration
+DEBUG verbosity for DHCPv4 packet drops, we must create a configuration
entry for the logger called “kea-dhcp4.bad-packets” and specify severity
DEBUG for this logger. All other configuration parameters may be omitted
for this logger if the logger should use the default values specified in
Currently defined loggers are defined in the following table. The
"Software Package" column of this table specifies whether the particular
loggers belong to the core Kea code (open source Kea binaries and
-libraries), or hook libraries (open source or premium).
-
-.. table:: List of loggers supported by Kea servers and hooks libraries
-shipped with Kea and premium packages
-
- +-----------------------+-----------------------+-----------------------+
- | Logger Name | Software Package | Description |
- +=======================+=======================+=======================+
- | ``kea-ctrl-agent`` | core | The root logger for |
- | | | the Control Agent |
- | | | exposing the RESTful |
- | | | control API. All |
- | | | components used by |
- | | | the Control Agent |
- | | | inherit the settings |
- | | | from this logger. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-ctrl-agent.http | core | A logger which |
- | `` | | outputs log messages |
- | | | related to receiving, |
- | | | parsing, and sending |
- | | | HTTP messages. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4`` | core | The root logger for |
- | | | the DHCPv4 server. |
- | | | All components used |
- | | | by the DHCPv4 server |
- | | | inherit the settings |
- | | | from this logger. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp6`` | core | The root logger for |
- | | | the DHCPv6 server. |
- | | | All components used |
- | | | by the DHCPv6 server |
- | | | inherit the settings |
- | | | from this logger. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.alloc-eng | core | Used by the lease |
- | ine``, | | allocation engine, |
- | ``kea-dhcp6.alloc-eng | | which is responsible |
- | ine`` | | for managing leases |
- | | | in the lease |
- | | | database, i.e. |
- | | | creating, modifying, |
- | | | and removing DHCP |
- | | | leases as a result of |
- | | | processing messages |
- | | | from the clients. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.bad-packe | core | Used by the DHCP |
- | ts``, | | servers for logging |
- | ``kea-dhcp6.bad-packe | | inbound client |
- | ts`` | | packets that were |
- | | | dropped or to which |
- | | | the server responded |
- | | | with a DHCPNAK. It |
- | | | allows administrators |
- | | | to configure a |
- | | | separate log output |
- | | | that contains only |
- | | | packet drop and |
- | | | reject entries. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.callouts` | core | Used to log messages |
- | `, | | pertaining to the |
- | ``kea-dhcp6.callouts` | | callouts registration |
- | ` | | and execution for the |
- | | | particular hook |
- | | | point. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.commands` | core | Used to log messages |
- | `, | | relating to the |
- | ``kea-dhcp6.commands` | | handling of commands |
- | ` | | received by the DHCP |
- | | | server over the |
- | | | command channel. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.database` | core | Used to log messages |
- | `, | | relating to general |
- | ``kea-dhcp6.database` | | operations on the |
- | ` | | relational databases |
- | | | and Cassandra. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.ddns``, | core | Used by the DHCP |
- | ``kea-dhcp6.ddns`` | | server to log |
- | | | messages related to |
- | | | the Client FQDN and |
- | | | Hostname option |
- | | | processing. It also |
- | | | includes log messages |
- | | | related to the |
- | | | relevant DNS updates. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.dhcp4`` | core | Used by the DHCPv4 |
- | | | server daemon to log |
- | | | basic operations. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.dhcpsrv`` | core | The base loggers for |
- | , | | the libkea-dhcpsrv |
- | ``kea-dhcp6.dhcpsrv`` | | library. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.eval``, | core | Used to log messages |
- | ``kea-dhcp6.eval`` | | relating to the |
- | | | client classification |
- | | | expression evaluation |
- | | | code. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.host-cach | libdhcp_host_cache | This logger is used |
- | e-hooks``, | premium hook library | to log messages |
- | ``kea-dhcp6.host-cach | | related to the |
- | e-hooks`` | | operation of the Host |
- | | | Cache Hook Library. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.flex-id-h | libdhcp_flex_id | This logger is used |
- | ooks``, | premium hook library | to log messages |
- | ``kea-dhcp6.flex-id-h | | related to the |
- | ooks`` | | operation of the |
- | | | Flexible Identifiers |
- | | | Hook Library. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.ha-hooks` | libdhcp_ha hook | This logger is used |
- | `, | library | to log messages |
- | ``kea-dhcp6.ha-hooks` | | related to the |
- | ` | | operation of the High |
- | | | Availability Hook |
- | | | Library. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.hooks``, | core | Used to log messages |
- | ``kea-dhcp6.hooks`` | | related to the |
- | | | management of hooks |
- | | | libraries, e.g. |
- | | | registration and |
- | | | deregistration of the |
- | | | libraries, and to the |
- | | | initialization of the |
- | | | callouts execution |
- | | | for various hook |
- | | | points within the |
- | | | DHCP server. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.host-cmds | libdhcp_host_cmds | This logger is used |
- | -hooks``, | premium hook library | to log messages |
- | ``kea-dhcp6.host-cmds | | related to the |
- | -hooks`` | | operation of the Host |
- | | | Cmds hooks library. |
- | | | In general, these |
- | | | will pertain to the |
- | | | loading and unloading |
- | | | of the library and |
- | | | the execution of |
- | | | commands by the |
- | | | library. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.hosts``, | core | Used within the |
- | ``kea-dhcp6.hosts`` | | libdhcpsrv, it logs |
- | | | messages related to |
- | | | the management of the |
- | | | DHCP host |
- | | | reservations, i.e. |
- | | | retrieval of the |
- | | | reservations and |
- | | | adding new |
- | | | reservations. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.lease-cmd | libdhcp_lease_cmds | This logger is used |
- | s-hooks``, | hook library | to log messages |
- | ``kea-dhcp6.lease-cmd | | related to the |
- | s-hooks`` | | operation of the |
- | | | Lease Cmds hooks |
- | | | library. In general, |
- | | | these will pertain to |
- | | | the loading and |
- | | | unloading of the |
- | | | library and the |
- | | | execution of commands |
- | | | by the library. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.leases``, | core | Used by the DHCP |
- | ``kea-dhcp6.leases`` | | server to log |
- | | | messages related to |
- | | | lease allocation. The |
- | | | messages include |
- | | | detailed information |
- | | | about the allocated |
- | | | or offered leases, |
- | | | errors during the |
- | | | lease allocation, |
- | | | etc. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.legal-log | libdhcp_legal_log | This logger is used |
- | -hooks``, | premium hook library | to log messages |
- | ``kea-dhcp6.legal-log | | related to the |
- | -hooks`` | | operation of the |
- | | | Forensic Logging |
- | | | Hooks Library. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.options`` | core | Used by the DHCP |
- | , | | server to log |
- | ``kea-dhcp4.options`` | | messages related to |
- | | | the processing of |
- | | | options in the DHCP |
- | | | messages, i.e. |
- | | | parsing options, |
- | | | encoding options into |
- | | | on-wire format, and |
- | | | packet classification |
- | | | using options |
- | | | contained in the |
- | | | received packets. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.packets`` | core | This logger is mostly |
- | , | | used to log messages |
- | ``kea-dhcp6.packets`` | | related to |
- | | | transmission of the |
- | | | DHCP packets, i.e. |
- | | | packet reception and |
- | | | the sending of a |
- | | | response. Such |
- | | | messages include |
- | | | information about the |
- | | | source and |
- | | | destination IP |
- | | | addresses and |
- | | | interfaces used to |
- | | | transmit packets. The |
- | | | logger is also used |
- | | | to log messages |
- | | | related to subnet |
- | | | selection, as this |
- | | | selection is usually |
- | | | based on the IP |
- | | | addresses, relay |
- | | | addresses, and/or |
- | | | interface names, |
- | | | which can be |
- | | | retrieved from the |
- | | | received packet even |
- | | | before the DHCP |
- | | | message carried in |
- | | | the packet is parsed. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.radius-ho | libdhcp_radius | This logger is used |
- | oks``, | premium hook library | to log messages |
- | ``kea-dhcp6.radius-ho | | related to the |
- | oks`` | | operation of the |
- | | | Radius Hook Library. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.stat-cmds | libdhcp_stat_cmds | This logger is used |
- | -hooks``, | hook library | to log messages |
- | ``kea-dhcp6.stat-cmds | | related to the |
- | -hooks`` | | operation of the |
- | | | Statistics Commands |
- | | | hooks library. In |
- | | | general, these will |
- | | | pertain to loading |
- | | | and unloading the |
- | | | library and the |
- | | | execution of commands |
- | | | by the library. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.subnet-cm | libdhcp_subnet_cmds | This logger is used |
- | ds-hooks``, | hook library | to log messages |
- | ``kea-dhcp6.subnet-cm | | related to the |
- | ds-hooks`` | | operation of the |
- | | | Subnet Commands hooks |
- | | | library. In general, |
- | | | these will pertain to |
- | | | loading and unloading |
- | | | the library and the |
- | | | execution of commands |
- | | | by the library. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp4.mysql-cb- | libdhcp_mysql_cb_hook | This logger is used |
- | hooks``, | s | to log messages |
- | ``kea-dhcp6.mysql-cb- | hook library | related to the |
- | hooks`` | | operation of the |
- | | | MySQL Configuration |
- | | | Backend hooks |
- | | | library. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp-ddns`` | core | The root logger for |
- | | | the kea-dhcp-ddns |
- | | | daemon. All |
- | | | components used by |
- | | | this daemon inherit |
- | | | the settings from |
- | | | this logger unless |
- | | | there are |
- | | | configurations for |
- | | | more specialized |
- | | | loggers.. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp-ddns.dctl` | core | The logger used by |
- | ` | | the kea-dhcp-ddns |
- | | | daemon for logging |
- | | | basic information |
- | | | about the process, |
- | | | received signals, and |
- | | | triggered |
- | | | reconfigurations. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp-ddns.dhcpd | core | The logger used by |
- | dns`` | | the kea-dhcp-ddns |
- | | | daemon for logging |
- | | | events related to |
- | | | DDNS operations. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp-ddns.dhcp- | core | Used by the |
- | to-d2`` | | kea-dhcp-ddns daemon |
- | | | for logging |
- | | | information about |
- | | | events dealing with |
- | | | receiving messages |
- | | | from the DHCP servers |
- | | | and adding them to |
- | | | the queue for |
- | | | processing. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-dhcp-ddns.d2-to | core | Used by the |
- | -dns`` | | kea-dhcp-ddns daemon |
- | | | for logging |
- | | | information about |
- | | | events dealing with |
- | | | sending and receiving |
- | | | messages with the DNS |
- | | | servers. |
- +-----------------------+-----------------------+-----------------------+
- | ``kea-netconf`` | core | The root logger for |
- | | | the Netconf agent. |
- | | | All components used |
- | | | by Netconf inherit |
- | | | the settings from |
- | | | this logger if there |
- | | | is no specialized |
- | | | logger provided. |
- +-----------------------+-----------------------+-----------------------+
+libraries), or hooks libraries (open source or premium).
+
+.. table:: List of Loggers Supported by Kea Servers and Hooks Libraries Shipped With Kea and Premium Packages
+
+ +----------------------------------+------------------------+-----------------------+
+ | Logger Name | Software Package | Description |
+ +==================================+========================+=======================+
+ | ``kea-ctrl-agent`` | core | The root logger for |
+ | | | the Control Agent |
+ | | | exposing the RESTful |
+ | | | control API. All |
+ | | | components used by |
+ | | | the Control Agent |
+ | | | inherit the settings |
+ | | | from this logger. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-ctrl-agent.http`` | core | A logger which |
+ | | | outputs log messages |
+ | | | related to receiving, |
+ | | | parsing, and sending |
+ | | | HTTP messages. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4`` | core | The root logger for |
+ | | | the DHCPv4 server. |
+ | | | All components used |
+ | | | by the DHCPv4 server |
+ | | | inherit the settings |
+ | | | from this logger. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp6`` | core | The root logger for |
+ | | | the DHCPv6 server. |
+ | | | All components used |
+ | | | by the DHCPv6 server |
+ | | | inherit the settings |
+ | | | from this logger. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.alloc-engine``, | core | Used by the lease |
+ | ``kea-dhcp6.alloc-engine`` | | allocation engine, |
+ | | | which is responsible |
+ | | | for managing leases |
+ | | | in the lease |
+ | | | database, i.e. |
+ | | | creating, modifying, |
+ | | | and removing DHCP |
+ | | | leases as a result of |
+ | | | processing messages |
+ | | | from clients. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.bad-packets``, | core | Used by the DHCP |
+ | ``kea-dhcp6.bad-packets`` | | servers for logging |
+ | | | inbound client |
+ | | | packets that were |
+ | | | dropped or to which |
+ | | | the server responded |
+ | | | with a DHCPNAK. It |
+ | | | allows administrators |
+ | | | to configure a |
+ | | | separate log output |
+ | | | that contains only |
+ | | | packet drop and |
+ | | | reject entries. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.callouts``, | core | Used to log messages |
+ | ``kea-dhcp6.callouts`` | | pertaining to the |
+ | | | callouts registration |
+ | | | and execution for the |
+ | | | particular hook |
+ | | | point. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.commands``, | core | Used to log messages |
+ | ``kea-dhcp6.commands`` | | relating to the |
+ | | | handling of commands |
+ | | | received by the DHCP |
+ | | | server over the |
+ | | | command channel. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.database``, | core | Used to log messages |
+ | ``kea-dhcp6.database`` | | relating to general |
+ | | | operations on the |
+ | | | relational databases |
+ | | | and Cassandra. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.ddns``, | core | Used by the DHCP |
+ | ``kea-dhcp6.ddns`` | | server to log |
+ | | | messages related to |
+ | | | Client FQDN and |
+ | | | Hostname option |
+ | | | processing. It also |
+ | | | includes log messages |
+ | | | related to the |
+ | | | relevant DNS updates. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.dhcp4`` | core | Used by the DHCPv4 |
+ | | | server daemon to log |
+ | | | basic operations. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.dhcpsrv``, | core | The base loggers for |
+ | ``kea-dhcp6.dhcpsrv`` | | the libkea-dhcpsrv |
+ | | | library. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.eval``, | core | Used to log messages |
+ | ``kea-dhcp6.eval`` | | relating to the |
+ | | | client classification |
+ | | | expression evaluation |
+ | | | code. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.host-cache-hooks``, | libdhcp_host_cache | This logger is used |
+ | ``kea-dhcp6.host-cache-hooks`` | premium hook library | to log messages |
+ | | | related to the |
+ | | | operation of the Host |
+ | | | Cache hooks library. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.flex-id-hooks``, | libdhcp_flex_id | This logger is used |
+ | ``kea-dhcp6.flex-id-hooks`` | premium hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | Flexible Identifiers |
+ | | | hooks library. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.ha-hooks``, | libdhcp_ha hook | This logger is used |
+ | ``kea-dhcp6.ha-hooks`` | library | to log messages |
+ | | | related to the |
+ | | | operation of the High |
+ | | | Availability hooks |
+ | | | library. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.hooks``, | core | Used to log messages |
+ | ``kea-dhcp6.hooks`` | | related to the |
+ | | | management of hooks |
+ | | | libraries, e.g. |
+ | | | registration and |
+ | | | deregistration of the |
+ | | | libraries, and to the |
+ | | | initialization of the |
+ | | | callouts execution |
+ | | | for various hook |
+ | | | points within the |
+ | | | DHCP server. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.host-cmds-hooks``, | libdhcp_host_cmds | This logger is used |
+ | ``kea-dhcp6.host-cmds-hooks`` | premium hook library | to log messages |
+ | | | related to the |
+ | | | operation of the Host |
+ | | | Commands hooks |
+ | | | library. In general, |
+ | | | these will pertain to |
+ | | | the loading and |
+ | | | unloading of the |
+ | | | library and the |
+ | | | execution of commands |
+ | | | by the library. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.hosts``, | core | Used within the |
+ | ``kea-dhcp6.hosts`` | | libdhcpsrv, it logs |
+ | | | messages related to |
+ | | | the management of |
+ | | | DHCP host |
+ | | | reservations, i.e. |
+ | | | retrieving |
+ | | | reservations and |
+ | | | adding new |
+ | | | reservations. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.lease-cmds-hooks``, | libdhcp_lease_cmds | This logger is used |
+ | ``kea-dhcp6.lease-cmds-hooks`` | hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | Lease Commands hooks |
+ | | | library. In general, |
+ | | | these will pertain to |
+ | | | the loading and |
+ | | | unloading of the |
+ | | | library and the |
+ | | | execution of commands |
+ | | | by the library. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.leases``, | core | Used by the DHCP |
+ | ``kea-dhcp6.leases`` | | server to log |
+ | | | messages related to |
+ | | | lease allocation. The |
+ | | | messages include |
+ | | | detailed information |
+ | | | about the allocated |
+ | | | or offered leases, |
+ | | | errors during the |
+ | | | lease allocation, |
+ | | | etc. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.legal-log-hooks``, | libdhcp_legal_log | This logger is used |
+ | ``kea-dhcp6.legal-log-hooks`` | premium hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | Forensic Logging |
+ | | | hooks library. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.options``, | core | Used by the DHCP |
+ | ``kea-dhcp4.options`` | | server to log |
+ | | | messages related to |
+ | | | the processing of |
+ | | | options in the DHCP |
+ | | | messages, i.e. |
+ | | | parsing options, |
+ | | | encoding options into |
+ | | | on-wire format, and |
+ | | | packet classification |
+ | | | using options |
+ | | | contained in the |
+ | | | received packets. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.packets``, | core | This logger is mostly |
+ | ``kea-dhcp6.packets`` | | used to log messages |
+ | | | related to |
+ | | | transmission of the |
+ | | | DHCP packets, i.e. |
+ | | | packet reception and |
+ | | | the sending of a |
+ | | | response. Such |
+ | | | messages include |
+ | | | information about the |
+ | | | source and |
+ | | | destination IP |
+ | | | addresses and |
+ | | | interfaces used to |
+ | | | transmit packets. The |
+ | | | logger is also used |
+ | | | to log messages |
+ | | | related to subnet |
+ | | | selection, as this |
+ | | | selection is usually |
+ | | | based on the IP |
+ | | | addresses, relay |
+ | | | addresses, and/or |
+ | | | interface names, |
+ | | | which can be |
+ | | | retrieved from the |
+ | | | received packet even |
+ | | | before the DHCP |
+ | | | message carried in |
+ | | | the packet is parsed. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.radius-hooks``, | libdhcp_radius | This logger is used |
+ | ``kea-dhcp6.radius-hooks`` | premium hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | RADIUS hooks library. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.stat-cmds-hooks``, | libdhcp_stat_cmds | This logger is used |
+ | ``kea-dhcp6.stat-cmds-hooks`` | hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | Statistics Commands |
+ | | | hooks library. In |
+ | | | general, these will |
+ | | | pertain to loading |
+ | | | and unloading the |
+ | | | library and the |
+ | | | execution of commands |
+ | | | by the library. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.subnet-cmds-hooks``, | libdhcp_subnet_cmds | This logger is used |
+ | ``kea-dhcp6.subnet-cmds-hooks`` | hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | Subnet Commands hooks |
+ | | | library. In general, |
+ | | | these will pertain to |
+ | | | loading and unloading |
+ | | | the library and the |
+ | | | execution of commands |
+ | | | by the library. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp4.mysql-cb-hooks``, | libdhcp_mysql_cb_hooks | This logger is used |
+ | ``kea-dhcp6.mysql-cb-hooks`` | hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | MySQL Configuration |
+ | | | Backend hooks |
+ | | | library. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp-ddns`` | core | The root logger for |
+ | | | the kea-dhcp-ddns |
+ | | | daemon. All |
+ | | | components used by |
+ | | | this daemon inherit |
+ | | | the settings from |
+ | | | this logger unless |
+ | | | there are |
+ | | | configurations for |
+ | | | more specialized |
+ | | | loggers. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp-ddns.dctl`` | core | The logger used by |
+ | | | the kea-dhcp-ddns |
+ | | | daemon for logging |
+ | | | basic information |
+ | | | about the process, |
+ | | | received signals, and |
+ | | | triggered |
+ | | | reconfigurations. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp-ddns.dhcpddns`` | core | The logger used by |
+ | | | the kea-dhcp-ddns |
+ | | | daemon for logging |
+ | | | events related to |
+ | | | DDNS operations. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp-ddns.dhcp-to-d2`` | core | Used by the |
+ | | | kea-dhcp-ddns daemon |
+ | | | for logging |
+ | | | information about |
+ | | | events dealing with |
+ | | | receiving messages |
+ | | | from the DHCP servers |
+ | | | and adding them to |
+ | | | the queue for |
+ | | | processing. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-dhcp-ddns.d2-to-dns`` | core | Used by the |
+ | | | kea-dhcp-ddns daemon |
+ | | | for logging |
+ | | | information about |
+ | | | events dealing with |
+ | | | sending and receiving |
+ | | | messages to and from |
+ | | | the DNS servers. |
+ +----------------------------------+------------------------+-----------------------+
+ | ``kea-netconf`` | core | The root logger for |
+ | | | the NETCONF agent. |
+ | | | All components used |
+ | | | by NETCONF inherit |
+ | | | the settings from |
+ | | | this logger if there |
+ | | | is no specialized |
+ | | | logger provided. |
+ +----------------------------------+------------------------+-----------------------+
Note that user-defined hook libraries should not use any of the loggers
mentioned above, but should instead define new loggers with names that
-correspond to the libraries using them. Suppose that the user created
-the library called “libdhcp-packet-capture” to dump packets received and
-transmitted by the server to the file. An appropriate name for the
+correspond to the libraries using them. Suppose that a user created
+a library called “libdhcp-packet-capture” to dump packets received and
+transmitted by the server to a file. An appropriate name for the
logger could be ``kea-dhcp4.packet-capture-hooks``. (Note that the hook
library implementer only specifies the second part of this name, i.e.
“packet-capture”. The first part is a root-logger name and is prepended
the configuration file.
The easiest way to find a logger name is to configure all logging to go
-to a single destination and look for specific logger names. See `Logging
-Message Format <#logging-message-format>`__ for details.
+to a single destination and look there for specific logger names. See
+:ref:`logging-message-format` for details.
-severity (string)
-~~~~~~~~~~~~~~~~~
+The severity (string) Logger
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This specifies the category of messages logged. Each message is logged
with an associated severity, which may be one of the following (in
**Note**
- The keactrl tool, described in `??? <#keactrl>`__, can be configured
+ The ``keactrl`` tool, described in :ref:`keactrl`, can be configured
to start the servers in verbose mode. If this is the case, the
settings of the logging severity in the configuration file will have
- no effect, i.e. the servers will use a logging severity of DEBUG
+ no effect; the servers will use a logging severity of DEBUG
regardless of the logging settings specified in the configuration
- file. If you need to control severity via the configuration file,
+ file. To control severity via the configuration file,
please make sure that the ``kea_verbose`` value is set to "no" within
- the keactrl configuration.
+ the ``keactrl`` configuration.
-debuglevel (integer)
-~~~~~~~~~~~~~~~~~~~~
+The debuglevel (integer) Logger
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When a logger's severity is set to DEBUG, this value specifies what
level of debug messages should be printed. It ranges from 0 (least
verbose) to 99 (most verbose). If severity for the logger is not DEBUG,
this value is ignored.
-output_options (list)
-~~~~~~~~~~~~~~~~~~~~~
+The output_options (list) Logger
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each logger can have zero or more ``output_options``. These specify
where log messages are sent and are explained in detail below.
-output (string)
-^^^^^^^^^^^^^^^
+The output (string) Option
+^^^^^^^^^^^^^^^^^^^^^^^^^^
This value determines the type of output. There are several special
values allowed here: ``stdout`` (messages are printed on standard
output), ``stderr`` (messages are printed on stderr), ``syslog``
-(messages are logged to syslog using default name), ``syslog:name``
-(messages are logged to syslog using specified name). Any other value is
+(messages are logged to syslog using the default name), ``syslog:name``
+(messages are logged to syslog using a specified name). Any other value is
interpreted as a filename to which messages should be written.
-flush (true of false)
-^^^^^^^^^^^^^^^^^^^^^
+The flush (true of false) Option
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Flush buffers after each log message. Doing this will reduce performance
but will ensure that if the program terminates abnormally, all messages
up to the point of termination are output. The default is "true".
-maxsize (integer)
-^^^^^^^^^^^^^^^^^
+The maxsize (integer) Option
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Only relevant when the destination is a file. This is the maximum size
+This option is only relevant when the destination is a file; this is the maximum size
in bytes that a log file may reach. When the maximum size is reached,
the file is renamed and a new file opened. For example, a ".1" is
-appended to the name — if a ".1" file exists, it is renamed ".2", etc.
+appended to the name; if a ".1" file exists, it is renamed ".2", etc.
This is referred to as rotation.
-The default value is 10240000 (10MB). The smallest value that may be
+The default value is 10240000 (10MB). The smallest value that can be
specified without disabling rotation is 204800. Any value less than
this, including 0, disables rotation.
Due to a limitation of the underlying logging library (log4cplus),
rolling over the log files (from ".1" to ".2", etc) may show odd
- results; there can be multiple small files at the timing of roll
- over. This can happen when multiple processes try to roll over the
+ results; there can be multiple small files at the timing of rollover.
+ This can happen when multiple processes try to roll over the
files simultaneously. Version 1.1.0 of log4cplus solved this problem,
so if this version or later of log4cplus is used to build Kea, the
issue should not occur. Even for older versions, it is normally
expected to happen rarely unless the log messages are produced very
frequently by multiple different processes.
-maxver (integer)
-^^^^^^^^^^^^^^^^
+The maxver (integer) Option
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Only relevant when the destination is a file and rotation is enabled
+This option is only relevant when the destination is a file and rotation is enabled
(i.e. maxsize is large enough). This is the maximum number of rotated
versions that will be kept. Once that number of files has been reached,
the oldest file, "log-name.maxver", will be discarded each time the log
Example Logger Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In this example we want to set the Server logging to write to the
+In this example we want to set the server logging to write to the
console using standard output.
::
}
In this second example, we want to store debug log messages in a file
-that is at most 2MB and keep up to 8 copies of old logfiles. Once the
+that is at most 2MB and keep up to eight copies of old logfiles. Once the
logfile grows to 2MB, it will be renamed and a new file will be created.
::
]
}
+.. _logging-message-format:
+
Logging Message Format
----------------------
process generating the message (in this case, ``kea-dhcp4``) and the
component within the program from which the message originated
(``dhcpsrv``, which is the name of the common library used by DHCP
- server implementations). The number after the slash is a process id
- (pid).
+ server implementations). The number after the slash is a process ID
+ (PID).
DHCPSRV_MEMFILE_DB
The message identification. Every message in Kea has a unique
- identification, which can be used as an index into the `Kea Messages
- Manual <kea-messages.html>`__
- (https://jenkins.isc.org/job/Kea_doc/messages/kea-messages.html) from
- which more information can be obtained.
+ identification, which can be used as an index to the `Kea Messages
+ Manual <https://jenkins.isc.org/job/Kea_doc/messages/kea-messages.html>`__,
+ where more information can be obtained.
opening memory file lease database: type=memfile universe=4
A brief description. Within this text, information relating to the
--------------------------
The logging configuration is specified in the configuration file.
-However, when Kea starts, the file is not read until partway into the
+However, when Kea starts, the configuration file is not read until partway into the
initialization process. Prior to that, the logging settings are set to
default values, although it is possible to modify some aspects of the
settings by means of environment variables. Note that in the absence of
KEA_LOCKFILE_DIR
Specifies a directory where the logging system should create its lock
- file. If not specified, it is prefix/var/run/kea, where prefix
+ file. If not specified, it is prefix/var/run/kea, where "prefix"
defaults to /usr/local. This variable must not end with a slash.
- There is one special value: "none", which instructs Kea to not create
+ There is one special value: "none", which instructs Kea not to create
a lock file at all. This may cause issues if several processes log to
the same file.
KEA_LOGGER_DESTINATION
- Specifies logging output. There are several special values.
+ Specifies logging output. There are several special values:
stdout
Log to standard output.
Installing NETCONF on Ubuntu 18.04
----------------------------------
-For detailed installation instructions see the `
- Ubuntu installation notes page <
- Ubuntu installation notes page>`__.
+For detailed installation instructions, see the `Ubuntu installation notes page <https://gitlab.isc.org/isc-projects/kea/wikis/docs/ubuntu-installation-notes>`__.
.. _netconf-centos-install:
Installing NETCONF on CentOS 7.5
--------------------------------
-For detailed installation instructions see the `
- CentOS installation notes page <
- CentOS installation notes page>`__.
+For detailed installation instructions, see the `CentOS installation notes page <https://gitlab.isc.org/isc-projects/kea/wikis/docs/centos-installation-notes>`__.
-CentOS 7.5's gcc compiler (version 4.8.5) is very old. Some sysrepo
+CentOS 7.5's gcc compiler (version 4.8.5) is very old. Some Sysrepo
dependencies require at least version 4.9, which unfortunately means
that a new compiler has to be installed. Also, many of the Sysrepo
dependencies are not avalable in CentOS as packages, so for the time
======================
This section offers a rather brief overview of a subset of available
-functions in Sysrepo. For more complete information, see the Sysrepo
-homepage. You may also want to take a look at the `
- notes made during a series of IETF Hackathons <
- notes made during a series of IETF Hackathons>`__.
+functions in Sysrepo. For more complete information, see the `Sysrepo
+homepage <https://www.sysrepo.org>`__.
In YANG, configurations and state data are described in the YANG syntax
in module files named: ``"module-name"``\ ``[@"revision"]``.yang
XML syntax YIN is defined but less user-friendly. Top-level modules are
named in Kea models (a short version of schema models).
-List currently installed YANG modules:
+To list the currently installed YANG modules:
::
Kea uses its own dedicated models for DHCPv4 and DHCPv6 but partially
supports the IETF model for DHCPv6. Those three models have extra
modules as dependencies. The dependency modules are also provided in
-``src/share/yang/modules`` in sources and ``share/kea/yang/modules``
+``src/share/yang/modules`` in sources and in ``share/kea/yang/modules``
after installation.
To install modules from sources, do the following:
...
Note that the first -s parameter specifies the location of the YANG
-schema repository; you can check it with sysrepoctl -l. This is a
+schema repository; it can be verified with sysrepoctl -l. This is a
parameter that is configured during Sysrepo compilation and is detected
by the Kea configuration under the SYSREPO_REPO name.
Notifying sysrepo about the change...
Install operation completed successfully.
-You can confirm whether the models are imported correctly by using
-sysrepoctl -l
+It is possible to confirm whether the models are imported correctly by using
+sysrepoctl -l:
::
If the module is used (i.e. imported) by other modules, it can be
uninstalled only after those modules have finished using it.
Installation and uninstallation must be done in dependency order and
-reverse dependency order accordingly.
+reverse-dependency order accordingly.
.. _netconf-models:
The only currently supported models are ``kea-dhcp4-server`` and
``kea-dhcp6-server``. There is partial support for
-``ietf-dhcpv6-server``, but the primary focus of testing was on Kea DHCP
+``ietf-dhcpv6-server``, but the primary focus of testing has been on Kea DHCP
servers. Several other models (``kea-dhcp-ddns`` and ``kea-ctrl-agent``)
are currently not supported.
sessions with the startup and running datastores.
- Check that used (not essential) and required (essential) modules are
- installed in the sysrepo repository at the right revision. If an
- essential module, i.e. a module where the configuration schema for a
- managed server is defined, is not installed, raise a fatal error.
+ installed in the Sysrepo repository at the right revision. If an
+ essential module - that is, a module where the configuration schema for a
+ managed server is defined - is not installed, raise a fatal error.
- For each managed server, get the YANG configuration from the startup
datastore, translate it to JSON, and load it onto the server being
Configuration
=============
-The behavior described in `Using the NETCONF Agent <#using-netconf>`__
+The behavior described in :ref:`using-netconf`
is controlled by a few configuration flags, which can be set in the
global scope or in a specific managed-server scope. In the second case,
the value defined in the managed-server scope takes precedence. These
flags are:
-- The ``boot-update`` controls the initial configuration phase; when
+- ``boot-update`` - controls the initial configuration phase; when
true (the default), the initial configuration retrieved from the
classic Kea server JSON configuration file is loaded first, and then
the startup YANG model is loaded. This setting lets administrators
define a control socket in the local JSON file and then download the
configuration from YANG. When set to false, this phase is skipped.
-- The ``subscribe-changes`` command controls the module change
+- ``subscribe-changes`` - controls the module change
subscription; when true (the default), a module change callback is
subscribed, but when false the phase is skipped and running
configuration updates are disabled. When set to true, the running
datastore is used to subscribe for changes.
-- The ``validate-changes`` command controls how Kea monitors changes in
- the Sysrepo configuration. Sysrepo offers two stages where Kea could
+- ``validate-changes`` - controls how Kea monitors changes in
+ the Sysrepo configuration. Sysrepo offers two stages where Kea can
interact: validation and application. At the validation (or
SR_EV_VERIFY event, in the Sysrepo naming convention) stage, Kea
retrieves the newly committed configuration and verifies it. If the
Note the alternative to boot with full configurations does not allow
easy tracking of changes or synchronization between the JSON and YANG
configuration sources; therefore, that setup is not really compatible
-with the YANG / NETCONF configuration management paradigm, where
+with the YANG/NETCONF configuration management paradigm, where
everything should be performed in YANG.
With module change subscriptions enabled, the kea-netconf daemon will
monitor any configuration changes as they appear in the Sysrepo. Such
changes can be done using the ``sysrepocfg`` tool or remotely using any
NETCONF client. For details, please see the Sysrepo documentation or
-`Step-by-Step NETCONF Agent Operation Example <#operation-example>`__.
+:ref:`operation-example`.
Those tools can be used to modify YANG configurations in the running
datastore. Note that committed configurations are only updated in the
running datastore; to keep them between server reboots they must be
``sysrepocfg`` or any NETCONF client), the callback validates the
modified configuration (if ``validate-changes`` was not set to false)
and runs a second time to apply the new configuration. If the validation
-fails, the callback is still called again but with an ABORT (vs APPLY)
+fails, the callback is still called again but with an ABORT (vs. APPLY)
event with rollback changes.
The returned code of the callback on an APPLY event is ignored, as it is
There are four ways in which a modified YANG configuration could
possibly be incorrect:
-1. It can be non-compliant with the schema, e.g. unknown entry, missing
- mandatory entry, value with a bad type, or not matching a constraint.
+1. It can be non-compliant with the schema, e.g. an unknown entry, missing a
+ mandatory entry, a value with a bad type, or not matching a constraint.
-2. It can fail to be translated from YANG to JSON, e.g. invalid user
+2. It can fail to be translated from YANG to JSON, e.g. an invalid user
context.
-3. It can fail Kea server sanity checks, e.g. out-of-subnet-pool range
- or unsupported database type.
+3. It can fail Kea server sanity checks, e.g. an out-of-subnet-pool range
+ or an unsupported database type.
-4. The syntax is correct and passes server sanity checks but the
+4. The syntax may be correct and pass server sanity checks but the
configuration fails to run, e.g. the configuration specifies database
- credentials, but the database refuses connection.
+ credentials but the database refuses the connection.
The first case is handled by Sysrepo. The second and third cases are
handled by kea-netconf in the validation phase (if not disabled by
Each managed server entry contains optionally:
-- ``boot-update``, ``subscribe-changes``, and ``validate-changes``
+- ``boot-update``, ``subscribe-changes``, and ``validate-changes`` -
control flags.
-- ``model`` specifies the YANG model / module name. For each service,
+- ``model`` - specifies the YANG model / module name. For each service,
the default is the corresponding Kea YANG model, e.g. for ``"dhcp4"``
it is ``"kea-dhcp4-server"``.
-- ``control-socket`` specifies the control socket for managing the
+- ``control-socket`` - specifies the control socket for managing the
service configuration.
A control socket is specified by:
-- ``socket-type``: the socket type is either ``stdout`` (the default;
+- ``socket-type`` - the socket type is either ``stdout``, ``unix``, or ``http``.
+ ``stdout`` is the default;
it is not really a socket, but it allows ``kea-netconf`` to run in
- debugging mode where everything is printed on stdout. Can be also
- useful to redirect commands easily.), ``unix`` (standard direct
- server control channel, which uses UNIX sockets), and ``http`` (using
- a control agent, which accepts HTTP connections).
+ debugging mode where everything is printed on stdout, and it can also be
+ used to redirect commands easily. ``unix`` is the standard direct
+ server control channel, which uses UNIX sockets, and ``http`` uses
+ a control agent, which accepts HTTP connections.
-- ``socket-name``: the local socket name for the ``unix`` socket type
+- ``socket-name`` - the local socket name for the ``unix`` socket type
(default empty string).
-- ``socket-url``: the HTTP URL for the ``http`` socket type (default
+- ``socket-url`` - the HTTP URL for the ``http`` socket type (default
``http://127.0.0.1:8000/``).
User contexts can store arbitrary data as long as they are in valid JSON
should be loaded by kea-netconf, along with their configuration
information specified with ``parameters``.
-Please consult `??? <#logging>`__ for the details on how to configure
+Please consult :ref:`logging` for details on how to configure
logging. The NETCONF agent's root logger's name is ``kea-netconf``, as
given in the example above.
.. _netconf-example:
-kea-netconf Configuration Example
-=================================
+A kea-netconf Configuration Example
+===================================
The following example demonstrates the basic NETCONF configuration. More
examples are available in the ``doc/examples/netconf`` directory in the
"Netconf":
{
// Control flags can be defined in the global scope or
- // in a managed server scope. Precedence are:
+ // in a managed server scope. Precedences are:
// - use the default value (true)
// - use the global value
// - use the local value.
// "stdout" which outputs the configuration on the standard output,
// "unix" which uses the local control channel supported by the
// "dhcp4" and "dhcp6" servers ("d2" support is not yet available),
- // and "http" which uses the Control agent "ca" to manage itself or
+ // and "http" which uses the Control Agent "ca" to manage itself or
// to forward commands to "dhcp4" or "dhcp6".
"managed-servers":
{
}
},
- // Of course the Control Agent (nicknamed CA) supports HTTP.
+ // Of course the Control Agent (CA) supports HTTP.
"ca":
{
"model": "kea-ctrl-agent",
}
],
- // Similar to other Kea components, Netconf also uses logging.
+ // Similar to other Kea components, NETCONF also uses logging.
"loggers": [
{
"name": "kea-netconf",
.. _operation-example:
-Step-by-Step NETCONF Agent Operation Example
-============================================
+A Step-by-Step NETCONF Agent Operation Example
+==============================================
**Note**
}
}
-Note that in production you should not need to log at the DEBUG level.
+Note that in production there should not be a need to log at the DEBUG level.
The Kea NETCONF agent is launched by:
</control-socket>
</config>
-is directly rejected by ``sysrepocfg``:
+It is directly rejected by ``sysrepocfg``:
::
In the last case, the misconfiguration is detected too late and the
change must be reverted in Sysrepo, e.g. using the startup datastore as
a backup. For this reason, please use the ``sysrepocfg`` ``--permanent``
-/ ``-p`` option (or a similar feature of NETCONF clients) with care.
+/ ``-p`` option (or any similar feature of NETCONF clients) with care.
.. _operation-example-2pools:
# sysrepocfg -d running -f xml -e vi kea-dhcp6-server
-or, of course, using a NETCONF client like ``netopeer2-cli`` from the `
- Netopeer2 <
- Netopeer2>`__ NETCONF Toolset.
+or, of course, using a NETCONF client like ``netopeer2-cli`` from the
+`Netopeer2 <https://github.com/CESNET/Netopeer2>`__ NETCONF Toolset.
This section describes the basic steps needed to get Kea up and running.
For further details, full customizations, and troubleshooting, see the
-respective chapters in the Kea Administrator Reference Manual (ARM).
+respective chapters elsewhere in this Kea Administrator Reference Manual (ARM).
.. _quick-start:
For instructions specific to your system, please read the
`system-specific notes <https://kb.isc.org/docs/installing-kea>`__,
-available in the `Kea section of ISC's
+available in the Kea section of `ISC's
Knowledgebase <https://kb.isc.org/docs>`__.
The details of ``keactrl`` script usage can be found in
.. _shell-overview:
-Overview
-========
+Overview of the Kea Shell
+=========================
Kea 1.2.0 introduced the Control Agent (CA, see
-`??? <#kea-ctrl-agent>`__), which provides a RESTful control interface
+:ref:`kea-ctrl-agent`), which provides a RESTful control interface
over HTTP. That API is typically expected to be used by various IPAMs
and similar management systems. Nevertheless, there may be cases when an
-administrator wants to send a command to the CA directly. The Kea shell
+administrator wants to send a command to the CA directly, and the Kea shell
provides a way to do this. It is a simple command-line,
scripting-friendly, text client that is able to connect to the CA, send
it commands with parameters, retrieve the responses, and display them.
As the primary purpose of the Kea shell is as a tool in a scripting
-environment, it is not interactive. However, with simple tricks it can
+environment, it is not interactive. However, following simple guidelines it can
be run manually.
Shell Usage
Other switches are:
-- ``-h`` prints a help message.
+- ``-h`` - prints a help message.
-- ``-v`` prints the software version.
+- ``-v`` - prints the software version.
Once started, the shell reads parameters for the command from standard
input, which are expected to be in JSON format. When all have been read,
command, and awaits a response. Once that is received, it is displayed
on standard output.
-For a list of available commands, see `??? <#ctrl-channel>`__;
-additional commands may be provided by hook libraries. If you are unsure
-which commands are supported, use the ``list-commands`` command. It will
-instruct the CA to return a list of all supported commands.
+For a list of available commands, see :ref:`ctrl-channel`;
+additional commands may be provided by hooks libraries. For a list of
+all supported commands from the CA, use the ``list-commands`` command.
The following shows a simple example of usage:
It is envisaged that the Kea shell will be most frequently used in
scripts; the next example shows a simple scripted execution. It sends
-the command "config-write" to the CA (the ``--service`` parameter hasn't
+the command "config-write" to the CA (the ``--service`` parameter has not
been used), along with the parameters specified in param.json. The
result will be stored in result.json.
$ kea-shell --host 192.0.2.1 --port 8001 --path kea ...
-Kea shell requires Python to to be installed on the system. It has been
+The Kea shell requires Python to to be installed on the system. It has been
tested with Python 2.7 and various versions of Python 3, up to 3.5.
Since not every Kea deployment uses this feature and there are
deployments that do not have Python, the Kea shell is not enabled by
The Kea shell is intended to serve more as a demonstration of the
RESTful interface's capabilities (and, perhaps, an illustration for
people interested in integrating their management environments with Kea)
-than as a serious management client. Do not expect it to be
-significantly expanded in the future. It is, and will remain, a simple
+than as a serious management client. It is not likely to be
+significantly expanded in the future; it is, and will remain, a simple
tool.
Both Kea DHCP servers support statistics gathering. A working DHCP
server encounters various events that can cause certain statistics to be
collected. For example, a DHCPv4 server may receive a packet
-(pkt4-received statistic increases by one) that after parsing is
+(the pkt4-received statistic increases by one) that after parsing is
identified as a DHCPDISCOVER (pkt4-discover-received). The server
processes it and decides to send a DHCPOFFER representing its answer
-(pkt4-offer-sent and pkt4-sent statistics increase by one). Such events
+(the pkt4-offer-sent and pkt4-sent statistics increase by one). Such events
happen frequently, so it is not uncommon for the statistics to have
values in the high thousands. They can serve as an easy and powerful
tool for observing a server's and a network's health. For example, if
- *integer* - this is the most common type. It is implemented as a
64-bit integer (int64_t in C++), so it can hold any value between
- -2^63 to 2^63 -1.
+ -2^63 to 2^63-1.
- *floating point* - this type is intended to store floating-point
precision. It is implemented as a C++ double type.
During normal operation, the DHCPv4 and DHCPv6 servers gather
statistics. For a list of DHCPv4 and DHCPv6 statistics, see
-`??? <#dhcp4-stats>`__ and `??? <#dhcp6-stats>`__, respectively.
+:ref:`dhcp4-stats` and :ref:`dhcp6-stats`, respectively.
To extract data from the statistics module, the control channel can be
-used. See `??? <#ctrl-channel>`__ for details. It is possible to
+used. See :ref:`ctrl-channel` for details. It is possible to
retrieve a single statistic or all statistics, reset statistics (i.e.
-set to neutral value, typically zero), or even remove completely a
-single statistic or all statistics. See section `Commands for
-Manipulating Statistics <#command-stats>`__ for a list of
-statistics-oriented commands.
+set to a neutral value, typically zero), or even completely remove a
+single statistic or all statistics. See the section :ref:`command-stats`
+for a list of statistics-oriented commands.
.. _stats-lifecycle:
It is useful to understand how the Statistics Manager module works. When
the server starts operation, the manager is empty and contains no
-statistics. When ``statistic-get-all`` is executed, an empty list is
+statistics. If the ``statistic-get-all`` command is executed at that point, an empty list is
returned. Once the server performs an operation that causes a statistic
to change, the related statistic will be created. In general, once a
statistic is recorded even once, it is kept in the manager until
cause clients to report duplicate addresses, so the server will report
increasing values of pkt4-decline-received. Once the problem is found
and the device is removed, the system administrator may want to remove
-the pkt4-decline-received statistic, so it won't be reported anymore. If
-a duplicate address is detected ever again, the server will add this
+the pkt4-decline-received statistic, so it will not be reported anymore. If
+a duplicate address is ever detected again, the server will add this
statistic back.
.. _command-stats:
====================================
There are several commands defined that can be used for accessing
-(-get), resetting to zero or neutral value (-reset), or even removing a
+(-get), resetting to zero or a neutral value (-reset), or removing a
statistic completely (-remove). The difference between reset and remove
is somewhat subtle. The reset command sets the value of the statistic to
zero or a neutral value, so after this operation, the statistic will
have a value of 0 (integer), 0.0 (float), 0h0m0s0us (duration), or ""
(string). When requested, a statistic with the values mentioned will be
returned. ``Remove`` removes a statistic completely, so the statistic
-will not be reported anymore. Please note that the server code may add
+will no longer be reported. Please note that the server code may add
it back if there is a reason to record it.
**Note**
The following sections describe commands that can be sent to the
server; the examples are not fragments of a configuration file. For
more information on sending commands to Kea, see
- `??? <#ctrl-channel>`__.
+ :ref:`ctrl-channel`.
.. _command-statistic-get:
-statistic-get Command
----------------------
+The statistic-get Command
+-------------------------
-The *statistic-get* command retrieves a single statistic. It takes a
+The ``statistic-get`` command retrieves a single statistic. It takes a
single-string parameter called ``name``, which specifies the statistic
name. An example command may look like this:
.. _command-statistic-reset:
-statistic-reset Command
------------------------
+The statistic-reset Command
+---------------------------
-The *statistic-reset* command sets the specified statistic to its
+The ``statistic-reset`` command sets the specified statistic to its
neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time
duration, and "" for string type. It takes a single-string parameter
called ``name``, which specifies the statistic name. An example command
.. _command-statistic-remove:
-statistic-remove Command
-------------------------
+The statistic-remove Command
+----------------------------
-The *statistic-remove* command attempts to delete a single statistic. It
+The ``statistic-remove`` command attempts to delete a single statistic. It
takes a single-string parameter called ``name``, which specifies the
statistic name. An example command may look like this:
.. _command-statistic-get-all:
-statistic-get-all Command
--------------------------
+The statistic-get-all Command
+-----------------------------
-The *statistic-get-all* command retrieves all statistics recorded. An
+The ``statistic-get-all`` command retrieves all statistics recorded. An
example command may look like this:
::
.. _command-statistic-reset-all:
-statistic-reset-all Command
----------------------------
+The statistic-reset-all Command
+-------------------------------
-The *statistic-reset* command sets all statistics to their neutral
+The ``statistic-reset`` command sets all statistics to their neutral
values: 0 for integer, 0.0 for float, 0h0m0s0us for time duration, and
"" for string type. An example command may look like this:
.. _command-statistic-remove-all:
-statistic-remove-all Command
-----------------------------
+The statistic-remove-all Command
+--------------------------------
-The *statistic-remove-all* command attempts to delete all statistics. An
+The ``statistic-remove-all`` command attempts to delete all statistics. An
example command may look like this:
::
If the removal of all statistics is successful, the server responds with
a status of 0, indicating success, and an empty parameters field. If an
error is encountered, the server returns a status code of 1 (error) and
-the text field will contain the error description.
+the text field contains the error description.
projects / thirdparty / kea.git / commitdiff
