|
|
@@ -5,92 +5,103 @@
|
|
|
]>
|
|
|
|
|
|
<chapter id="kea-shell">
|
|
|
- <title>Kea Shell</title>
|
|
|
+ <title>The Kea Shell</title>
|
|
|
|
|
|
<section id="shell-overview">
|
|
|
<title>Overview</title>
|
|
|
- <para>Kea 1.2.0 introduced Control Agent (see <xref linkend="kea-ctrl-agent"/>) that
|
|
|
+ <para>Kea 1.2.0 introduced the Control Agent (CA, see <xref linkend="kea-ctrl-agent"/>) 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.</para>
|
|
|
+ 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.</para>
|
|
|
|
|
|
- <para>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.
|
|
|
+ <para>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.
|
|
|
</para>
|
|
|
</section>
|
|
|
|
|
|
<section id="shell-usage">
|
|
|
<title>Shell Usage</title>
|
|
|
-
|
|
|
- <para>kea-shell accepts a number of optional parameters:
|
|
|
+ <para><command>kea-shell</command> is run as follows:
|
|
|
+<screen>
|
|
|
+kea-shell [--host hostname] [--port number] [--timeout seconds] [command]
|
|
|
+</screen>
|
|
|
+ where:
|
|
|
</para>
|
|
|
<itemizedlist>
|
|
|
<listitem>
|
|
|
<simpara>
|
|
|
<command>--host <replaceable>hostname</replaceable></command> specifies the hostname
|
|
|
- of CA. If not specified, "localhost" is used.
|
|
|
+ of the CA. If not specified, "localhost" is used.
|
|
|
</simpara>
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
<simpara>
|
|
|
<command>--port <replaceable>number</replaceable></command> 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.
|
|
|
</simpara>
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
<simpara>
|
|
|
<command>--timeout <replaceable>seconds</replaceable></command> 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.
|
|
|
</simpara>
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
<simpara>
|
|
|
- <command>-h</command> prints out help message.
|
|
|
+ <command>command</command> specifies the command to be sent. If not specified,
|
|
|
+ <command>list-commands</command> command is used.
|
|
|
</simpara>
|
|
|
</listitem>
|
|
|
+ </itemizedlist>
|
|
|
+
|
|
|
+ <para>Other switches are:</para>
|
|
|
+ <itemizedlist>
|
|
|
<listitem>
|
|
|
<simpara>
|
|
|
- <command>-v</command> prints software version.
|
|
|
+ <command>-h</command> prints a help message.
|
|
|
</simpara>
|
|
|
</listitem>
|
|
|
<listitem>
|
|
|
<simpara>
|
|
|
- <command>command</command> specifies the command to be sent. If not specified,
|
|
|
- <command>list-commands</command> command is used.
|
|
|
+ <command>-v</command> prints the software version.
|
|
|
</simpara>
|
|
|
</listitem>
|
|
|
</itemizedlist>
|
|
|
|
|
|
<para>
|
|
|
- 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.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
For a list of available commands, see <xref linkend="ctrl-channel"/>. Additional commands
|
|
|
- may be provided by hook libraries. If unsure which commands are supported, please use
|
|
|
- <command>list-commands</command> command. It will instruct CA to list all supported commands.
|
|
|
+ may be provided by hook libraries. If unsure which commands are supported, use the
|
|
|
+ <command>list-commands</command> command. It will instruct the CA to return a list of
|
|
|
+ all supported commands.
|
|
|
</para>
|
|
|
|
|
|
- <para>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.
|
|
|
+ <para>The following shows a simple example of usage:
|
|
|
<screen>
|
|
|
$ <userinput>kea-shell --host 192.0.2.1 --port 8001 list-commands</userinput>
|
|
|
+^D
|
|
|
</screen>
|
|
|
+ After the command line is entered, the program waits for command parameters to be entered.
|
|
|
+ Since <command>list-commands</command> 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.
|
|
|
</para>
|
|
|
|
|
|
- <para>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.
|
|
|
+ <para>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.
|
|
|
<screen>
|
|
|
$ cat param.json
|
|
|
"filename": "my-config-file.json"
|
|
|
@@ -98,14 +109,16 @@ $ <userinput>cat param.json | kea-shell --host 192.0.2.1 config-write > result.j
|
|
|
</screen>
|
|
|
</para>
|
|
|
|
|
|
- <para>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 <command>--enable-shell</command> to configure script.</para>
|
|
|
+ <para>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 <command>--enable-shell</command> to when running "configure" during the
|
|
|
+ installation of Kea.</para>
|
|
|
|
|
|
- <para>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.</para>
|
|
|
- </section>
|
|
|
+ <para>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.</para>
|
|
|
+ </section>
|
|
|
</chapter>
|
Stephen Morris