.. ischooklib:: libdhcp_subnet_cmds.so
.. _hooks-subnet-cmds:

``libdhcp_subnet_cmds.so``: Subnet Commands to Manage Subnets and Shared Networks
=================================================================================

This library offers commands used to query and manipulate subnet and shared network
configurations in Kea. These can be very useful in deployments
with a large number of subnets being managed by the DHCP servers,
when those subnets are frequently updated. The commands offer a lightweight
approach for manipulating subnets without needing to fully reconfigure
the server, and without affecting existing servers' configurations. An
ability to manage shared networks (listing, retrieving details, adding
new ones, removing existing ones, and adding subnets to and removing them from
shared networks) is also provided.

.. note::

    :ischooklib:`libdhcp_subnet_cmds.so` is available only to ISC customers with
    a paid support contract. For more information on subscription options,
    please complete the form at https://www.isc.org/contact.

.. note::

   This library can only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6`
   process.

The following commands are currently supported:

-  :isccmd:`subnet4-list` / :isccmd:`subnet6-list` - lists all configured subnets.

-  :isccmd:`subnet4-get` / :isccmd:`subnet6-get` - retrieves detailed information about a
   specified subnet.

-  :isccmd:`subnet4-add` / :isccmd:`subnet6-add` - adds a new subnet into the server's
   configuration.

-  :isccmd:`subnet4-update` / :isccmd:`subnet6-update` - updates (replaces) a single subnet in
   the server's configuration.

-  :isccmd:`subnet4-del` / :isccmd:`subnet6-del` - removes a subnet from the server's
   configuration.

-  :isccmd:`subnet4-delta-add` / :isccmd:`subnet6-delta-add` - updates (replaces) parts of a
   single subnet in the server's configuration.

-  :isccmd:`subnet4-delta-del` / :isccmd:`subnet6-delta-del` - removes parts of a single subnet in
   the server's configuration.

-  :isccmd:`network4-list` / :isccmd:`network6-list` - lists all configured shared networks.

-  :isccmd:`network4-get` / :isccmd:`network6-get` - retrieves detailed information about a
   specified shared network.

-  :isccmd:`network4-add` / :isccmd:`network6-add` - adds a new shared network to the
   server's configuration.

-  :isccmd:`network4-del` / :isccmd:`network6-del` - removes a shared network from the
   server's configuration.

-  :isccmd:`network4-subnet-add` / :isccmd:`network6-subnet-add` - adds an existing subnet to
   an existing shared network.

-  :isccmd:`network4-subnet-del` / :isccmd:`network6-subnet-del` - removes a subnet from
   an existing shared network and demotes it to a plain subnet.

.. isccmd:: subnet4-list
.. _command-subnet4-list:

The ``subnet4-list`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to list all currently configured subnets. Each
subnet is returned with a subnet identifier and
subnet prefix. To retrieve
detailed information about the subnet, use the :isccmd:`subnet4-get` command.

This command has a simple structure:

::

   {
       "command": "subnet4-list"
   }

The list of subnets is returned in the following format:

::

   {
       "result": 0,
       "text": "2 IPv4 subnets found",
       "arguments": {
       "subnets": [
           {
               "id": 10,
               "subnet": "10.0.0.0/8"
           },
           {
               "id": 100,
               "subnet": "192.0.2.0/24"
           }
       ]
       }
   }

If no IPv4 subnets are found, an error code is returned along with the
error description.

.. isccmd:: subnet6-list
.. _command-subnet6-list:

The ``subnet6-list`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to list all currently configured subnets. Each
subnet is returned with a subnet identifier and
subnet prefix. To retrieve
detailed information about the subnet, use the :isccmd:`subnet6-get` command.

This command has a simple structure:

::

   {
       "command": "subnet6-list"
   }

The list of subnets is returned in the following format:

::

   {
       "result": 0,
       "text": "2 IPv6 subnets found",
       "arguments": {
       "subnets": [
           {
               "id": 11,
               "subnet": "2001:db8:1::/64"
           },
           {
               "id": 233,
               "subnet": "3000::/16"
           }
       ]
       }
   }

If no IPv6 subnets are found, an error code is returned along with the
error description.

.. isccmd:: subnet4-get
.. _command-subnet4-get:

The ``subnet4-get`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to retrieve detailed information about the
specified subnet. This command usually follows :isccmd:`subnet4-list`,
which is used to discover available subnets with their respective subnet
identifiers and prefixes. Any of those parameters can then be used in
:isccmd:`subnet4-get` to fetch subnet information:

::

   {
       "command": "subnet4-get",
       "arguments": {
           "id": 10
       }
   }

or

::

   {
       "command": "subnet4-get",
       "arguments": {
           "subnet": "10.0.0.0/8"
       }
   }

If the subnet exists, the response will be similar to this:

::

   {
       "result": 0,
       "text": "Info about IPv4 subnet 10.0.0.0/8 (id 10) returned",
       "arguments": {
           "subnets": [
               {
                   "subnet": "10.0.0.0/8",
                   "id": 1,
                   "option-data": [
                       {
                           ...
                       },
                       ...
                   ],
                   ...
               }
           ]
       }
   }

.. isccmd:: subnet6-get
.. _command-subnet6-get:

The ``subnet6-get`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to retrieve detailed information about the
specified subnet. This command usually follows :isccmd:`subnet6-list`,
which is used to discover available subnets with their respective subnet
identifiers and prefixes. Any of those parameters can be then used in
:isccmd:`subnet6-get` to fetch subnet information:

::

   {
       "command": "subnet6-get",
       "arguments": {
           "id": 11
       }
   }

or

::

   {
       "command": "subnet6-get",
       "arguments": {
           "subnet": "2001:db8:1::/64"
       }
   }

If the subnet exists, the response will be similar to this:

::

   {
       "result": 0,
       "text": "Info about IPv6 subnet 2001:db8:1::/64 (id 11) returned",
       "arguments": {
           "subnets": [
               {
                   "subnet": "2001:db8:1::/64",
                   "id": 1,
                   "option-data": [
                       {
                           ...
                       },
                       ...
                   ],
                   ...
               }
           ]
       }
   }

.. isccmd:: subnet4-add
.. _command-subnet4-add:

The ``subnet4-add`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to create and add a new subnet to the existing server
configuration. This operation has no impact on other subnets. The subnet
identifier must be specified and must be unique among all subnets. If
the identifier or a subnet prefix is not unique, an error is reported and
the subnet is not added.

The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
:isccmd:`subnet4-add`. The commands described in :ref:`hooks-host-cmds` should be used to
add, remove, and modify static reservations.

::

   {
       "command": "subnet4-add",
       "arguments": {
           "subnet4": [ {
               "id": 123,
               "subnet": "10.20.30.0/24",
               ...
           } ]
       }
   }

The response to this command has the following structure:

::

   {
       "result": 0,
       "text": "IPv4 subnet added",
       "arguments": {
           "subnet4": [
               {
                   "id": 123,
                   "subnet": "10.20.30.0/24"
               }
           ]
       }
   }

.. isccmd:: subnet6-add
.. _command-subnet6-add:

