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

1212 lines
38 KiB
ReStructuredText
Raw Normal View History

[#2554] add 'ischooklib' anchors and references
2023-06-06 13:30:39 +03:00
.. ischooklib:: libdhcp_host_cmds.so
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
.. _hooks-host-cmds:
[#2554] add 'ischooklib' anchors and references
2023-06-06 13:30:39 +03:00
``libdhcp_host_cmds.so``: Host Commands
=======================================
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
Kea can store host reservations in a database; in many larger deployments,
it is useful to be able to manage that information while the server is
[#2403] Final changes to section header formatting
2022-06-13 16:04:58 +00:00
running. The Host Commands library provides management commands for adding, querying,
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
and deleting host reservations in a safe way without restarting the
server. In particular, it validates the parameters, so an attempt to
insert incorrect data - such as adding a host with a conflicting identifier in the
same subnet - is rejected. Those commands are exposed via the command
channel (JSON over UNIX sockets) and the Control Agent (JSON over a RESTful
interface).
[#2554] add notes about each hook library's packaging - Premium libraries were marked as subscription libraries. That has also been fixed.
2023-06-13 19:39:12 +03:00
.. note::
:ischooklib:`libdhcp_host_cmds.so` is available as a premium
hook library from ISC. Please visit https://www.isc.org/shop/ to purchase
the premium hook libraries, or contact us at https://www.isc.org/contact for
more information.
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
.. note::
[#2554] add 'iscman' references The commands used were: - find doc/sphinx/man -name '*.rst' | xargs grep -F '.. iscman' | cut -d ' ' -f 3 > /tmp/binaries - for i in $(cat /tmp/binaries); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/:iscman:\`${i}\`/g"; done Manual adjustment was required in a few places to: - extend title lines - realign table lines
2023-06-06 13:43:11 +03:00
This library can only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6`
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
process.
Currently, the following commands are supported:
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
- :isccmd:`reservation-add`, which adds a new host reservation.
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
- :isccmd:`reservation-get`, which returns an existing reservation if specified
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
criteria are matched.
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
- :isccmd:`reservation-get-all`, which returns all reservations in a specified subnet.
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
- :isccmd:`reservation-get-page`, a variant of :isccmd:`reservation-get-all` that returns
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
reservations by pages, either all or in a specified subnet.
[#2795] updating ARM docs
2023-06-16 11:43:34 +02:00
- :isccmd:`reservation-get-by-address`, which returns all reservations with a
[#2795] addressed review comments
2023-06-26 15:42:19 +02:00
specified IP address or a delegated prefix (without a prefix length), and optionally a subnet id.
[#2795] updating ARM docs
2023-06-16 11:43:34 +02:00
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
- :isccmd:`reservation-get-by-hostname`, which returns all reservations with a
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
specified hostname and optionally in a subnet.
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
- :isccmd:`reservation-get-by-id`, which returns all reservations with a specified
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
identifier (since Kea version 1.9.0).
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
- :isccmd:`reservation-del`, which attempts to delete a reservation matching specified
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
criteria.
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
- :isccmd:`reservation-update`, which updates (replaces) an existing reservation
[#549] document reservation-update
2023-04-05 14:39:12 +03:00
matching the given identifiers in a subnet.
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
To use the commands that change reservation information
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
(i.e. :isccmd:`reservation-add`, :isccmd:`reservation-del`, and :isccmd:`reservation-update`) to
[#2815] Update docs
2023-05-09 16:54:24 +02:00
modify data stored in the host database, the hosts database must be specified
and it must not operate in read-only mode (for details, see the
``hosts-databases`` descriptions in :ref:`hosts-databases-configuration4` and
:ref:`hosts-databases-configuration6`). If the ``hosts-databases`` are not
[#2554] add 'ischooklib' anchors and references
2023-06-06 13:30:39 +03:00
specified or are running in read-only mode, :ischooklib:`libhost_cmds.so` will
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
load, but any attempts to use :isccmd:`reservation-add`, :isccmd:`reservation-del`, and
:isccmd:`reservation-update` to modify data in that database will fail.
[#2815] Update docs
2023-05-09 16:54:24 +02:00
These commands can also modify hosts from the JSON configuration independently
from the hosts database. The changes provided in the JSON configuration are
[#2554] address review comments
2023-06-13 16:33:13 +03:00
volatile and can be made permanent by sending the :isccmd:`config-write` command.
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
For a description of proposed future commands, see the `Control API
Requirements <https://gitlab.isc.org/isc-projects/kea/wikis/designs/commands>`__
document.
All host commands use JSON syntax. They can be issued either using the
control channel (see :ref:`ctrl-channel`) or via the Control Agent (see
:ref:`kea-ctrl-agent`).
The library can be loaded similarly to other hook libraries. It
does not take any parameters, and it supports both the DHCPv4 and DHCPv6
servers.
::
"Dhcp6": {
"hooks-libraries": [
{
"library": "/path/libdhcp_host_cmds.so"
[#2827] fixed all json examples in arm
2023-05-05 15:04:16 +03:00
},
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
...
]
}
The ``subnet-id`` Parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before examining the individual commands, it is worth discussing the
parameter ``subnet-id``. Currently this parameter is mandatory for all of the
commands supplied by this library, with the exception of
[#2795] updating ARM docs
2023-06-16 11:43:34 +02:00
:isccmd:`reservation-get-by-hostname` and :isccmd:`reservation-get-by-address`,
where it is optional. Since Kea 1.9.0,
[#2554] address review comments
2023-06-13 16:33:13 +03:00
``subnet-id`` is also optional in :isccmd:`reservation-get-page`, and
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
it is forbidden in :isccmd:`reservation-get-by-id`.
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
Reservations can be specified globally, and are not necessarily specific to any
subnet. When reservations are supplied via the configuration file, the
ID of the containing subnet (or lack thereof) is implicit in the
configuration structure. However, when managing reservations using
host commands, it is necessary to explicitly identify the scope to which
the reservation belongs. This is done via the ``subnet-id`` parameter.
For global reservations, use a value of zero (0). For reservations
scoped to a specific subnet, use that subnet's ID.
On the other hand, when the ``subnet-id`` is not specified in the command
parameters, it is added to each host in responses. If the ``subnet-id``
has the unused special value, this means the host entry belongs only
to the other IP version (i.e. IPv6 in DHCPv4 server or IPv4 in DHCPv6
server) and this entry is ignored.
[#2815] Update docs
2023-05-09 16:54:24 +02:00
The ``operation-target`` Parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Most host commands accept the ``operation-target`` parameter that specifies the
database(s) to query. The commands may process data from the JSON configuration
(primary source), the hosts database (alternate source), or both of them
(all sources). The operation target parameter is optional. By default, the
commands that only read the data use all data sources (JSON configuration and
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
hosts database); the commands that modify the state (as :isccmd:`reservation-add`,
:isccmd:`reservation-del`, and :isccmd:`reservation-update`) only use the alternate source.
[#2815] Update docs
2023-05-09 16:54:24 +02:00
[#2815] Add 1 suggestion to 1 file
2023-05-24 15:26:57 +00:00
The operation target accepts the following values:
[#2815] Update docs
2023-05-09 16:54:24 +02:00
- ``primary`` - query the primary source - JSON configuration.
- ``alternate`` - query the alternate source - hosts database(s).
- ``all`` - query both sources - JSON configuration and host database(s).
- ``default`` - query the default source - it's command specific.
[#2554] add 'isccmd' anchors
2023-06-06 13:33:44 +03:00
.. isccmd:: reservation-add
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
.. _command-reservation-add:
The ``reservation-add`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
:isccmd:`reservation-add` allows for the insertion of a new host. It takes a
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
set of arguments that vary depending on the nature of the host
reservation. Any parameters allowed in the configuration file that
pertain to host reservation are permitted here. For details regarding
IPv4 reservations, see :ref:`host-reservation-v4`; for IPv6 reservations, see
:ref:`host-reservation-v6`. The ``subnet-id`` is mandatory. Use a
value of zero (0) to add a global reservation, or the ID of the subnet
[#549] document reservation-update
2023-04-05 14:39:12 +03:00
to which the reservation should be added. The command can be as simple as having
only the two mandatory entries:
.. code-block:: json
{
"command": "reservation-add",
"arguments": {
"reservation": {
"subnet-id": 1,
"hw-address": "1a:1b:1c:1d:1e:1f"
}
}
}
In that case, however, it does not assign any resources to the host. An IPv4
address can be assigned like so:
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
.. code-block:: json
{
"command": "reservation-add",
"arguments": {
"reservation": {
"subnet-id": 1,
"hw-address": "1a:1b:1c:1d:1e:1f",
"ip-address": "192.0.2.202"
}
}
}
[#549] address review comments
2023-04-19 19:19:44 +03:00
It can also take many more parameters, for example:
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
.. code-block:: json
{
"command": "reservation-add",
"arguments": {
"reservation": {
"subnet-id": 1,
"client-id": "01:0a:0b:0c:0d:0e:0f",
"ip-address": "192.0.2.205",
"next-server": "192.0.2.1",
"server-hostname": "hal9000",
"boot-file-name": "/dev/null",
"option-data": [
{
"name": "domain-name-servers",
"data": "10.1.1.202,10.1.1.203"
}
],
"client-classes": [ "special_snowflake", "office" ]
}
}
}
Here is an example of a complex IPv6 reservation:
.. code-block:: json
{
"command": "reservation-add",
"arguments": {
"reservation": {
"subnet-id": 1,
"duid": "01:02:03:04:05:06:07:08:09:0A",
"ip-addresses": [ "2001:db8:1:cafe::1" ],
"prefixes": [ "2001:db8:2:abcd::/64" ],
"hostname": "foo.example.com",
"option-data": [
{
"name": "vendor-opts",
"data": "4491"
},
{
"name": "tftp-servers",
"space": "vendor-4491",
"data": "3000:1::234"
}
]
}
}
}
[#2815] Update docs
2023-05-09 16:54:24 +02:00
The command accepts the ``operation-target`` argument. By default, it adds the
reservation to the hosts database only.
.. code-block:: json
{
"command": "reservation-add",
"arguments": {
[#2815] Fix docs
2023-05-10 12:24:04 +02:00
"reservation": {},
[#2815] Update docs
2023-05-09 16:54:24 +02:00
"operation-target": "all"
}
}
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
The command returns a status that indicates either success (result 0)
or failure (result 1). A failed command always includes a text parameter
that explains the cause of the failure. Here's an example of a successful
addition:
[#549] document reservation-update
2023-04-05 14:39:12 +03:00
.. code-block:: json
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
[#549] document reservation-update
2023-04-05 14:39:12 +03:00
{
"result": 0,
"text": "Host added."
}
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
And here's an example of a failure:
[#549] document reservation-update
2023-04-05 14:39:12 +03:00
.. code-block:: json
{
"result": 1,
"text": "Mandatory 'subnet-id' parameter missing."
}
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
As :isccmd:`reservation-add` is expected to store the host, the ``hosts-databases``
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
parameter must be specified in the configuration, and databases must not
run in read-only mode.
[#2554] add 'isccmd' anchors
2023-06-06 13:33:44 +03:00
.. isccmd:: reservation-get
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
.. _command-reservation-get:
The ``reservation-get`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
:isccmd:`reservation-get` can be used to query the host database and retrieve
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
existing reservations. This command supports two types of parameters:
(``subnet-id``, ``address``) or (``subnet-id``, ``identifier-type``,
``identifier``). The first type of query is used when the address (either
IPv4 or IPv6) is known, but the details of the reservation are not. One
common use for this type of query is to find out whether a given
address is reserved. The second query uses identifiers. For
maximum flexibility, Kea stores the host identifying information as a
pair of values: the type and the actual identifier. Currently supported
identifiers are ``"hw-address"``, ``"duid"``, ``"circuit-id"``, ``"client-id"``, and
``"flex-id"``. The ``subnet-id`` is mandatory. Use a value
of zero (0) to fetch a global reservation, or the ID of the subnet to
which the reservation belongs.
An example command for getting a host reservation by a (``subnet-id``,
``address``) pair looks as follows:
::
{
"command": "reservation-get",
"arguments": {
"subnet-id": 1,
"ip-address": "192.0.2.202"
}
}
An example query by (``subnet-id``, ``identifier-type``, ``identifier``) looks as
follows:
::
{
"command": "reservation-get",
"arguments": {
"subnet-id": 4,
"identifier-type": "hw-address",
"identifier": "01:02:03:04:05:06"
}
}
[#2815] Update docs
2023-05-09 16:54:24 +02:00
The command accepts the ``operation-target`` argument. By default, it gets the
reservation from both JSON configuration and the hosts database.
.. code-block:: json
{
"command": "reservation-get",
"arguments": {
"subnet-id": 1,
"ip-address": "192.0.2.202",
"operation-target": "alternate"
}
}
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
Command :isccmd:`reservation-get` typically returns the result 0 when a query was
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
conducted properly. In particular, 0 is returned when the host was not
found. If the query was successful, the host parameters are
returned. An example of a query that did not find the host looks as
follows:
::
{ "result": 0, "text": "Host not found." }
Here's an example of a result returned when the host was found successfully:
::
{
"arguments": {
"boot-file-name": "bootfile.efi",
"client-classes": [
],
"hostname": "somehost.example.org",
"hw-address": "01:02:03:04:05:06",
"ip-address": "192.0.2.100",
"next-server": "192.0.0.2",
"option-data": [
],
[#2471] Updated doc
2022-08-05 16:02:42 +02:00
"server-hostname": "server-hostname.example.org",
"subnet-id": 4
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
},
"result": 0,
"text": "Host found."
}
An example result returned when the query was malformed might look like this:
::
[#2827] fixed all json examples in arm
2023-05-05 15:04:16 +03:00
{ "result": 1, "text": "No 'ip-address' provided and 'identifier-type' is either missing or not a string." }
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
[#2554] add 'isccmd' anchors
2023-06-06 13:33:44 +03:00
.. isccmd:: reservation-get-all
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
.. _command-reservation-get-all:
The ``reservation-get-all`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
:isccmd:`reservation-get-all` can be used to query the host database and
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
retrieve all reservations in a specified subnet. This command uses
parameters providing the mandatory ``subnet-id``. Global host reservations
can be retrieved by using a ``subnet-id`` value of zero (0).
For instance, retrieving host reservations for the subnet 1:
::
{
"command": "reservation-get-all",
"arguments": {
"subnet-id": 1
}
}
returns some IPv4 hosts:
::
{
"arguments": {
"hosts": [
{
"boot-file-name": "bootfile.efi",
"client-classes": [ ],
"hostname": "somehost.example.org",
"hw-address": "01:02:03:04:05:06",
"ip-address": "192.0.2.100",
"next-server": "192.0.0.2",
"option-data": [ ],
[#2471] Updated doc
2022-08-05 16:02:42 +02:00
"server-hostname": "server-hostname.example.org",
"subnet-id": 1
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
},
{
"boot-file-name": "bootfile.efi",
"client-classes": [ ],
"hostname": "otherhost.example.org",
"hw-address": "01:02:03:04:05:ff",
"ip-address": "192.0.2.200",
"next-server": "192.0.0.2",
"option-data": [ ],
[#2471] Updated doc
2022-08-05 16:02:42 +02:00
"server-hostname": "server-hostname.example.org",
"subnet-id": 1
[#2827] fixed all json examples in arm
2023-05-05 15:04:16 +03:00
},
...
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
]
},
"result": 0,
"text": "72 IPv4 host(s) found."
}
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
The response returned by :isccmd:`reservation-get-all` can be very long. The
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
DHCP server does not handle DHCP traffic while preparing a response to
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
:isccmd:`reservation-get-all`, so if there are many reservations in a subnet, this
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
may be disruptive; use with caution. For larger deployments, please
[#2554] address review comments
2023-06-13 16:33:13 +03:00
consider using :isccmd:`reservation-get-page` instead.
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
[#2815] Update docs
2023-05-09 16:54:24 +02:00
The command accepts the ``operation-target`` argument. By default, it gets the
reservation from both JSON configuration and the hosts database.
.. code-block:: json
{
"command": "reservation-get-all",
"arguments": {
"subnet-id": 1,
"operation-target": "alternate"
}
}
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
For more information, see :ref:`command-reservation-get-all`.
[#2554] add 'isccmd' anchors
2023-06-06 13:33:44 +03:00
.. isccmd:: reservation-get-page
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
.. _command-reservation-get-page:
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
The ``reservation-get-page`` Command
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
:isccmd:`reservation-get-page` can be used to query the host database and
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
retrieve all reservations in a specified subnet, by pages. This command
uses parameters providing the mandatory ``subnet-id``. Use a value of zero
(0) to fetch global reservations. The second mandatory parameter is the
page size limit. The optional ``source-index`` and ``from-host-id`` parameters, both
of which default to 0, are used to chain page queries.
Since Kea version 1.9.0, the ``subnet-id`` parameter is optional.
The usage of the ``from`` and ``source-index`` parameters requires additional
explanation. For the first call, those parameters should not be specified
(or should be specified as zeros). For any follow-up calls, they should be set to
the values returned in previous calls, in a next map holding ``from`` and
``source-index`` values. Subsequent calls should be issued until all
reservations are returned. The end is reached once the returned list is
empty, the count is 0, no next map is present, and result status 3 (empty) is
returned.
.. note::
The ``from`` and ``source-index`` parameters reflect the internal state of
the search. There is no need to understand what they represent; it is
simply a value that should be copied from one response to the
next query. However, for those who are curious, the ``from`` field represents a
64-bit representation of the host identifier used by a host backend. The
``source-index`` is an internal representation of multiple host
backends: 0 is used to represent hosts defined in a configuration
file, and 1 represents the first database backend. In some uncommon cases
there may be more than one database backend configured, so
potentially there may be a 2. In any case, Kea iterates over all
backends configured.
For instance, retrieving host reservations for the subnet 1 and
requesting the first page can be done by:
::
{
"command": "reservation-get-page",
"arguments": {
"subnet-id": 1,
"limit": 10
}
}
Since this is the first call, ``source-index`` and ``from`` should not be
specified. They are set to their zero default values.
Some hosts are returned with information to get the next page:
::
{
"arguments": {
"count": 72,
"hosts": [
{
"boot-file-name": "bootfile.efi",
"client-classes": [ ],
"hostname": "somehost.example.org",
"hw-address": "01:02:03:04:05:06",
"ip-address": "192.0.2.100",
"next-server": "192.0.0.2",
"option-data": [ ],
"server-hostname": "server-hostname.example.org"
},
{
"boot-file-name": "bootfile.efi",
"client-classes": [ ],
"hostname": "otherhost.example.org",
"hw-address": "01:02:03:04:05:ff",
"ip-address": "192.0.2.200",
"next-server": "192.0.0.2",
"option-data": [ ],
"server-hostname": "server-hostname.example.org"
[#2827] fixed all json examples in arm
2023-05-05 15:04:16 +03:00
},
...
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
],
"next": {
"from": 1234567,
"source-index": 1
}
},
"result": 0,
"text": "72 IPv4 host(s) found."
}
Note that the ``from`` and ``source-index`` fields were specified in the response in
the next map. Those two must be copied to the next command, so Kea
continues from the place where the last command finished. To get the
next page the following command can be sent:
::
{
"command": "reservation-get-page",
"arguments": {
"subnet-id": 1,
"source-index": 1,
"from": 1234567,
"limit": 10
}
}
The response will contain a list of hosts with updated ``source-index``
and ``from`` fields. Continue calling the command until the last
page is received. Its response will look like this:
[#2569] add JSON validation to code blocks in ARM
2022-09-23 14:42:03 +03:00
.. code-block:: json
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
{
"arguments": {
"count": 0,
[#2569] add JSON validation to code blocks in ARM
2022-09-23 14:42:03 +03:00
"hosts": [ ]
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
},
"result": 3,
[#2827] fixed all json examples in arm
2023-05-05 15:04:16 +03:00
"text": "0 IPv4 host(s) found."
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
}
[#2815] Update docs
2023-05-09 16:54:24 +02:00
The command doesn't accept the ``operation-target`` argument.
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
This command is more complex than :isccmd:`reservation-get-all`, but lets
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
users retrieve larger host reservations lists in smaller chunks. For
small deployments with few reservations, it is easier to use
[#2554] address review comments
2023-06-13 16:33:13 +03:00
:isccmd:`reservation-get-all`.
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
[#2795] updating ARM docs
2023-06-16 11:43:34 +02:00
.. isccmd:: reservation-get-by-address
.. _command-reservation-get-by-address:
The ``reservation-get-by-address`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:isccmd:`reservation-get-by-address` can be used to query the host database and
[#2795] addressed review comments
2023-06-26 15:42:19 +02:00
retrieve all reservations for given IP address or a delegated prefix (without
a prefix length) in a specified subnet or in all subnets. This command uses
parameters providing the mandatory ``ip-address`` and the optional ``subnet-id``
and ``operation-target``.
[#2795] updating ARM docs
2023-06-16 11:43:34 +02:00
[#2795] addressed review comments
2023-06-26 15:42:19 +02:00
For instance, retrieving host reservations for the IPv4 address "192.0.200.181"
in the subnet 1:
[#2795] updating ARM docs
2023-06-16 11:43:34 +02:00
::
{
"command": "reservation-get-by-address",
"arguments": {
"ip-address": "192.0.200.181",
"subnet-id": 1
},
"service": [
"dhcp4"
]
}
[#2795] addressed review comments
2023-06-26 15:42:19 +02:00
can return two IPv4 hosts:
[#2795] updating ARM docs
2023-06-16 11:43:34 +02:00
::
{
"arguments": {
"hosts": [
{
"boot-file-name": "",
"client-classes": [],
"hostname": "",
"hw-address": "99:99:99:99:99:01",
"ip-address": "192.0.200.181",
"next-server": "0.0.0.0",
"option-data": [],
"server-hostname": "",
"subnet-id": 1
},
{
"boot-file-name": "",
"circuit-id": "1234",
"client-classes": [],
"hostname": "",
"ip-address": "192.0.200.181",
"next-server": "0.0.0.0",
"option-data": [],
"server-hostname": "",
"subnet-id": 1
}
]
},
"result": 0,
"text": "2 IPv4 host(s) found."
}
To search for all reservations in all subnets simply skip the ``subnet-id`` parameter:
::
{
"command": "reservation-get-by-address",
"arguments": {
"ip-address": "192.0.200.181"
},
"service": [
"dhcp4"
]
}
[#2795] addressed review comments
2023-06-26 15:42:19 +02:00
An example response can be:
[#2795] updating ARM docs
2023-06-16 11:43:34 +02:00
::
{
"arguments": {
"hosts": [
{
"boot-file-name": "",
"client-classes": [],
"hostname": "",
"hw-address": "99:99:99:99:99:01",
"ip-address": "192.0.200.181",
"next-server": "0.0.0.0",
"option-data": [],
"server-hostname": "",
"subnet-id": 1
},
{
"boot-file-name": "",
"circuit-id": "1234",
"client-classes": [],
"hostname": "",
"ip-address": "192.0.200.181",
"next-server": "0.0.0.0",
"option-data": [],
"server-hostname": "",
"subnet-id": 1
},
{
"boot-file-name": "",
"client-classes": [],
"hostname": "",
"hw-address": "99:99:99:99:99:02",
"ip-address": "192.0.200.181",
"next-server": "0.0.0.0",
"option-data": [],
"server-hostname": "",
"subnet-id": 0
},
{
"boot-file-name": "",
"client-classes": [],
"hostname": "",
"hw-address": "99:99:99:99:99:03",
"ip-address": "192.0.200.181",
"next-server": "0.0.0.0",
"option-data": [],
"server-hostname": "",
"subnet-id": 2
}
]
},
"result": 0,
"text": "4 IPv4 host(s) found."
}
[#2795] doc update with IPv6 PD use case
2023-06-22 13:04:37 +02:00
When using the command for retrieving DHCP6 host reservations, one can provide
[#2795] addressed review comments
2023-06-26 15:42:19 +02:00
either an IPv6 address or a delegated prefix as the ``ip-address`` parameter.
Please notice that this command does not take prefix length as a parameter in the
current implementation. That's why searching by an IP address ``2001:db8:2:cafe::``
can return host reservations having delegated prefixes matching this search with
different lengths. For example: ``2001:db8:2:cafe::/63``, ``2001:db8:2:cafe::/64`` etc.
Please consider the example below:
[#2795] doc update with IPv6 PD use case
2023-06-22 13:04:37 +02:00
::
{
"command": "reservation-get-by-address",
"arguments": {
"ip-address": "2001:db8:2:cafa::"
},
"service": [
"dhcp6"
]
}
Response:
::
{
"arguments": {
"hosts": [
{
"client-classes": [],
"duid": "01:02:03:04:05:06:07:88:98:fa",
"hostname": "foo.example.com",
"ip-addresses": [
"2001:db8:1:cafe::2"
],
"option-data": [],
"prefixes": [
"2001:db8:2:abcd::/64",
"2001:db8:2:cafa::/63"
],
"subnet-id": 8
},
{
"client-classes": [],
"duid": "01:02:03:04:05:06:07:88:98:fb",
"hostname": "foo.example.com",
"ip-addresses": [
"2001:db8:1:cafe::2"
],
"option-data": [],
"prefixes": [
"2001:db8:2:abcd::/64",
"2001:db8:2:cafa::/64"
],
"subnet-id": 8
}
]
},
"result": 0,
"text": "2 IPv6 host(s) found."
}
[#2795] updating ARM docs
2023-06-16 11:43:34 +02:00
The command accepts the ``operation-target`` argument. By default, it gets the
reservation from both JSON configuration and the hosts database.
.. code-block:: json
{
"command": "reservation-get-by-address",
"arguments": {
"ip-address": "192.0.200.181",
"subnet-id": 1,
"operation-target": "alternate"
},
"service": [
"dhcp4"
]
}
.. note::
This command is useful in specific cases. By default, having more than
one host reservation for the same IP address in a given subnet is not allowed,
as explained in the
:ref:`Multiple Reservations for the Same IPv4 <multiple-reservations-same-ip4>`
or in the
:ref:`Multiple Reservations for the Same IPv6 <multiple-reservations-same-ip6>`.
That's why this command comes in handy
when the ``ip-reservations-unique`` boolean parameter is set to ``false``.
Other use case of this command is having overlapping subnets and having
the same IP address reservation (but with different identifier) in different
subnets.
[#2554] add 'isccmd' anchors
2023-06-06 13:33:44 +03:00
.. isccmd:: reservation-get-by-hostname
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
.. _command-reservation-get-by-hostname:
The ``reservation-get-by-hostname`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
:isccmd:`reservation-get-by-hostname` can be used to query the host database and
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
retrieve all reservations with a specified hostname or in
a specified subnet. This command uses parameters providing the mandatory
``hostname`` and the optional ``subnet-id``. Global host reservations
can be retrieved by using a ``subnet-id`` value of zero (0).
Hostname matching is case-insensitive.
For instance, retrieving host reservations for "foobar" in the subnet 1:
::
{
"command": "reservation-get-by-hostname",
"arguments": {
"hostname": "foobar.example.org",
"subnet-id": 1
}
}
returns some IPv4 hosts:
::
{
"arguments": {
"hosts": [
{
"boot-file-name": "bootfile.efi",
"client-classes": [ ],
"hostname": "foobar.example.org",
"hw-address": "01:02:03:04:05:06",
"ip-address": "192.0.2.100",
"next-server": "192.0.0.2",
"option-data": [ ],
"server-hostname": "server-hostname.example.org"
},
{
"boot-file-name": "bootfile.efi",
"client-classes": [ ],
"hostname": "foobar.example.org",
"hw-address": "01:02:03:04:05:ff",
"ip-address": "192.0.2.200",
"next-server": "192.0.0.2",
"option-data": [ ],
"server-hostname": "server-hostname.example.org"
[#2827] fixed all json examples in arm
2023-05-05 15:04:16 +03:00
},
...
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
]
},
"result": 0,
"text": "5 IPv4 host(s) found."
}
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
The response returned by :isccmd:`reservation-get-by-hostname` can be long,
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
particularly when responses are not limited to a subnet.
[#2815] Update docs
2023-05-09 16:54:24 +02:00
The command accepts the ``operation-target`` argument. By default, it gets the
reservation from both JSON configuration and the hosts database.
.. code-block:: json
{
"command": "reservation-get-by-hostname",
"arguments": {
"hostname": "foobar.example.org",
"subnet-id": 1,
"operation-target": "alternate"
}
}
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
For more information, see :ref:`command-reservation-get-by-hostname`.
.. note::
When using MySQL as the host backend, this command relies on the fact
that the hostname column in the hosts table uses a case-insensitive
collation, as explained in the :ref:`mysql-database` section of
:ref:`admin`.
[#2554] add 'isccmd' anchors
2023-06-06 13:33:44 +03:00
.. isccmd:: reservation-get-by-id
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
.. _command-reservation-get-by-id:
The ``reservation-get-by-id`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
:isccmd:`reservation-get-by-id` can be used to query the host database and
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
retrieve all reservations with a specified identifier (``identifier-type``
and ``identifier`` parameters), independently of subnets. The syntax for
[#2554] address review comments
2023-06-13 16:33:13 +03:00
parameters is the same as for :isccmd:`reservation-get`.
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
The ``subnet-id`` parameter cannot be used, to avoid confusion.
This command is available since Kea version 1.9.0.
For instance, retrieving host reservations for the 01:02:03:04:05:06 MAC
address:
::
{
"command": "reservation-get-by-id",
"arguments": {
"identifier-type": "hw-address",
"identifier": "01:02:03:04:05:06"
}
}
returns some IPv4 hosts:
::
{
"arguments": {
"hosts": [
{
"boot-file-name": "bootfile.efi",
"client-classes": [ ],
"hostname": "foo.example.org",
"hw-address": "01:02:03:04:05:06",
"ip-address": "192.0.2.100",
"next-server": "192.0.0.2",
"option-data": [ ],
"server-hostname": "server-hostname.example.org",
"subnet-id": 123
},
{
"boot-file-name": "bootfile.efi",
"client-classes": [ ],
"hostname": "bar.example.org",
"hw-address": "01:02:03:04:05:06",
"ip-address": "192.0.2.200",
"next-server": "192.0.0.2",
"option-data": [ ],
"server-hostname": "server-hostname.example.org",
"subnet-id": 345
[#2827] fixed all json examples in arm
2023-05-05 15:04:16 +03:00
},
...
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
]
},
"result": 0,
"text": "5 IPv4 host(s) found."
}
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
The response returned by :isccmd:`reservation-get-by-id` can be long,
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
particularly when responses are not limited to a subnet.
[#2815] Update docs
2023-05-09 16:54:24 +02:00
The command accepts the ``operation-target`` argument. By default, it gets the
reservation from both JSON configuration and the hosts database.
.. code-block:: json
{
"command": "reservation-get-by-id",
"arguments": {
"identifier-type": "hw-address",
"identifier": "01:02:03:04:05:06",
"operation-target": "alternate"
}
}
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
For more information, see :ref:`command-reservation-get-by-id`.
[#2554] add 'isccmd' anchors
2023-06-06 13:33:44 +03:00
.. isccmd:: reservation-del
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
.. _command-reservation-del:
The ``reservation-del`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
:isccmd:`reservation-del` can be used to delete a reservation from the host
[#2815] Update docs
2023-05-09 16:54:24 +02:00
database and/or JSON configuration. This command supports two types of parameters:
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
(``subnet-id``, ``address``) or (``subnet-id``, ``identifier-type``, ``identifier``). The
first type of query is used when the address (either IPv4 or IPv6) is
known, but the details of the reservation are not. One common use for
this type of query is to remove a reservation (e.g. a specific
address should no longer be reserved). The second query uses identifiers.
For maximum flexibility, Kea stores the host identifying information as
a pair of values: the type and the actual identifier. Currently supported
identifiers are ``"hw-address"``, ``"duid"``, ``"circuit-id"``, ``"client-id"``, and
``"flex-id"``. The ``subnet-id`` is mandatory. Use a value
of zero (0) to delete a global reservation, or the ID of the subnet from
which the reservation should be deleted.
An example command for deleting a host reservation by (``subnet-id``,
``address``) pair looks as follows:
::
{
"command": "reservation-del",
"arguments": {
"subnet-id": 1,
"ip-address": "192.0.2.202"
}
}
An example deletion by (``subnet-id``, ``identifier-type``, ``identifier``) looks as
follows:
::
{
"command": "reservation-del",
[#2827] fixed all json examples in arm
2023-05-05 15:04:16 +03:00
"arguments": {
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
"subnet-id": 4,
"identifier-type": "hw-address",
"identifier": "01:02:03:04:05:06"
}
}
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
Command :isccmd:`reservation-del` returns a result of 0 when the host deletion was
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
successful, or 1 if it failed. Descriptive text is provided in the event of
an error. Here are some examples of possible results:
::
{
"result": 1,
"text": "Host not deleted (not found)."
}
[#2827] fixed all json examples in arm
2023-05-05 15:04:16 +03:00
or
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
::
{
"result": 0,
"text": "Host deleted."
}
[#2827] fixed all json examples in arm
2023-05-05 15:04:16 +03:00
or
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
::
{
"result": 1,
[#2827] fixed all json examples in arm
2023-05-05 15:04:16 +03:00
"text": "Unable to delete a host because there is no hosts-database configured."
[#2403] Editorial review of documentation about hook libraries in the ARM
2022-05-11 22:05:43 +00:00
}
[#2566] Added a ChangeLog entry
2022-10-07 18:23:21 +02:00
[#2815] Update docs
2023-05-09 16:54:24 +02:00
The command accepts the ``operation-target`` argument. By default, it removes
the reservation from the hosts database only.
.. code-block:: json
{
"command": "reservation-del",
"arguments": {
"subnet-id": 4,
"identifier-type": "hw-address",
"identifier": "01:02:03:04:05:06",
"operation-target": "primary"
}
}
[#2554] add 'isccmd' anchors
2023-06-06 13:33:44 +03:00
.. isccmd:: reservation-update
[#549] document reservation-update
2023-04-05 14:39:12 +03:00
.. _command-reservation-update:
The ``reservation-update`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
:isccmd:`reservation-update` allows for the update of an existing host. It takes the
[#2554] address review comments
2023-06-13 16:33:13 +03:00
same set of arguments as :isccmd:`reservation-add`, and just as well,
[#549] document reservation-update
2023-04-05 14:39:12 +03:00
requires a host identifier and a subnet ID to identify the host that is being
updated. The command can be as simple as having only the two mandatory entries:
.. code-block:: json
{
"command": "reservation-update",
"arguments": {
"reservation": {
"subnet-id": 1,
"hw-address": "1a:1b:1c:1d:1e:1f"
}
}
}
In that case, however, it does not assign any resources to the host. An IPv4
address can be assigned like so:
.. code-block:: json
{
"command": "reservation-update",
"arguments": {
"reservation": {
"subnet-id": 1,
"hw-address": "1a:1b:1c:1d:1e:1f",
"ip-address": "192.0.2.202"
}
}
}
[#549] address review comments
2023-04-19 19:19:44 +03:00
It can also take many more parameters, for example:
[#549] document reservation-update
2023-04-05 14:39:12 +03:00
.. code-block:: json
{
"command": "reservation-update",
"arguments": {
"reservation": {
"subnet-id": 1,
"client-id": "01:0a:0b:0c:0d:0e:0f",
"ip-address": "192.0.2.205",
"next-server": "192.0.2.1",
"server-hostname": "hal9000",
"boot-file-name": "/dev/null",
"option-data": [
{
"name": "domain-name-servers",
"data": "10.1.1.202,10.1.1.203"
}
],
"client-classes": [
"office",
"special_snowflake"
]
}
}
}
Here is an example of a complex IPv6 reservation update:
.. code-block:: json
{
"command": "reservation-update",
"arguments": {
"reservation": {
"subnet-id": 1,
"duid": "01:02:03:04:05:06:07:08:09:0A",
"ip-addresses": [
"2001:db8:1:cafe::1"
],
"prefixes": [
"2001:db8:2:abcd::/64"
],
"hostname": "foo.example.com",
"option-data": [
{
"name": "vendor-opts",
"data": "4491"
},
{
"name": "tftp-servers",
"space": "vendor-4491",
"data": "3000:1::234"
}
]
}
}
}
The command returns a status that indicates either success (result ``0``) or
failure (result ``1``) and a text parameter that confirms success or explains
the cause of the failure. Here's an example of a successful update:
.. code-block:: json
{
"result": 0,
"text": "Host updated."
}
And here's an example of a failure:
.. code-block:: json
{
"result": 1,
"text": "Mandatory 'subnet-id' parameter missing."
}
[#2815] Update docs
2023-05-10 11:44:55 +02:00
The command accepts the ``operation-target`` argument. By default, it adds the
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
reservation to the hosts database only. As :isccmd:`reservation-update` is expected
[#2815] Update docs
2023-05-10 11:44:55 +02:00
to store the host, the ``hosts-databases`` parameter must be specified in the
configuration, and databases must not run in read-only mode if the operation
target is not the JSON configuration.
[#549] document reservation-update
2023-04-05 14:39:12 +03:00
As with other update and set commands, this command overwrites all the contents
of the entry. If the host previously had a resource assigned to it, and the
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
:isccmd:`reservation-update` command is missing the resource, it is deleted from the
[#549] document reservation-update
2023-04-05 14:39:12 +03:00
database. If an incremental update of the host is desired, then this can be
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
achieved by doing a :isccmd:`reservation-get-by-id` to get the current state of the
[#549] document reservation-update
2023-04-05 14:39:12 +03:00
host, picking the host out of the response, modifying it to the required
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
outcome, and then issuing the :isccmd:`reservation-update` command with the resulting
[#549] document reservation-update
2023-04-05 14:39:12 +03:00
host attached.
.. _hooks-host-cmds-general-mentions:
General Mentions
~~~~~~~~~~~~~~~~
[#2566] Added a ChangeLog entry
2022-10-07 18:23:21 +02:00
.. note::
[#2566] Reworded the note in doc about backend not supporting host collections
2022-10-18 11:05:59 +03:00
The host cache and RADIUS hook libraries are two host backends that do not
[#2804] Text edits
2023-04-07 15:12:25 +00:00
respond to commands that return a collection of host reservations, such as
[#2554] add 'isccmd' references The commands used were: - find doc/sphinx/arm -name '*.rst' | xargs grep -E '^\.\. ' | cut -d ' ' -f 2 | sort -uV | grep _command- > /tmp/commands - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\` command/\`${i} command <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/\`\`${i}\`\`/\`${i} <_command-${i}>\`/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/The \`${i} <_command-${i}>\` Command/The \`\`${i}\`\` Command/g"; done - for i in $(cat /tmp/commands); do find doc/sphinx/arm -name '*.rst' | xargs sed -i "s/- ${i}/- \`${i} <_command-${i}>\`/g"; done But they were not perfect. Some manual adjustment was required.
2023-06-06 13:43:28 +03:00
:isccmd:`reservation-get-all`. Commands returning one host entry or dedicated host
[#2566] Reworded the note in doc about backend not supporting host collections
2022-10-18 11:05:59 +03:00
cache commands should be used instead.
Reference in New Issue Copy Permalink