]>

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 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. 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.

kea-shell is run as follows: kea-shell [--host hostname] [--port number] [--timeout seconds] [--service service-name] [command] where: --host hostname specifies the hostname of the CA. If not specified, "localhost" is used. --port number specifies the TCP port on which the CA listens. If not specified, 8000 is used. --timeout seconds specifies the timeout (in seconds) for the connection. If not given, 10 seconds is used. --service serive-name specifies the target of a command. If not given, CA will be used as target. May be used more than once to specify multiple targets. command specifies the command to be sent. If not specified, list-commands command is used. Other switches are: -h prints a help message. -v prints the software version. 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, use the list-commands command. It will instruct the CA to return a list of all supported commands. The following shows a simple example of usage: $ kea-shell --host 192.0.2.1 --port 8001 --service dhcp4 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 for the service named dhcp4. 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 ( --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 "filename": "my-config-file.json" $ cat param.json | kea-shell --host 192.0.2.1 config-write > result.json 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. 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.