The ``subnet6-add`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to create and add a new subnet to the existing server
configuration. This operation has no impact on other subnets. The subnet
identifier must be specified and must be unique among all subnets. If
the identifier or a subnet prefix is not unique, an error is reported and
the subnet is not added.

The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
:isccmd:`subnet6-add`. The commands described in :ref:`hooks-host-cmds` should be used
to add, remove, and modify static reservations.

::

   {
       "command": "subnet6-add",
       "arguments": {
           "subnet6": [ {
               "id": 234,
               "subnet": "2001:db8:1::/64",
               ...
           } ]
       }
   }

The response to this command has the following structure:

::

   {
       "result": 0,
       "text": "IPv6 subnet added",
       "arguments": {
           "subnet6": [
               {
                   "id": 234,
                   "subnet": "2001:db8:1::/64"
               }
           ]
       }
   }

It is recommended, but not mandatory, to specify the subnet ID. If not
specified, Kea will try to assign the next ``subnet-id`` value. This
automatic ID value generator is simple; it returns the previous
automatically assigned value, increased by 1. This works well, unless
a subnet is manually created with a larger value than one previously used. For
example, if :isccmd:`subnet4-add` is called five times, each without an ID, Kea will
assign IDs 1, 2, 3, 4, and 5 and it will work just fine. However, if
:isccmd:`subnet4-add` is called five times, with the first subnet having the
``subnet-id`` of value 3 and the remaining ones having no ``subnet-id``, the operation will
fail. The first command (with the explicit value) will use ``subnet-id`` 3; the
second command will create a subnet with and ID of 1; the third will use a
value of 2; and finally the fourth will have its ``subnet-id`` value
auto-generated as 3. However, since there is already a subnet with that
ID, the process will fail.

The general recommendation is either never to use explicit values, so
that auto-generated values will always work; or always use explicit
values, so that auto-generation is never used. The two
approaches can be mixed only if the administrator understands how internal
automatic ``subnet-id`` generation works in Kea.

.. note::

   Subnet IDs must be greater than zero and less than 4294967295.

.. isccmd:: subnet4-update
.. _command-subnet4-update:

The ``subnet4-update`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to update (overwrite) a single subnet in the existing
server configuration. This operation has no impact on other subnets. The
subnet identifier is used to identify the subnet to replace; it must be
specified and must be unique among all subnets. The subnet prefix should
not be updated.

The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
:isccmd:`subnet4-update`. The commands described in :ref:`hooks-host-cmds` should be
used to update, remove, and modify static reservations.

::

   {
       "command": "subnet4-update",
       "arguments": {
           "subnet4": [ {
               "id": 123,
               "subnet": "10.20.30.0/24",
               ...
           } ]
       }
   }

The response to this command has the following structure:

::

   {
       "result": 0,
       "text": "IPv4 subnet updated",
       "arguments": {
           "subnet4": [
               {
                   "id": 123,
                   "subnet": "10.20.30.0/24"
               }
           ]
       }
   }

As with other update commands, this command overwrites all the contents of the
entry. If the IPv4 subnet previously had a resource assigned to it, and the
:isccmd:`subnet4-update` command is missing the resource, it is deleted from the
server configuration. If an incremental update of the subnet is desired, then
this can be achieved with :isccmd:`subnet4-delta-add`.

.. isccmd:: subnet6-update
.. _command-subnet6-update:

The ``subnet6-update`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to update (overwrite) a single subnet in the existing
server configuration. This operation has no impact on other subnets. The
subnet identifier is used to identify the subnet to replace; it must be
specified and must be unique among all subnets. The subnet prefix should
not be updated.

The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
:isccmd:`subnet6-update`. The commands described in :ref:`hooks-host-cmds` should be
used to update, remove, and modify static reservations.

::

   {
       "command": "subnet6-update",
       "arguments": {
           "subnet6": [ {
               "id": 234,
               "subnet": "2001:db8:1::/64",
               ...
           } ]
       }
   }

The response to this command has the following structure:

::

   {
       "result": 0,
       "text": "IPv6 subnet updated",
       "arguments": {
           "subnet6": [
               {
                   "id": 234,
                   "subnet": "2001:db8:1::/64"
               }
           ]
       }
   }

As with other update commands, this command overwrites all the contents of the
entry. If the IPv6 subnet previously had a resource assigned to it, and the
:isccmd:`subnet6-update` command is missing the resource, it is deleted from the
server configuration. If an incremental update of the subnet is desired, then
this can be achieved with :isccmd:`subnet6-delta-add`.

.. isccmd:: subnet4-del
.. _command-subnet4-del:

The ``subnet4-del`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to remove a subnet from the server's configuration.
This command has no effect on other configured subnets, but removing a
subnet does have certain implications.

In most cases the server has assigned some leases to the clients
belonging to the subnet. The server may also be configured with static
host reservations which are associated with this subnet. The current
implementation of the :isccmd:`subnet4-del` command removes neither the leases nor
the host reservations associated with a subnet. This is the safest approach
because the server does not lose track of leases assigned to clients
from this subnet. However, removal of the subnet may still cause
configuration errors and conflicts. For example: after removal of the
subnet, the server administrator may update a new subnet with the ID
used previously for the removed subnet. This means that the existing
leases and static reservations will be in conflict with this new subnet.
Thus, we recommend that this command be used with extreme caution.

