From: Tomek Mrugalski Date: Tue, 18 Apr 2017 15:18:54 +0000 (+0200) Subject: [5171] missing shell.xml added. X-Git-Tag: trac5186_base~4^2~1 X-Git-Url: http://git.ipfire.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=08f18c59cd1de6cb4d7cc2366c0ec789d0bf787c;p=thirdparty%2Fkea.git [5171] missing shell.xml added. --- diff --git a/doc/guide/shell.xml b/doc/guide/shell.xml new file mode 100644 index 0000000000..a2a4de3697 --- /dev/null +++ b/doc/guide/shell.xml @@ -0,0 +1,111 @@ + + +]> + + + Kea Shell + +
+ Overview + Kea 1.2.0 introduced Control Agent (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. + + 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. + +
+ +
+ Shell Usage + + kea-shell accepts a number of optional parameters: + + + + + --host hostname specifies the hostname + of CA. If not specified, "localhost" is used. + + + + + + --port number specifies the TCP port + on which CA listens. If not specified, 8000 is used. + + + + + + --timeout seconds specifies the + timeout in seconds for connection. If not specified, 10 seconds is used. + + + + + + -h prints out help message. + + + + + -v prints software version. + + + + + command specifies the command to be sent. If not specified, + list-commands command is used. + + + + + + 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. + + + + 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. + + + 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. + +$ kea-shell --host 192.0.2.1 --port 8001 list-commands + + + + 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. + +$ cat param.json +"filename": "my-config-file.json" +$ cat param.json | kea-shell --host 192.0.2.1 config-write > result.json + + + + 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 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. +
+