<!--
 - Copyright (C) 2017-2018 Internet Systems Consortium, Inc. ("ISC")
 -
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
-->

<refentry>

  <info>
    <productname>ISC Kea</productname>
    <date>Dec 14, 2018</date>
    <edition>1.5.0</edition>
    <author>
      <contrib>The Kea software has been written by a number of
        engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
        Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
        Wlodek Wencel and Shawn Routhier.  That list is roughly in the
        chronological order in which the authors made their first
        contribution. For a complete list of authors and
        contributors, see AUTHORS file.</contrib><orgname>Internet Systems Consortium, Inc.</orgname></author>
  </info>

  <refmeta>
    <refentrytitle>kea-shell</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo class="manual">Kea</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>kea-shell</refname>
    <refpurpose>Text client for Control Agent process</refpurpose>
  </refnamediv>

  <docinfo>
    <copyright>
      <year>2017-2018</year>
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
  </docinfo>

  <refsynopsisdiv>
    <cmdsynopsis sepchar=" ">
      <command>kea-shell</command>
      <arg choice="opt" rep="norepeat"><option>-h</option></arg>
      <arg choice="opt" rep="norepeat"><option>-v</option></arg>
      <arg choice="opt" rep="norepeat"><option>--host</option></arg>
      <arg choice="opt" rep="norepeat"><option>--port</option></arg>
      <arg choice="opt" rep="norepeat"><option>--path</option></arg>
      <arg choice="opt" rep="norepeat"><option>--timeout</option></arg>
      <arg choice="opt" rep="norepeat"><option>--service</option></arg>
      <arg choice="opt" rep="norepeat"><option>command</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>


  <refsect1>
    <title>DESCRIPTION</title>
    <para>
      The <command>kea-shell</command> provides a REST client for the
      Kea Control Agent (CA). It takes command as a command-line parameter
      that is being sent to CA with proper JSON
      encapsulation. Optional arguments may be specified on the
      standard input. The request it sent of HTTP and a response is
      retrieved. That response is displayed out on the standard output.
    </para>

  </refsect1>

  <refsect1>
    <title>ARGUMENTS</title>

    <para>The arguments are as follows:</para>

    <variablelist>

      <varlistentry>
        <term><option>-h</option></term>
        <listitem><para>
          Displays help regarding command line parameters.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-v</option></term>
        <listitem><para>
          Display the version.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--host</option></term>
        <listitem><para>
          Specifies the host to connect to. Control Agent must be
          running at specified host. If not specified, 127.0.0.1 is used.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--port</option></term>
        <listitem><para>
          Specifies the TCP port to connect to. Control Agent must be
          listening at specified port. If not specified, 8000 is used.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--path</option></term>
        <listitem><para>
          Specifies the path in the URL to connect to. If not specified,
          empty path is used. As Control Agent listens at the empty path
          this parameter is useful only with a reverse proxy.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--timeout</option></term>
        <listitem><para>
          Specifies the connection timeout in seconds. If not
          specified, 10 (seconds) is used.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--service</option></term>
        <listitem><para>
          Specifies the service that is the target of a command. If not
          specified, Control Agent will be targeted. May be used more than
          once to specify multiple targets.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>command</option></term>
        <listitem><para>
          Specifies the command to be sent to CA. If not
          specified, "list-commands" is used.
        </para></listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>DOCUMENTATION</title>
    <para>Kea comes with an extensive Kea User's Guide documentation
      that covers all aspects of running the Kea software -
      compilation, installation, configuration, configuration examples
      and many more. Kea also features a Kea Messages Manual, which
      lists all possible messages Kea can print with a brief
      description for each of them. Both documents are typically
      available in various formats (txt, html, pdf) with your Kea
      distribution. The Kea documentation is available at
      https://kb.isc.org/docs/kea-administrator-reference-manual .</para>
    <para>
      Kea source code is documented in the Kea Developer's Guide. Its
      on-line version is available at https://jenkins.isc.org/job/Kea_doc/doxygen/.
    </para>
    <para>
      Kea project website is available at: https://gitlab.isc.org/isc-projects/kea.
    </para>
  </refsect1>

  <refsect1>
    <title>MAILING LISTS AND SUPPORT</title>
    <para>
      There are two mailing lists available for Kea project. kea-users
      (kea-users at lists.isc.org) is intended for Kea users, while kea-dev
      (kea-dev at lists.isc.org) is intended for Kea developers, prospective
      contributors and other advanced users.  Both lists are available at
      http://lists.isc.org. The community provides best effort type of support
      on both of those lists.
    </para>
    <para>
      ISC provides professional support for Kea services. See
      https://www.isc.org/kea/ for details.
    </para>
  </refsect1>

  <refsect1>
    <title>HISTORY</title>
    <para>
      The <command>kea-shell</command> was first coded in March 2017
      by Tomek Mrugalski.
    </para>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>kea-ctrl-agent</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>kea-dhcp4</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>kea-dhcp6</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>kea-dhcp-ddns</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>kea-admin</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>keactrl</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>perfdhcp</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>kea-lfc</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,

      <citetitle>Kea Administrator's Guide</citetitle>.

    </para>
  </refsect1>

</refentry>