This command can also be used to completely delete an IPv4 subnet that
is part of a shared network. To simply remove the subnet
from a shared network and keep the subnet configuration, use the
:isccmd:`network4-subnet-del` command instead.

The command has the following structure:

::

   {
       "command": "subnet4-del",
       "arguments": {
           "id": 123
       }
   }

A successful response may look like this:

::

   {
       "result": 0,
       "text": "IPv4 subnet 192.0.2.0/24 (id 123) deleted",
       "arguments": {
           "subnets": [
               {
                   "id": 123,
                   "subnet": "192.0.2.0/24"
               }
           ]
       }
   }

.. isccmd:: subnet6-del
.. _command-subnet6-del:

The ``subnet6-del`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to remove a subnet from the server's configuration.
This command has no effect on other configured subnets, but removing a
subnet does have certain implications.

In most cases the server has assigned some leases to the clients
belonging to the subnet. The server may also be configured with static
host reservations which are associated with this subnet. The current
implementation of the :isccmd:`subnet6-del` command removes neither the leases nor
the host reservations associated with a subnet. This is the safest approach
because the server does not lose track of leases assigned to clients
from this subnet. However, removal of the subnet may still cause
configuration errors and conflicts. For example: after removal of the
subnet, the server administrator may add a new subnet with the ID used
previously for the removed subnet. This means that the existing leases
and static reservations will be in conflict with this new subnet. Thus,
we recommend that this command be used with extreme caution.

This command can also be used to completely delete an IPv6 subnet that
is part of a shared network. To simply remove the subnet
from a shared network and keep the subnet configuration, use the
:isccmd:`network6-subnet-del` command instead.

The command has the following structure:

::

   {
       "command": "subnet6-del",
       "arguments": {
           "id": 234
       }
   }

A successful response may look like this:

::

   {
       "result": 0,
       "text": "IPv6 subnet 2001:db8:1::/64 (id 234) deleted",
       "subnets": [
           {
               "id": 234,
               "subnet": "2001:db8:1::/64"
           }
       ]
   }

.. isccmd:: subnet4-delta-add
.. _command-subnet4-delta-add:

The ``subnet4-delta-add`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to update a subnet by adding or overwriting its parts in
the existing server configuration. This operation has no impact on other
subnets. The subnet identifier is used to identify the subnet to update; it must
be specified and must be unique among all subnets. The subnet prefix should not
be updated.

The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
:isccmd:`subnet4-delta-add`. The commands described in :ref:`hooks-host-cmds` should
be used to update, remove, and modify static reservations.

::

   {
       "command": "subnet4-delta-add",
       "arguments": {
           "subnet4": [ {
               "valid-lifetime": 120,
               "id": 123,
               "subnet": "10.20.30.0/24",
               "option-data": [
                   {
                       "always-send": false,
                       "code": 3,
                       "csv-format": true,
                       "data": "192.0.3.1",
                       "name": "routers",
                       "space": "dhcp4"
                   }
               ],
               "pools": [
                   {
                       "pool": "10.20.30.1-10.20.30.10",
                       "option-data": [
                           {
                               "always-send": false,
                               "code": 4,
                               "csv-format": true,
                               "data": "192.0.4.1",
                               "name": "time-servers",
                               "space": "dhcp4"
                           }
                       ]
                   }
               ]
           } ]
       }
   }

The response to this command has the following structure:

::

   {
       "result": 0,
       "text": "IPv4 subnet updated",
       "arguments": {
           "subnet4": [
               {
                   "id": 123,
                   "subnet": "10.20.30.0/24"
               }
           ]
       }
   }

The command updates subnet "10.20.30.0/24" with id 123 by changing the valid
lifetime, adding or changing the subnet level option 3 ("routers"), by adding
or changing the pool "10.20.30.1-10.20.30.10" and by adding or changing the pool
level option 4 ("time-servers").

.. isccmd:: subnet6-delta-add
.. _command-subnet6-delta-add:

