<?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 "2016-06-27">
<!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>
      <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 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>
	</group>
	<sbr/>
	<group>
	  <arg choice="plain"><option>--stop-checker</option></arg>
	</group>
	<sbr/>
	<group>
	  <arg choice="plain"><option>--remove</option></arg>
	  <arg choice="plain"><option>-r</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>--interval
	  <replaceable>TIME</replaceable></option></arg>
	  <arg choice="plain"><option>-i
	  <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/>
      <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>--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>
      <group>
	<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 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>--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>
    <informalexample>
      <para>
	To list all clients:
      </para>
      <para>
	<userinput>&COMMANDNAME;</userinput>
      </para>
    </informalexample>
    
    <informalexample>
      <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>
      <para>
	To enable all clients:
      </para>
      <para>
	<userinput>&COMMANDNAME; --enable --all</userinput>
      </para>
    </informalexample>
    
    <informalexample>
      <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="5m" --interval="1m" foo1.example.org foo2.example.org</userinput>

      </para>
    </informalexample>
    
    <informalexample>
      <para>
	To approve all clients currently waiting for it:
      </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: -->
