From: Marcin Siodelski Date: Mon, 29 Oct 2018 15:51:38 +0000 (+0100) Subject: [64-client-class-cmds-hook] Documented class_cmds in the User's Guide. X-Git-Tag: 66-authoritative-flag-in-kea_base~23 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=14f4932334a2c1933cebccab7b0e2ced51bc80f7;p=thirdparty%2Fkea.git [64-client-class-cmds-hook] Documented class_cmds in the User's Guide. --- diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index ece9ed07fe..122cb95da5 100644 --- a/doc/guide/Makefile.am +++ b/doc/guide/Makefile.am @@ -7,10 +7,10 @@ dist_html_DATA = $(HTMLDOCS) kea-guide.css kea-logo-100x70.png DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml admin.xml config.xml DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml lease-expiration.xml logging.xml -DOCBOOK += ddns.xml hooks.xml hooks-ha.xml hooks-host-cache.xml hooks-lease-cmds.xml -DOCBOOK += hooks-radius.xml hooks-stat-cmds.xml libdhcp.xml lfc.xml stats.xml -DOCBOOK += ctrl-channel.xml faq.xml classify.xml shell.xml agent.xml netconf.xml -DOCBOOK += api.xml +DOCBOOK += ddns.xml hooks.xml hooks-class-cmds.xml hooks-ha.xml hooks-host-cache.xml +DOCBOOK += hooks-lease-cmds.xml hooks-radius.xml hooks-stat-cmds.xml libdhcp.xml +DOCBOOK += lfc.xml stats.xml ctrl-channel.xml faq.xml classify.xml shell.xml agent.xml +DOCBOOK += netconf.xml api.xml EXTRA_DIST = $(DOCBOOK) diff --git a/doc/guide/hooks-class-cmds.xml b/doc/guide/hooks-class-cmds.xml new file mode 100644 index 0000000000..7201621ac2 --- /dev/null +++ b/doc/guide/hooks-class-cmds.xml @@ -0,0 +1,245 @@ + + +
+ class_cmds: Class Commands + + This section describes the Class Commands hooks library, which exposes + several control commands for manipulating client classes, being a part of + the Kea DHCP servers' configurations, without the need to restart those + servers. Using these commands it is possible to add, update, delete and + list client classes configured for a given server. + + + This library may only be loaded by kea-dhcp4 + or kea-dhcp6 process. + + + + The Class Commands hooks library is available to premium Kea + customers only + + +
+ class-add command + The class-add command is used to add a new client + class to the DHCP server configuration. This class is appended at the + end of the list of classes used by the server, i.e. this class may depend + on any of the already configured client classes. + The following example demonstrates how to add a new client class + to the DHCPv4 server configuration: + +{ + "command": "class-add", + "arguments": { + "client-classes": [ + { + "name": "ipxe_efi_x64", + "test": "option[93].hex == 0x0009", + "next-server": "192.0.2.254", + "server-hostname": "hal9000", + "boot-file-name": "/dev/null" + } + ] + } +} + + + + Note that the client-classes parameter is a JSON list, + but it allows only a single client class to be present. In the future this + hooks library may be extended to support specification of multiple client + classes within a single class-add command. + + + + The following is the example response to the class-add + command: + +{ + "result": 0, + "text": "Class 'ipxe_efi_x64' added." +} + + +
+ +
+ class-update command + + The class-update command is used to update an existing + client class in the DHCP server configuration. If the client class with the + given name doesn't exist, the server returns result code of 3. In such case, + the server configuration is not modified (client class is not created). The + class-add command must be used instead to create the new + client class. + + + The class-update command has the same arguments structure + as class-add command: + +{ + "command": "class-update", + "arguments": { + "client-classes": [ + { + "name": "ipxe_efi_x64", + "test": "option[93].hex == 0x0017", + "next-server": "0.0.0.0", + "server-hostname": "xfce", + "boot-file-name": "/dev/null" + } + ] + } +} + + + + The following is the example response: + +{ + "result": 0, + "text": "Class 'ipxe_efi_x64' updated." +} + + + + Any parameter of the client class can be modified with this command, except + name. There is currently no way to rename the class, + because the class name is used as a key for searching the class to be updated. + In order to achieve similar effect to renaming the class, an existing class + should be removed with class-del command and then added + again with a different name using class-add. Note however, + that the class with the new name will be added at the end of the list of + configured classes. + +
+ +
+ class-del command + The class-del is used to remove a particular class + from the server configuration. The class to be removed is identified by name. + The class won't be removed if there are other classes dependening on it. + In order to remove such class, the dependent classes must be removed first. + The following is the example command removing + ipxe_efi_x64 class: + +{ + "command": "class-del", + "arguments": { + { + "name": "ipxe_efi_x64" + } + } +} + + + The following is the sample response to the class-del + command when the specified client class has been found: + +{ + "result": 0, + "text": "Class 'ipxe_efi_x64' deleted." +} + + + If the class doesn't exist, the result of 3 is returned. +
+ +
+ class-list command + The class-list is used to retrieve a list of all + client classes. This command includes no arguments: + +{ + "command": "class-list" +} + + + + The following is the example response of the server including the list + of client classes: + +{ + "result": 0, + "text": "2 classes found", + "arguments": { + "client-classes": [ + { + "name": "ipxe_efi_x64" + }, + { + "name": "pxeclient" + } + ] + } +} + + + + Note that the returned list does not contain full class definitions, but + merely class names. In order to retrieve full class information, the + class-get command should be used. + +
+ +
+ class-get command + The class-get is used to retrieve detail information + about specified class. The command structure is very simple: + +{ + "command": "class-get", + "arguments": { + "name": "pxeclient" + } +} + + + + If the class with the specified name doesn't exist, the status code of 3 + is returned. If the specified client class exists, the class details are + returned in the following format: + +{ + "result": 0, + "text": "Class 'pxeclient' definition returned", + "arguments": { + "client-classes": [ + { + "name": "pxeclient", + "only-if-required": true, + "test": "option[vendor-class-identifier].text == 'PXEClient'", + "option-def": [ + { + "name": "configfile", + "code": 209, + "type": "string" + } + ], + "option-data": [ ], + "next-server": "0.0.0.0", + "server-hostname": "xfce", + "boot-file-name": "/dev/null" + } + ] + } +} + + + + Note that the example above is DHCPv4 specific. The last three parameters + are only returned by the DHCPv4 server and never returned by the DHCPv6 + server. Also, some of the parameters provided in this example may not be + returned if they are not specified for the class. Specifically, + only-if-required, test and the + option-def are not returned if they are not specified + for the class. + +
+
diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index 7f739930d8..f7d95f9f16 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -2521,6 +2521,9 @@ both the command and the response. + + +