From: Tomek Mrugalski Date: Sat, 21 Oct 2017 16:34:54 +0000 (+0100) Subject: [5396] Documentation for new shared network commands written. X-Git-Tag: Kea-1.3.0~2^2~12^2~7 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=85e19e9167e6622c0d260b70cffceed065da0e27;p=thirdparty%2Fkea.git [5396] Documentation for new shared network commands written. --- diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index eaa5d131e2..fb9dce08c4 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -1670,12 +1670,15 @@ as follows: subnet_cmds: Subnet Commands This section describes a hook application that offers a number of new - commands used to query and manipulate subnet configurations in Kea. - This application is very useful in deployments with a large number of - subnets being managed by the DHCP servers and when the subnets are - frequently updated. The commands offer lightweight approach for - manipulating subnets without a need to fully reconfigure the server - and without affecting existing servers' configurations. + commands used to query and manipulate subnet and shared network + configurations in Kea. This application is very useful in deployments + with a large number of subnets being managed by the DHCP servers and + when the subnets are frequently updated. The commands offer + lightweight approach for manipulating subnets without a need 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, adding + subnets to and removing from shared networks) is also provided. Currently this library is only available to ISC customers with a @@ -1689,7 +1692,7 @@ as follows: - subnet4-get/subnet6-get: retrieves detailed information about a selected subnet + subnet4-get/subnet6-get: retrieves detailed information about a specified subnet @@ -1702,6 +1705,45 @@ as follows: subnet4-del/subnet6-del: removes a subnet from the server's configuration + + + + network4-list/network6-list: lists all configured + shared networks + + + + + network4-get/network6-get: retrieves detailed + information about specified shared network + + + + + network4-add/network6-add: adds a new shared + network to the server's configuration + + + + + network4-del/network6-del: removes a shared + network from the server's configuration + + + + + network4-subnet-add/network6-subnet-add: adds + existing subnet to existing shared network + + + + + network4-subnet-del/network6-subnet-del: removes + a subnet from existing shared network and demotes it to a plain + subnet. + + + @@ -2125,8 +2167,303 @@ If the subnet exists the response will be similar to this: +
+ network4-list, network6-list commands + + These commands are used to retrieve 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 + network4-get or 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 network4-list looks as follows: + +{ + "arguments": { + "shared-networks": [ + { "name": "floor1" }, + { "name": "office" } + ] + }, + "result": 0, + "text": "2 IPv4 network(s) found" +} +network6-list follows exactly the same syntax for +both the query and the response. + +
+ +
+ network4-get, network6-get commands + + These commands are used to retrieve detailed information + about shared networks, including subnets currently + being part of a given network. Both commands take one + mandatory parameter name, which specify + the name of shared network. An example command to retrieve + details about IPv4 shared network with a 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", + "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 + } + ] + } +} + +Note that actual response contains many additional fields that are +omitted here for clarity. The response format is exactly the same as +used in config-get, just is limited to returning +shared networks information. + +
+ +
+ network4-add, network6-add commands + + These commands are used to add a new shared network. New + network has to have 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 + allowed 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 with only one subnet) is + discouraged in production environments. For details regarding + syntax, see and . + + As opposed to parameter inheritance during full + new configuration processing, this command does not fully handle + parameter inheritance and any missing parameters will be + filled with default values, rather than inherited from + 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 id +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 network6-add uses the same syntax for both the query and +the response. However, there are some parameters that are IPv4-only +(e.g. match-client-id) and some are IPv6-only (e.g. interface-id). The same +applies to subnets within the network. + +
+
+ network4-del, network6-del commands + + These commands are used to delete existing shared networks. Each + subnet within the network being removed will be demoted to a plain + network. If you want to competely remove the subnets, please use + subnet4-del or subnet6-del + commands. Both commands take exactly one parameter 'name' that + specifies the name of the network to be removed. An example invocation + of 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": "floor1" + } + ] + }, + "result": 0, + "text": "IPv4 shared network 'floor13' deleted" +} +The network6-del command uses exactly the same syntax for +both the command and the response. + + +
+
+ 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 new shared network. System + administrator can add the whole shared network at once, either by + editing a configuration file or by calling + network4-add or network6-add + commands with desired subnets in it. This approach works better 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 has to be + added on top of it. For this scenario, a system administrator can use + network4-add or network6-add and + then add existing subnet to this newly created shared network using + network4-subnet-add or + network6-subnet-add. + + + The network4-subnet-add and + network6-subnet-add commands take two parameters: + id, which is an integer and specifies subnet-id of existing subnet to + be added to a shared network; and name, which + specifies name of the shared network the subnet will be added to. The + subnet must not belong to any existing network. In case you want to + reassign a subnet from one shared network to another, please use + network4-subnet-del or + network6-subnet-del commands first. + + + An example invocation of network4-subnet-add + command looks as follows: + +{ + "command": "network4-subnet-add", + "arguments": { + "name": "floor13", + "id": 5 + } +} +Assuming there is a network named 'floor13', there is a subnet with subnet-id 5 +and it is not a part of 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 'floor1'" +} + The network6-subnet-add command uses exactly the same syntax for +both the command and the response. + + + As opposed to parameter inheritance during full + new configuration processing or when adding a new shared network with + new subnets, this command does not fully handle + parameter inheritance and any missing parameters will be + filled with default values, rather than inherited from + global scope or from the shared network. +
+
+ network4-subnet-del, network6-subnet-del commands + + These commands are used to remove a subnet that is part of existing shared + network and demote it to a plain, stand-alone subnet. The + network4-subnet-del and + network6-subnet-del commands take two parameters: + id, which is an integer and specifies subnet-id of + existing subnet to be removed from a shared network; and + name, which specifies name of the shared network + the subnet will be removed from. + + An example invocation of the + network4-subnet-del command looks as follows: + + { + "command": "network4-subnet-del", + "arguments": { + "name": "floor13", + "id": 5 + } + } + Assuming there was a subnet with subnet-id equal to 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 network6-subnet-del command uses exactly the same syntax for +both the command and the response. + +
+ - +
User contexts