From a253aba33e53aa16a967349b69ca3c15119c2f8b Mon Sep 17 00:00:00 2001 From: Stephen Morris Date: Tue, 18 Apr 2017 19:38:40 +0100 Subject: [PATCH] [5171] Miscellaneous edits to the documentation --- doc/guide/agent.xml | 2 +- doc/guide/shell.xml | 91 ++++++++++++++++++++++++++------------------- 2 files changed, 53 insertions(+), 40 deletions(-) diff --git a/doc/guide/agent.xml b/doc/guide/agent.xml index 8e83c4af18..481f706f61 100644 --- a/doc/guide/agent.xml +++ b/doc/guide/agent.xml @@ -205,7 +205,7 @@ $ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ca.conf
- Connecting to Control Agent + Connecting to the Control Agent For an example of tool that can take advantage of the RESTful API, see .
diff --git a/doc/guide/shell.xml b/doc/guide/shell.xml index a2a4de3697..778d5c5f87 100644 --- a/doc/guide/shell.xml +++ b/doc/guide/shell.xml @@ -5,92 +5,103 @@ ]> - Kea Shell + The Kea Shell
Overview - Kea 1.2.0 introduced Control Agent (see ) that + Kea 1.2.0 introduced the Control Agent (CA, see ) that provides a RESTful control interface over HTTP. That API is typically expected to be used by - various IPAMs and similar management systems. Nevertheless, there are cases when a simple - client is required to issue commands. Kea shell fulfills that need. It is a simple, - command-line, scripting friendly text client that is able connect to CA, send commands with - parameters, retrieve and print CA responses. + 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. - The primary use case for shell is to be used as a tool in scriting environment, - therefore the tool is not interactive. However, with simple tricks it can be run manually. + As the primary purpose of the Kea Shell is as a tool in scripting environment, + it is not interactive. However, with simple tricks it can be run manually.
Shell Usage - - kea-shell accepts a number of optional parameters: + kea-shell is run as follows: + +kea-shell [--host hostname] [--port number] [--timeout seconds] [command] + + where: --host hostname specifies the hostname - of CA. If not specified, "localhost" is used. + of the CA. If not specified, "localhost" is used. --port number specifies the TCP port - on which CA listens. If not specified, 8000 is used. + on which the CA listens. If not specified, 8000 is used. --timeout seconds specifies the - timeout in seconds for connection. If not specified, 10 seconds is used. + timeout (in seconds) for the connection. If not given, 10 seconds is used. - -h prints out help message. + command specifies the command to be sent. If not specified, + list-commands command is used. + + + Other switches are: + - -v prints software version. + -h prints a help message. - command specifies the command to be sent. If not specified, - list-commands command is used. + -v prints the software version. - Once started, the shell reads command parameters from the standard input. Those are - expected to be in JSON format. After read ends, the shell establishes connection using - http protocol to CA, sends the command and awaits response. Once the response becomes - available it is being printed on standart output. + 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. For a list of available commands, see . Additional commands - may be provided by hook libraries. If unsure which commands are supported, please use - list-commands command. It will instruct CA to list all supported commands. + may be provided by hook libraries. If unsure which commands are supported, use the + list-commands command. It will instruct the CA to return a list of + all supported commands. - Several examples of kea-shell usage are presented below. This example will expect - parameters to be provided on standard input. Since list-commands does not take any - arguments, ctrl-d may be pressed to indicate end of file. Kea shell will then contact - CA and will print out a list of available commands. + The following shows a simple example of usage: $ kea-shell --host 192.0.2.1 --port 8001 list-commands +^D + 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. - Kea shell is envisaged to be most frequently used in scripts. Here is an example of - very simple scripted execution. It will issue command "config-write" with parameters - specified in param.json. The result will be stored in result.json. + It is envisaged that 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, along + with the parameters specified in param.json. The result will be stored in result.json. $ cat param.json "filename": "my-config-file.json" @@ -98,14 +109,16 @@ $ cat param.json | kea-shell --host 192.0.2.1 config-write > result.j - Kea shell requires python to run. It was 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 - certainly deployments that do not have python, Kea shell is not enabled by default. To - enable it, make sure you pass --enable-shell to configure script. + Kea Shell requires Python to to be installed on the system. It was 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 + installation of Kea. - Kea shell is intended to serve more a demonstration of the RESTful interface - capabilities and perhaps an illustration for people interested in integrating their - management evironments with Kea, rather than a serious management client. Do not expect it - to be significantly expanded in the future. It is and will remain a simple tool. -
+ The Kea Shell is intended to serve more as a demonstration of the RESTful interface + 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 + to be significantly expanded in the future. It is, and will remain, a simple tool. + -- 2.47.2