The ``subnet6-delta-add`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to update a subnet by adding or overwriting its parts in
the existing server configuration. This operation has no impact on other
subnets. The subnet identifier is used to identify the subnet to update; it must
be specified and must be unique among all subnets. The subnet prefix should not
be updated.

The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
:isccmd:`subnet6-delta-add`. The commands described in :ref:`hooks-host-cmds` should
be used to update, remove, and modify static reservations.

::

   {
       "command": "subnet6-delta-add",
       "arguments": {
           "subnet6": [ {
               "valid-lifetime": 120,
               "id": 243,
               "subnet": "2001:db8:1::/64",
               "option-data": [
                   {
                       "always-send": false,
                       "code": 23,
                       "csv-format": true,
                       "data": "3000::3:1",
                       "name": "dns-servers",
                       "space": "dhcp6"
                   }
               ],
               "pd-pools": [
                   {
                       "prefix": "2001:db8:2::",
                       "prefix-len": 48,
                       "delegated-len": 64,
                       "option-data": [
                           {
                               "always-send": false,
                               "code": 22,
                               "csv-format": true,
                               "data": "3000::4:1",
                               "name": "sip-server-addr",
                               "space": "dhcp6"
                           }
                       ]
                   }
               ],
               "pools": [
                   {
                       "pool": "2001:db8:1::1-2001:db8:1::10",
                       "option-data": [
                           {
                               "always-send": false,
                               "code": 31,
                               "csv-format": true,
                               "data": "3000::5:1",
                               "name": "sntp-servers",
                               "space": "dhcp6"
                           }
                       ]
                   }
               ]
           } ]
       }
   }

The response to this command has the following structure:

::

   {
       "result": 0,
       "text": "IPv6 subnet updated",
       "arguments": {
           "subnet6": [
               {
                   "id": 234,
                   "subnet": "2001:db8:1::/64"
               }
           ]
       }
   }

The command updates subnet "2001:db8:1::/64" with id 243 by changing the valid
lifetime, adding or changing the subnet level option 23 ("dns-servers"), by
adding or changing the pool "2001:db8:1::1-2001:db8:1::10", by adding or
changing the pool level option 31 ("sntp-servers"), by adding or changing the
pd-pool "2001:db8:2::" with prefix-len 48 and by adding or changing the pd-pool
level option 22 ("sip-server-addr").

.. isccmd:: subnet4-delta-del
.. _command-subnet4-delta-del:

The ``subnet4-delta-del`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to update a subnet by removing its parts in the existing
server configuration. This operation has no impact on other subnets.
The subnet identifier is used to identify the subnet to update; it must be
specified and must be unique among all subnets. The subnet prefix should not be
updated.

The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
:isccmd:`subnet4-delta-del`. The commands described in :ref:`hooks-host-cmds` should
be used to update, remove, and modify static reservations.

The command is flexible and can delete the part of the subnet by either
specifying the entire object that needs to be deleted, or just the keys
identifying the respective object. The address pools are identified by the
'pool' parameter, the options are identified by the 'name' or 'code' and
'space' parameters. The 'space' parameter can be omitted if the option belongs
to the default 'dhcp4' space.

::

   {
       "command": "subnet4-delta-del",
       "arguments": {
           "subnet4": [ {
               "valid-lifetime": 0,
               "id": 123,
               "subnet": "10.20.30.0/24",
               "option-data": [
                   { "name": "routers" }
               ],
               "pools": [
                   {
                       "option-data": [
                           { "code": 4 }
                       ],
                       "pool": "10.20.30.11-10.20.30.20"
                   },
                   {
                       "pool": "10.20.30.21-10.20.30.30"
                   }
               ]
           } ]
       }
   }

The response to this command has the following structure:

::

   {
       "result": 0,
       "text": "IPv4 subnet updated",
       "arguments": {
           "subnet4": [
               {
                   "id": 123,
                   "subnet": "10.20.30.0/24"
               }
           ]
       }
   }

The command updates subnet "10.20.30.0/24" with id 123 by removing the valid
lifetime, removing the subnet level option 3 ("routers"), by removing the pool
"10.20.30.21-10.20.30.30" and by removing the pool level option 4
("time-servers") in pool "10.20.30.11-10.20.30.20".
The scalar values don't need to match what is configured, but still need to be
present to maintain a valid json structure and to be a valid value to be able to
be parsed.

.. isccmd:: subnet6-delta-del
.. _command-subnet6-delta-del:

The ``subnet6-delta-del`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This command is used to update a subnet by removing its parts in the existing
server configuration. This operation has no impact on other subnets.
The subnet identifier is used to identify the subnet to update; it must be
specified and must be unique among all subnets. The subnet prefix should not be
updated.

The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
:isccmd:`subnet6-delta-del`. The commands described in :ref:`hooks-host-cmds` should
be used to update, remove, and modify static reservations.

The command is flexible and can delete the part of the subnet by either
specifying the entire object that needs to be deleted, or just the keys
identifying the respective object. The address pools are identified by the
'pool' parameter, the prefix pools are identified by the "prefix", "prefix-len"
and "delegated-len" parameters, the options are identified by the 'name' or
'code' and 'space' parameters. The 'space' parameter can be omitted if the
option belongs to the default 'dhcp6' space.

.. code-block:: json

   {
       "command": "subnet6-delta-del",
       "arguments": {
           "subnet6": [ {
               "valid-lifetime": 0,
               "id": 234,
               "subnet": "2001:db8:1::/64",
               "option-data": [
                   { "name": "dns-servers" }
               ],
               "pd-pools": [
                   {
                       "prefix": "2001:db8:3::",
                       "prefix-len": 48,
                       "delegated-len": 64,
                       "option-data": [
                           { "code": 22 }
                       ]
                   },
                   {
                       "prefix": "2001:db8:4::",
                       "prefix-len": 48,
                       "delegated-len": 64
                   }
               ],
               "pools": [
                   {
                       "option-data": [
                           { "code": 31 }
                       ],
                       "pool": "2001:db8:1::11-2001:db8:1::20"
                   },
                   {
                       "pool": "2001:db8:1::21-2001:db8:1::30"
                   }
               ]
           } ]
       }
   }

The response to this command has the following structure:

::

   {
       "result": 0,
       "text": "IPv6 subnet updated",
       "arguments": {
           "subnet6": [
               {
                   "id": 234,
                   "subnet": "2001:db8:1::/64"
               }
           ]
       }
   }

The command updates subnet "2001:db8:1::/64" with id 243 by removing the valid
lifetime, removing the subnet level option 23 ("dns-servers"), by removing the
pool "2001:db8:1::21-2001:db8:1::30", by removing the pool level option 31
("sntp-servers") in pool "2001:db8:1::11-2001:db8:1::20", by removing the
pd-pool "2001:db8:4::" with prefix-len 48, by removing the pd-pool level option
22 ("sip-server-addr") in pd-pool "2001:db8:3::" with prefix-len 48.
The scalar values don't need to match what is configured, but still need to be
present to maintain a valid json structure and to be a valid value to be able to
be parsed.

.. isccmd:: network4-list
.. _command-network4-list:

.. isccmd:: network6-list
.. _command-network6-list:

The ``network4-list``, ``network6-list`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These commands are used to retrieve the full list of currently configured
shared networks. The list contains only very basic information about
each shared network. If more details are needed, please use
:isccmd:`network4-get` or :isccmd:`network6-get` to retrieve all information
available. This command does not require any parameters and its
invocation is very simple:

::

   {
       "command": "network4-list"
   }

An example response for :isccmd:`network4-list` looks as follows:

::

   {
       "arguments": {
           "shared-networks": [
               { "name": "floor1" },
               { "name": "office" }
           ]
       },
       "result": 0,
       "text": "2 IPv4 network(s) found"
   }

The :isccmd:`network6-list` command uses exactly the same syntax for both the
command and the response.

.. isccmd:: network4-get
.. _command-network4-get:

.. isccmd:: network6-get
.. _command-network6-get:

