Commit 3dc4908f authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[master] Merge branch 'trac5171' (User's Guide section about Kea shell)

parents f3542400 a253aba3
......@@ -8,7 +8,7 @@ dist_html_DATA = $(HTMLDOCS) kea-guide.css kea-logo-100x70.png
DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml admin.xml config.xml
DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml lease-expiration.xml logging.xml
DOCBOOK += ddns.xml hooks.xml libdhcp.xml lfc.xml stats.xml ctrl-channel.xml faq.xml
DOCBOOK += classify.xml
DOCBOOK += classify.xml shell.xml agent.xml
EXTRA_DIST = $(DOCBOOK)
......
......@@ -203,4 +203,10 @@ $ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ca.conf
</screen>
</para>
</section>
<section id="agent-clients">
<title>Connecting to the Control Agent</title>
<para>For an example of tool that can take advantage of the
RESTful API, see <xref linkend="kea-shell"/>.</para>
</section>
</chapter>
......@@ -88,6 +88,8 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="shell.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="faq.xml" />
<chapter id="acknowledgments">
......
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash "&#x2017;" >
]>
<chapter id="kea-shell">
<title>The Kea Shell</title>
<section id="shell-overview">
<title>Overview</title>
<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 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>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><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 the CA. If not specified, "localhost" is used.
</simpara>
</listitem>
<listitem>
<simpara>
<command>--port <replaceable>number</replaceable></command> specifies the TCP port
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 the connection. If not given, 10 seconds is used.
</simpara>
</listitem>
<listitem>
<simpara>
<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>-h</command> prints a help message.
</simpara>
</listitem>
<listitem>
<simpara>
<command>-v</command> prints the software version.
</simpara>
</listitem>
</itemizedlist>
<para>
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, use the
<command>list-commands</command> command. It will instruct the CA to return a list of
all supported commands.
</para>
<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>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"
$ <userinput>cat param.json | kea-shell --host 192.0.2.1 config-write > result.json</userinput>
</screen>
</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>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>
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment