From: Suzanne Goldlust Date: Wed, 2 Jan 2019 20:45:08 +0000 (-0500) Subject: Update shell.xml X-Git-Tag: 481-remote-subnet4-set-inconsistent-work-when-id-subnet-is-duplicated_base~48 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0ea41b057fbf325dca799492de97253fdfb053d0;p=thirdparty%2Fkea.git Update shell.xml --- diff --git a/doc/guide/shell.xml b/doc/guide/shell.xml index 9396130a0f..70f80ceedc 100644 --- a/doc/guide/shell.xml +++ b/doc/guide/shell.xml @@ -3,7 +3,7 @@ - - This Source Code Form is subject to the terms of the Mozilla Public - License, v. 2.0. If a copy of the MPL was not distributed with this - - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - file, you can obtain one at http://mozilla.org/MPL/2.0/. --> @@ -11,14 +11,14 @@
Overview - Kea 1.2.0 introduced the Control Agent (CA, see ) that + Kea 1.2.0 introduced the Control Agent (CA, see ), which provides a RESTful control interface over HTTP. That API is typically expected to be used by - various IPAMs and similar management systems. Nevertheless, there may be cases when you want - to send a command to the CA directly. The Kea Shell provides a way to do this. It is a simple - command-line, scripting-friendly text client that is able connect to the CA, send it commands - with parameters, retrieve the responses and display them. + various IPAMs and similar management systems. Nevertheless, there may be cases when an administrator wants + to send a command to the CA directly. The Kea shell provides a way to do this. It is a simple + command-line, scripting-friendly, text client that is able to connect to the CA, send it commands + with parameters, retrieve the responses, and display them. - As the primary purpose of the Kea Shell is as a tool in scripting environment, + As the primary purpose of the Kea shell is as a tool in a scripting environment, it is not interactive. However, with simple tricks it can be run manually.
@@ -49,8 +49,8 @@ kea-shell [--host hostname] [--port number] [--path path] [--timeout seconds] [- --path path specifies - the path in the URL to connect to. If not specified, - empty path is used. As CA listens at the empty path + the path in the URL to connect to. If not specified, an + empty path is used. As CA listens at the empty path, this parameter is useful only with a reverse proxy. @@ -65,7 +65,7 @@ kea-shell [--host hostname] [--port number] [--path path] [--timeout seconds] [- --service service-name specifies the - target of a command. If not given, CA will be used as target. May be used more + target of a command. If not given, CA will be used as the target. May be used more than once to specify multiple targets. @@ -74,7 +74,7 @@ kea-shell [--host hostname] [--port number] [--path path] [--timeout seconds] [- command specifies the command to be sent. If not specified, - list-commands command is used. + the list-commands command is used. @@ -96,13 +96,13 @@ kea-shell [--host hostname] [--port number] [--path path] [--timeout seconds] [- Once started, the shell reads parameters for the command from standard input, which are expected to be in JSON format. When all have been read, the shell establishes a connection - with the CA using HTTP, sends the command and awaits a response. Once that is received, - it is printed on standard output. + with the CA using HTTP, sends the command, and awaits a response. Once that is received, + it is displayed on standard output. - For a list of available commands, see . Additional commands - may be provided by hook libraries. If unsure which commands are supported, use the + For a list of available commands, see ; additional commands + may be provided by hook libraries. If you are unsure which commands are supported, use the list-commands command. It will instruct the CA to return a list of all supported commands. @@ -114,14 +114,14 @@ $ kea-shell --host 192.0.2.1 --port 8001 --service dhcp4 list-command After the command line is entered, the program waits for command parameters to be entered. Since list-commands does not take any - arguments, CTRL-D (represented in the above example by "^D") is pressed to indicate end - of file (and so terminate the parameter input). The Shell will then contact - the CA and print out the list of available commands returned for the service named dhcp4. + arguments, CTRL-D (represented in the above example by "^D") is pressed to indicate + end-of-file and terminate the parameter input. The shell then contacts + the CA and prints out the list of available commands returned for the service named dhcp4. - It is envisaged that Kea Shell will be most frequently used in scripts. The next example + It is envisaged that the Kea shell will be most frequently used in scripts; the next example shows a simple scripted execution. It sends the command "config-write" to the CA - ( --service parameter hasn't been used), along + (the --service parameter hasn't been used), along with the parameters specified in param.json. The result will be stored in result.json. $ cat param.json @@ -131,24 +131,24 @@ $ cat param.json | kea-shell --host 192.0.2.1 config-write > resul When a reverse proxy is used to de-multiplex requests to different - servers the default empty path in the URL is not enough so the - --path parameter should be used. For instance + servers, the default empty path in the URL is not enough, so the + --path parameter should be used. For instance, if requests to the "/kea" path are forwarded to the CA this can be used: $ kea-shell --host 192.0.2.1 --port 8001 --path kea ... - Kea Shell requires Python to to be installed on the system. It was tested with + Kea shell requires Python to to be installed on the system. It has been tested with Python 2.7 and various versions of Python 3, up to 3.5. Since not every Kea deployment uses this feature and there are - deployments that do not have Python, the Kea Shell is not enabled by default. To use it, - you must specify --enable-shell to when running "configure" during the + deployments that do not have Python, the Kea shell is not enabled by default. To use it, + specify --enable-shell when running "configure" during the installation of Kea. - The Kea Shell is intended to serve more as a demonstration of the RESTful interface + The Kea shell is intended to serve more as a demonstration of the RESTful interface's capabilities (and, perhaps, an illustration for people interested in integrating their - management evironments with Kea) than as a serious management client. Do not expect it + management environments with Kea) than as a serious management client. Do not expect it to be significantly expanded in the future. It is, and will remain, a simple tool.