The ``network4-get``, ``network6-get`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These commands are used to retrieve detailed information about shared
networks, including subnets that are currently part of a given network.
Both commands take one mandatory parameter, ``name``, which specifies the
name of the shared network. An example command to retrieve details about
an IPv4 shared network with the name "floor13" looks as follows:

::

   {
       "command": "network4-get",
       "arguments": {
           "name": "floor13"
       }
   }

An example response could look as follows:

::

   {
       "result": 0,
       "text": "Info about IPv4 shared network 'floor13' returned",
       "arguments": {
           "shared-networks": [
           {
               "match-client-id": true,
               "name": "floor13",
               "option-data": [ ],
               "rebind-timer": 90,
               "relay": {
                   "ip-address": "0.0.0.0"
               },
               "renew-timer": 60,
               # "reservation-mode": "all",
               # It is replaced by the "reservations-global",
               # "reservations-in-subnet", and "reservations-out-of-pool"
               # parameters.
               # Specify if the server should look up global reservations.
               "reservations-global": false,
               # Specify if the server should look up in-subnet reservations.
               "reservations-in-subnet": true,
               # Specify if the server can assume that all reserved addresses
               # are out-of-pool.
               "reservations-out-of-pool": false,
               "subnet4": [
                   {
                       "subnet": "192.0.2.0/24",
                       "id": 5,
                       ...
                       # many other subnet-specific details here
                   },
                   {
                       "id": 6,
                       "subnet": "192.0.3.0/31",
                       ...
                       # many other subnet-specific details here
                   }
               ],
               "valid-lifetime": 120
           }
           ]
       }
   }

The actual response contains many additional fields that are
omitted here for clarity. The response format is exactly the same as
used in :isccmd:`config-get`, just limited to returning the shared network's
information.

.. isccmd:: network4-add
.. _command-network4-add:

.. isccmd:: network6-add
.. _command-network6-add:

The ``network4-add``, ``network6-add`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These commands are used to add a new shared network, which must
have a unique name. This command requires one parameter,
``shared-networks``, which is a list and should contain exactly one
entry that defines the network. The only mandatory element for a network
is its name. Although it does not make operational sense, it is possible
to add an empty shared network that does not have any subnets in it.
That is allowed for testing purposes, but having empty networks (or networks with
only one subnet) is discouraged in production environments. For details
regarding syntax, see :ref:`shared-network4` and
:ref:`shared-network6`.

.. note::

   As opposed to parameter inheritance during the processing of a full new
   configuration, this command does not fully handle parameter inheritance.
   Any missing parameters will be filled with default values, rather
   than inherited from the global scope.

An example that showcases how to add a new IPv4 shared network looks as
follows:

::

   {
       "command": "network4-add",
       "arguments": {
           "shared-networks": [ {
               "name": "floor13",
               "subnet4": [
               {
                   "id": 100,
                   "pools": [ { "pool": "192.0.2.2-192.0.2.99" } ],
                   "subnet": "192.0.2.0/24",
                   "option-data": [
                       {
                           "name": "routers",
                           "data": "192.0.2.1"
                       }
                   ]
               },
               {
                   "id": 101,
                   "pools": [ { "pool": "192.0.3.2-192.0.3.99" } ],
                   "subnet": "192.0.3.0/24",
                   "option-data": [
                       {
                           "name": "routers",
                           "data": "192.0.3.1"
                       }
                   ]
               } ]
           } ]
       }
   }

Assuming there was no shared network with a name "floor13" and no subnets
with IDs 100 and 101 previously configured, the command will be
successful and will return the following response:

::

   {
       "arguments": {
           "shared-networks": [ { "name": "floor13" } ]
       },
       "result": 0,
       "text": "A new IPv4 shared network 'floor13' added"
   }

The :isccmd:`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 that are IPv6-only (e.g. ``interface-id``). The same
applies to subnets within the network.

.. isccmd:: network4-del
.. _command-network4-del:

.. isccmd:: network6-del
.. _command-network6-del:

The ``network4-del``, ``network6-del`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These commands are used to delete existing shared networks. Both
commands take exactly one parameter, ``name``, that specifies the name of
the network to be removed. An example invocation of the :isccmd:`network4-del`
command looks as follows:

::

   {
       "command": "network4-del",
       "arguments": {
           "name": "floor13"
       }
   }

Assuming there was such a network configured, the response will look
similar to the following:

::

   {
       "arguments": {
           "shared-networks": [
               {
                   "name": "floor13"
               }
           ]
       },
       "result": 0,
       "text": "IPv4 shared network 'floor13' deleted"
   }

