/mandos/trunk

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

<!ENTITY COMMANDNAME "mandos-ctl">

<!ENTITY TIMESTAMP "2019-07-29">

<!ENTITY % common SYSTEM "common.ent">

%common;

]>

<refentry xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>

    <title>Mandos Manual</title>

    <!-- NWalsh’s docbook scripts use this to generate the footer: -->

    <productname>Mandos</productname>

    <productnumber>&version;</productnumber>

    <date>&TIMESTAMP;</date>

    <authorgroup>

      <author>

	<firstname>Björn</firstname>

	<surname>Påhlsson</surname>

	<address>

	  <email>belorn@recompile.se</email>

	</address>

      </author>

      <author>

	<firstname>Teddy</firstname>

	<surname>Hogeborn</surname>

	<address>

	  <email>teddy@recompile.se</email>

	</address>

      </author>

    </authorgroup>

    <copyright>

      <year>2010</year>

      <year>2011</year>

      <year>2012</year>

      <year>2013</year>

      <year>2014</year>

      <year>2015</year>

      <year>2016</year>

      <year>2017</year>

      <year>2018</year>

      <year>2019</year>

      <holder>Teddy Hogeborn</holder>

      <holder>Björn Påhlsson</holder>

    </copyright>

    <xi:include href="legalnotice.xml"/>

  </refentryinfo>

  <refmeta>

    <refentrytitle>&COMMANDNAME;</refentrytitle>

    <manvolnum>8</manvolnum>

  </refmeta>

  <refnamediv>

    <refname><command>&COMMANDNAME;</command></refname>

    <refpurpose>

      Control or query the operation of the Mandos server

    </refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group>

	  <arg choice="plain"><option>--verbose</option></arg>

	  <arg choice="plain"><option>-v</option></arg>

	  <sbr/>

	  <arg choice="plain"><option>--dump-json</option></arg>

	  <arg choice="plain"><option>-j</option></arg>

      </group>

      <arg><option>--debug</option></arg>

      <group>

	<arg rep='repeat' choice='plain'>

	  <replaceable>CLIENT</replaceable>

	</arg>

      </group>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group choice="req">

	<group>

	  <arg choice="plain"><option>--enable</option></arg>

	  <arg choice="plain"><option>-e</option></arg>

	  <sbr/>

	  <arg choice="plain"><option>--disable</option></arg>

	  <arg choice="plain"><option>-d</option></arg>

	</group>

	<sbr/>

	<group>

	  <arg choice="plain"><option>--bump-timeout</option></arg>

	  <arg choice="plain"><option>-b</option></arg>

	</group>

	<sbr/>

	<group>

	  <arg choice="plain"><option>--start-checker</option></arg>

	  <arg choice="plain"><option>--stop-checker</option></arg>

	</group>

	<sbr/>

	<group>

	  <arg choice="plain"><option>--checker

	  <replaceable>COMMAND</replaceable></option></arg>

	  <arg choice="plain"><option>-c

	  <replaceable>COMMAND</replaceable></option></arg>

	</group>

	<sbr/>

	<group>

	  <arg choice="plain"><option>--timeout

	  <replaceable>TIME</replaceable></option></arg>

	  <arg choice="plain"><option>-t

	  <replaceable>TIME</replaceable></option></arg>

	</group>

	<sbr/>

	<group>

	  <arg choice="plain"><option>--extended-timeout

	  <replaceable>TIME</replaceable></option></arg>

	</group>

	<sbr/>

	<group>

	  <arg choice="plain"><option>--interval

	  <replaceable>TIME</replaceable></option></arg>

	  <arg choice="plain"><option>-i

	  <replaceable>TIME</replaceable></option></arg>

	</group>

	<sbr/>

	<group>

	  <arg choice="plain"><option>--approve-by-default</option

          ></arg>

	  <sbr/>

	  <arg choice="plain"><option>--deny-by-default</option></arg>

	</group>

	<sbr/>

	<group>

	  <arg choice="plain"><option>--approval-delay

	  <replaceable>TIME</replaceable></option></arg>

	</group>

	<sbr/>

	<group>

	  <arg choice="plain"><option>--approval-duration

	  <replaceable>TIME</replaceable></option></arg>

	</group>

	<sbr/>

	<group>

	  <arg choice="plain"><option>--host

	  <replaceable>STRING</replaceable></option></arg>

	  <arg choice="plain"><option>-H

	  <replaceable>STRING</replaceable></option></arg>

	</group>

	<sbr/>

	<group>

	  <arg choice="plain"><option>--secret

	  <replaceable>FILENAME</replaceable></option></arg>

	  <arg choice="plain"><option>-s

	  <replaceable>FILENAME</replaceable></option></arg>

	</group>

	<sbr/>

	<group>

	  <arg choice="plain"><option>--approve</option></arg>

	  <arg choice="plain"><option>-A</option></arg>

	  <sbr/>

	  <arg choice="plain"><option>--deny</option></arg>

	  <arg choice="plain"><option>-D</option></arg>

	</group>

      </group>

      <sbr/>

      <arg><option>--debug</option></arg>

      <group choice="req">

	<arg choice="plain"><option>--all</option></arg>

	<arg choice="plain"><option>-a</option></arg>

	<arg rep='repeat' choice='plain'>

	  <replaceable>CLIENT</replaceable>

	</arg>

      </group>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group>

	<arg choice="plain"><option>--deny</option></arg>

	<arg choice="plain"><option>-D</option></arg>

      </group>

      <group choice="req">

	  <arg choice="plain"><option>--remove</option></arg>

	  <arg choice="plain"><option>-r</option></arg>

      </group>

      <sbr/>

      <arg><option>--debug</option></arg>

      <group choice="req">

	<arg choice="plain"><option>--all</option></arg>

	<arg choice="plain"><option>-a</option></arg>

	<arg rep='repeat' choice='plain'>

	  <replaceable>CLIENT</replaceable>

	</arg>

      </group>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group choice="req">

	<arg choice="plain"><option>--is-enabled</option></arg>

	<arg choice="plain"><option>-V</option></arg>

      </group>

      <arg><option>--debug</option></arg>

      <arg choice='plain'><replaceable>CLIENT</replaceable></arg>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group choice="req">

	<arg choice="plain"><option>--help</option></arg>

	<arg choice="plain"><option>-h</option></arg>

      </group>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group choice="req">

	<arg choice="plain"><option>--version</option></arg>

	<arg choice="plain"><option>-v</option></arg>

      </group>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <arg choice="plain"><option>--check</option></arg>

    </cmdsynopsis>

  </refsynopsisdiv>

  <refsect1 id="description">

    <title>DESCRIPTION</title>

    <para>

      <command>&COMMANDNAME;</command> is a program to control or

      query the operation of the Mandos server

      <citerefentry><refentrytitle>mandos</refentrytitle><manvolnum

      >8</manvolnum></citerefentry>.

    </para>

    <para>

      This program can be used to change client settings, approve or

      deny client requests, and to remove clients from the server.

    </para>

  </refsect1>

  <refsect1 id="purpose">

    <title>PURPOSE</title>

    <para>

      The purpose of this is to enable <emphasis>remote and unattended

      rebooting</emphasis> of client host computer with an

      <emphasis>encrypted root file system</emphasis>.  See <xref

      linkend="overview"/> for details.

    </para>

  </refsect1>

  <refsect1 id="options">

    <title>OPTIONS</title>

    <variablelist>

      <varlistentry>

	<term><option>--help</option></term>

	<term><option>-h</option></term>

	<listitem>

	  <para>

	    Show a help message and exit

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--enable</option></term>

	<term><option>-e</option></term>

	<listitem>

	  <para>

	    Enable client(s).  An enabled client will be eligble to

	    receive its secret.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--disable</option></term>

	<term><option>-d</option></term>

	<listitem>

	  <para>

	    Disable client(s).  A disabled client will not be eligble

	    to receive its secret, and no checkers will be started for

	    it.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--bump-timeout</option></term>

	<listitem>

	  <para>

	    Bump the timeout of the specified client(s), just as if a

	    checker had completed successfully for it/them.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--start-checker</option></term>

	<listitem>

	  <para>

	    Start a new checker now for the specified client(s).

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--stop-checker</option></term>

	<listitem>

	  <para>

	    Stop any running checker for the specified client(s).

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--remove</option></term>

	<term><option>-r</option></term>

	<listitem>

	  <para>

	    Remove the specified client(s) from the server.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--checker

	<replaceable>COMMAND</replaceable></option></term>

	<term><option>-c

	<replaceable>COMMAND</replaceable></option></term>

	<listitem>

	  <para>

	    Set the <varname>checker</varname> option of the specified

	    client(s); see <citerefentry><refentrytitle

	    >mandos-clients.conf</refentrytitle><manvolnum

            >5</manvolnum></citerefentry>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--timeout

	<replaceable>TIME</replaceable></option></term>

	<term><option>-t

	<replaceable>TIME</replaceable></option></term>

	<listitem>

	  <para>

	    Set the <varname>timeout</varname> option of the specified

	    client(s); see <citerefentry><refentrytitle

	    >mandos-clients.conf</refentrytitle><manvolnum

            >5</manvolnum></citerefentry>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--extended-timeout

	<replaceable>TIME</replaceable></option></term>

	<listitem>

	  <para>

	    Set the <varname>extended_timeout</varname> option of the

	    specified client(s); see <citerefentry><refentrytitle

	    >mandos-clients.conf</refentrytitle><manvolnum

	    >5</manvolnum></citerefentry>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--interval

	<replaceable>TIME</replaceable></option></term>

	<term><option>-i

	<replaceable>TIME</replaceable></option></term>

	<listitem>

	  <para>

	    Set the <varname>interval</varname> option of the

	    specified client(s); see <citerefentry><refentrytitle

	    >mandos-clients.conf</refentrytitle><manvolnum

            >5</manvolnum></citerefentry>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--approve-by-default</option></term>

	<term><option>--deny-by-default</option></term>

	<listitem>

	  <para>

	    Set the <varname>approved_by_default</varname> option of

	    the specified client(s) to <literal>True</literal> or

	    <literal>False</literal>, respectively; see

	    <citerefentry><refentrytitle

            >mandos-clients.conf</refentrytitle><manvolnum

            >5</manvolnum></citerefentry>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--approval-delay

	<replaceable>TIME</replaceable></option></term>

	<listitem>

	  <para>

	    Set the <varname>approval_delay</varname> option of the

	    specified client(s); see <citerefentry><refentrytitle

	    >mandos-clients.conf</refentrytitle><manvolnum

            >5</manvolnum></citerefentry>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--approval-duration

	<replaceable>TIME</replaceable></option></term>

	<listitem>

	  <para>

	    Set the <varname>approval_duration</varname> option of the

	    specified client(s); see <citerefentry><refentrytitle

	    >mandos-clients.conf</refentrytitle><manvolnum

            >5</manvolnum></citerefentry>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--host

	<replaceable>STRING</replaceable></option></term>

	<term><option>-H

	<replaceable>STRING</replaceable></option></term>

	<listitem>

	  <para>

	    Set the <varname>host</varname> option of the specified

	    client(s); see <citerefentry><refentrytitle

	    >mandos-clients.conf</refentrytitle><manvolnum

            >5</manvolnum></citerefentry>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--secret

	<replaceable>FILENAME</replaceable></option></term>

	<term><option>-s

	<replaceable>FILENAME</replaceable></option></term>

	<listitem>

	  <para>

	    Set the <varname>secfile</varname> option of the specified

	    client(s); see <citerefentry><refentrytitle

	    >mandos-clients.conf</refentrytitle><manvolnum

            >5</manvolnum></citerefentry>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--approve</option></term>

	<term><option>-A</option></term>

	<listitem>

	  <para>

	    Approve client(s) if currently waiting for approval.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--deny</option></term>

	<term><option>-D</option></term>

	<listitem>

	  <para>

	    Deny client(s) if currently waiting for approval.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--all</option></term>

	<term><option>-a</option></term>

	<listitem>

	  <para>

	    Make the client-modifying options modify <emphasis

	    >all</emphasis> clients.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--verbose</option></term>

	<term><option>-v</option></term>

	<listitem>

	  <para>

	    Show all client settings, not just a subset.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--dump-json</option></term>

	<term><option>-j</option></term>

	<listitem>

	  <para>

	    Dump client settings as JSON to standard output.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--is-enabled</option></term>

	<term><option>-V</option></term>

	<listitem>

	  <para>

	    Check if a single client is enabled or not, and exit with

	    a successful exit status only if the client is enabled.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--debug</option></term>

	<listitem>

	  <para>

	    Show debug output; currently, this means show D-Bus calls.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--check</option></term>

	<listitem>

	  <para>

	    Run self-tests.  This includes any unit tests, etc.

	  </para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1 id="overview">

    <title>OVERVIEW</title>

    <xi:include href="overview.xml"/>

    <para>

      This program is a small utility to generate new OpenPGP keys for

      new Mandos clients, and to generate sections for inclusion in

      <filename>clients.conf</filename> on the server.

    </para>

  </refsect1>

  <refsect1 id="exit_status">

    <title>EXIT STATUS</title>

    <para>

      If the <option>--is-enabled</option> option is used, the exit

      status will be 0 only if the specified client is enabled.

    </para>

  </refsect1>

  <refsect1 id="bugs">

    <title>BUGS</title>

    <xi:include href="bugs.xml"/>

  </refsect1>

  <refsect1 id="example">

    <title>EXAMPLE</title>

    <!-- Name of test methods in class Test_commands_from_options are

         written in comments below.  When adding an example, add a

         test too which tests the documented behavior. -->

    <informalexample>

      <!-- Test method: test_manual_page_example_1() -->

      <para>

	To list all clients:

      </para>

      <para>

	<userinput>&COMMANDNAME;</userinput>

      </para>

    </informalexample>

    <informalexample>

      <!-- Test method: test_manual_page_example_2() -->

      <para>

	To list <emphasis>all</emphasis> settings for the clients

        named <quote>foo1.example.org</quote> and <quote

        >foo2.example.org</quote>:

      </para>

      <para>