The :isccmd:`network6-del` command uses exactly the same syntax for both the
command and the response.

If there are any subnets belonging to the shared network being deleted,
they will be demoted to a plain subnet. There is an optional parameter
called ``subnets-action`` that, if specified, takes one of two possible
values: ``keep`` (which is the default) and ``delete``. It controls
whether the subnets are demoted to plain subnets or removed. An example
usage in the :isccmd:`network6-del` command that deletes the shared network and all
subnets in it could look as follows:

::

   {
       "command": "network4-del",
       "arguments": {
           "name": "floor13",
           "subnets-action": "delete"
       }
   }

Alternatively, to completely remove the subnets, it is possible to use the
:isccmd:`subnet4-del` or :isccmd:`subnet6-del` commands.

.. isccmd:: network4-subnet-add
.. _command-network4-subnet-add:

.. isccmd:: network6-subnet-add
.. _command-network6-subnet-add:

The ``network4-subnet-add``, ``network6-subnet-add`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These commands are used to add existing subnets to existing shared
networks. There are several ways to add a new shared network. The system
administrator can add the whole shared network at once, either by
editing a configuration file or by calling the :isccmd:`network4-add` or
:isccmd:`network6-add` command with the desired subnets in it. This approach
works well for completely new shared subnets. However, there may be
cases when an existing subnet is running out of addresses and needs to
be extended with additional address space; in other words, another subnet
needs to be added on top of it. For this scenario, a system administrator
can use :isccmd:`network4-add` or :isccmd:`network6-add`, and then add an existing
subnet to this newly created shared network using
:isccmd:`network4-subnet-add` or :isccmd:`network6-subnet-add`.

The :isccmd:`network4-subnet-add` and
:isccmd:`network6-subnet-add` commands take
two parameters: ``id``, which is an integer and specifies the ID of
an existing subnet to be added to a shared network; and ``name``, which
specifies the name of the shared network to which the subnet will be added. The
subnet must not belong to any existing network; to
reassign a subnet from one shared network to another, use the
:isccmd:`network4-subnet-del` or
:isccmd:`network6-subnet-del` command commands first.

An example invocation of the :isccmd:`network4-subnet-add` command looks as
follows:

::

   {
       "command": "network4-subnet-add",
       "arguments": {
           "name": "floor13",
           "id": 5
       }
   }

Assuming there is a network named "floor13", and there is a subnet with
``subnet-id`` 5 that is not a part of the existing network, the command will
return a response similar to the following:

::

   {
       "result": 0,
       "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor13'"
   }

The :isccmd:`network6-subnet-add` command uses exactly the same syntax for both the
command and the response.

.. note::

   As opposed to parameter inheritance during the processing of a full new
   configuration or when adding a new shared network with new subnets,
   this command does not fully handle parameter inheritance.
   Any missing parameters will be filled with default values, rather
   than inherited from the global scope or from the shared network.

.. isccmd:: network4-subnet-del
.. _command-network4-subnet-del:

.. isccmd:: network6-subnet-del
.. _command-network6-subnet-del:

The ``network4-subnet-del``, ``network6-subnet-del`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These commands are used to remove a subnet that is part of an existing
shared network and demote it to a plain, stand-alone subnet.
To remove a subnet completely, use the :isccmd:`subnet4-del` or :isccmd:`subnet6-del`
commands instead. The :isccmd:`network4-subnet-del` and
:isccmd:`network6-subnet-del` commands take two parameters: ``id``, which is
an integer and specifies the ID of an existing subnet to be removed from
a shared network; and ``name``, which specifies the name of the shared
network from which the subnet will be removed.

An example invocation of the :isccmd:`network4-subnet-del` command looks as
follows:

::

    {
       "command": "network4-subnet-del",
       "arguments": {
           "name": "floor13",
           "id": 5
       }
    }

Assuming there was a subnet with ``subnet-id`` 5, that was part of a
shared network named "floor13", the response would look similar to the
following:

::

   {
       "result": 0,
       "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'"
   }

The :isccmd:`network6-subnet-del` command uses exactly the same syntax for both the
command and the response.