<!-- do not wrap this line -->

<userinput>&COMMANDNAME; --verbose foo1.example.org foo2.example.org</userinput>

      </para>

    </informalexample>

    <informalexample>

      <!-- Test method: test_manual_page_example_3() -->

      <para>

	To enable all clients:

      </para>

      <para>

	<userinput>&COMMANDNAME; --enable --all</userinput>

      </para>

    </informalexample>

    <informalexample>

      <!-- Test method: test_manual_page_example_4() -->

      <para>

	To change timeout and interval value for the clients

        named <quote>foo1.example.org</quote> and <quote

        >foo2.example.org</quote>:

      </para>

      <para>

<!-- do not wrap this line -->

<userinput>&COMMANDNAME; --timeout=PT5M --interval=PT1M foo1.example.org foo2.example.org</userinput>

      </para>

    </informalexample>

    <informalexample>

      <!-- Test method: test_manual_page_example_5() -->

      <para>

	To approve all clients currently waiting for approval:

      </para>

      <para>

	<userinput>&COMMANDNAME; --approve --all</userinput>

      </para>

    </informalexample>

  </refsect1>

  <refsect1 id="security">

    <title>SECURITY</title>

    <para>

      This program must be permitted to access the Mandos server via

      the D-Bus interface.  This normally requires the root user, but

      could be configured otherwise by reconfiguring the D-Bus server.

    </para>

  </refsect1>

  <refsect1 id="see_also">

    <title>SEE ALSO</title>

    <para>

      <citerefentry><refentrytitle>intro</refentrytitle>

      <manvolnum>8mandos</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>mandos</refentrytitle>

      <manvolnum>8</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>

      <manvolnum>5</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>mandos-monitor</refentrytitle>

      <manvolnum>8</manvolnum></citerefentry>

    </para>

  </refsect1>

</refentry>

<!-- Local Variables: -->

<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->

<!-- time-stamp-end: "[\"']>" -->

<!-- time-stamp-format: "%:y-%02m-%02d" -->

<!-- End: -->