/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-client">

<!ENTITY TIMESTAMP "2023-10-21">

<!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>2008</year>

      <year>2009</year>

      <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>8mandos</manvolnum>

  </refmeta>

  <refnamediv>

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

    <refpurpose>

      Client for <application>Mandos</application>

    </refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group>

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

	<replaceable>ADDRESS</replaceable><literal>:</literal

	><replaceable>PORT</replaceable></option></arg>

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

	<replaceable>ADDRESS</replaceable><literal>:</literal

	><replaceable>PORT</replaceable></option></arg>

      </group>

      <sbr/>

      <group rep='repeat'>

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

	<replaceable>NAME</replaceable><arg rep='repeat'

	>,<replaceable>NAME</replaceable></arg></option></arg>

	<arg choice="plain"><option>-i <replaceable>NAME</replaceable

	><arg rep='repeat'>,<replaceable>NAME</replaceable></arg

	></option></arg>

      </group>

      <sbr/>

      <group>

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

	<replaceable>FILE</replaceable></option></arg>

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

	<replaceable>FILE</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

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

	<replaceable>FILE</replaceable></option></arg>

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

	<replaceable>FILE</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--tls-privkey

	<replaceable>FILE</replaceable></option></arg>

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

	<replaceable>FILE</replaceable></option></arg>

      </group>

      <sbr/>

      <group>

	<arg choice="plain"><option>--tls-pubkey

	<replaceable>FILE</replaceable></option></arg>

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

	<replaceable>FILE</replaceable></option></arg>

      </group>

      <sbr/>

      <arg>

	<option>--priority <replaceable>STRING</replaceable></option>

      </arg>

      <sbr/>

      <arg>

	<option>--dh-bits <replaceable>BITS</replaceable></option>

      </arg>

      <sbr/>

      <arg>

	<option>--dh-params <replaceable>FILE</replaceable></option>

      </arg>

      <sbr/>

      <arg>

	<option>--delay <replaceable>SECONDS</replaceable></option>

      </arg>

      <sbr/>

      <arg>

	<option>--retry <replaceable>SECONDS</replaceable></option>

      </arg>

      <sbr/>

      <arg>

	<option>--network-hook-dir

	<replaceable>DIR</replaceable></option>

      </arg>

      <sbr/>

      <arg>

	<option>--debug</option>

      </arg>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group choice="req">

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

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

      </group>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

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

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group choice="req">

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

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

      </group>

    </cmdsynopsis>

  </refsynopsisdiv>

  <refsect1 id="description">

    <title>DESCRIPTION</title>

    <para>

      <command>&COMMANDNAME;</command> is a client program that

      communicates with <citerefentry><refentrytitle

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

      to get a password.  In slightly more detail, this client program

      brings up network interfaces, uses the interfaces’ IPv6

      link-local addresses to get network connectivity, uses Zeroconf

      to find servers on the local network, and communicates with

      servers using TLS with a raw public key to ensure authenticity

      and confidentiality.  This client program keeps running, trying

      all servers on the network, until it receives a satisfactory

      reply or a TERM signal.  After all servers have been tried, all

      servers are periodically retried.  If no servers are found it

      will wait indefinitely for new servers to appear.

    </para>

    <para>

      The network interfaces are selected like this: If any interfaces

      are specified using the <option>--interface</option> option,

      those interface are used.  Otherwise,

      <command>&COMMANDNAME;</command> will use all interfaces that

      are not loopback interfaces, are not point-to-point interfaces,

      are capable of broadcasting and do not have the NOARP flag (see

      <citerefentry><refentrytitle>netdevice</refentrytitle>

      <manvolnum>7</manvolnum></citerefentry>).  (If the

      <option>--connect</option> option is used, point-to-point

      interfaces and non-broadcast interfaces are accepted.)  If any

      used interfaces are not up and running, they are first taken up

      (and later taken down again on program exit).

    </para>

    <para>

      Before network interfaces are selected, all <quote>network

      hooks</quote> are run; see <xref linkend="network-hooks"/>.

    </para>

    <para>

      This program is not meant to be run directly; it is really meant

      to be run by other programs in the initial

      <acronym>RAM</acronym> disk environment; see <xref

      linkend="overview"/>.

    </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>

    <para>

      This program is commonly not invoked from the command line; it

      is normally started by another program as described in <xref

      linkend="description"/>.  Any command line options this program

      accepts are therefore normally provided by the invoking program,

      and not directly.

    </para>

    <variablelist>

      <varlistentry>

	<term><option>--connect=<replaceable

	>ADDRESS</replaceable><literal>:</literal><replaceable

	>PORT</replaceable></option></term>

	<term><option>-c

	<replaceable>ADDRESS</replaceable><literal>:</literal

	><replaceable>PORT</replaceable></option></term>

	<listitem>

	  <para>

	    Do not use Zeroconf to locate servers.  Connect directly

	    to only one specified <application>Mandos</application>

	    server.  Note that an IPv6 address has colon characters in

	    it, so the <emphasis>last</emphasis> colon character is

	    assumed to separate the address from the port number.

	  </para>

	  <para>

	    Normally, Zeroconf would be used to locate Mandos servers,

	    in which case this option would only be used when testing

	    and debugging.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--interface=<replaceable

	>NAME</replaceable><arg rep='repeat'>,<replaceable

	>NAME</replaceable></arg></option></term>

	<term><option>-i

	<replaceable>NAME</replaceable><arg rep='repeat'>,<replaceable

	>NAME</replaceable></arg></option></term>

	<listitem>

	  <para>

	    Comma separated list of network interfaces that will be

	    brought up and scanned for Mandos servers to connect to.

	    The default is the empty string, which will automatically

	    use all appropriate interfaces.

	  </para>

	  <para>

	    If the <option>--connect</option> option is used, and

	    exactly one interface name is specified (except

	    <quote><literal>none</literal></quote>), this specifies

	    the interface to use to connect to the address given.

	  </para>

	  <para>

	    Note that since this program will normally run in the

	    initial RAM disk environment, the interface must be an

	    interface which exists at that stage.  Thus, the interface

	    can normally not be a pseudo-interface such as

	    <quote>br0</quote> or <quote>tun0</quote>; such interfaces

	    will not exist until much later in the boot process, and

	    can not be used by this program, unless created by a

	    <quote>network hook</quote> — see <xref

	    linkend="network-hooks"/>.

	  </para>

	  <para>

	    <replaceable>NAME</replaceable> can be the string

	    <quote><literal>none</literal></quote>; this will make

	    <command>&COMMANDNAME;</command> only bring up interfaces

	    specified <emphasis>before</emphasis> this string.  This

	    is not recommended, and only meant for advanced users.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--pubkey=<replaceable

	>FILE</replaceable></option></term>

	<term><option>-p

	<replaceable>FILE</replaceable></option></term>

	<listitem>

	  <para>

	    OpenPGP public key file name.  The default name is

	    <quote><filename>/conf/conf.d/mandos/pubkey.txt</filename

	    ></quote>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--seckey=<replaceable

	>FILE</replaceable></option></term>

	<term><option>-s

	<replaceable>FILE</replaceable></option></term>

	<listitem>

	  <para>

	    OpenPGP secret key file name.  The default name is

	    <quote><filename>/conf/conf.d/mandos/seckey.txt</filename

	    ></quote>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--tls-pubkey=<replaceable

	>FILE</replaceable></option></term>

	<term><option>-T

	<replaceable>FILE</replaceable></option></term>

	<listitem>

	  <para>

	    TLS raw public key file name.  The default name is

	    <quote><filename>/conf/conf.d/mandos/tls-pubkey.pem</filename

	    ></quote>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--tls-privkey=<replaceable

	>FILE</replaceable></option></term>

	<term><option>-t

	<replaceable>FILE</replaceable></option></term>

	<listitem>

	  <para>

	    TLS secret key file name.  The default name is

	    <quote><filename>/conf/conf.d/mandos/tls-privkey.pem</filename

	    ></quote>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--priority=<replaceable

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

	<listitem>

	  <xi:include href="../mandos-options.xml"

		      xpointer="priority"/>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--dh-bits=<replaceable

	>BITS</replaceable></option></term>

	<listitem>

	  <para>

	    Sets the number of bits to use for the prime number in the

	    TLS Diffie-Hellman key exchange.  The default value is

	    selected automatically based on the GnuTLS security

	    profile set in its priority string.  Note that if the

	    <option>--dh-params</option> option is used, the values

	    from that file will be used instead.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--dh-params=<replaceable

	>FILE</replaceable></option></term>

	<listitem>

	  <para>

	    Specifies a PEM-encoded PKCS#3 file to read the parameters

	    needed by the TLS Diffie-Hellman key exchange from.  If

	    this option is not given, or if the file for some reason

	    could not be used, the parameters will be generated on

	    startup, which will take some time and processing power.

	    Those using servers running under time, power or processor

	    constraints may want to generate such a file in advance

	    and use this option.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--delay=<replaceable

	>SECONDS</replaceable></option></term>

	<listitem>

	  <para>

	    After bringing a network interface up, the program waits

	    for the interface to arrive in a <quote>running</quote>

	    state before proceeding.  During this time, the kernel log

	    level will be lowered to reduce clutter on the system

	    console, alleviating any other plugins which might be

	    using the system console.  This option sets the upper

	    limit of seconds to wait.  The default is 2.5 seconds.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--retry=<replaceable

	>SECONDS</replaceable></option></term>

	<listitem>

	  <para>

	    All Mandos servers are tried repeatedly until a password

	    is received.  This value specifies, in seconds, how long

	    between each successive try <emphasis>for the same

	    server</emphasis>.  The default is 10 seconds.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--network-hook-dir=<replaceable

	>DIR</replaceable></option></term>

	<listitem>

	  <para>

	    Network hook directory.  The default directory is

	    <quote><filename class="directory"

	    >/lib/mandos/network-hooks.d</filename></quote>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

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

	<listitem>

	  <para>

	    Enable debug mode.  This will enable a lot of output to

	    standard error about what the program is doing.  The

	    program will still perform all other functions normally.

	  </para>

	  <para>

	    It will also enable debug mode in the Avahi and GnuTLS

	    libraries, making them print large amounts of debugging

	    output.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

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

	<term><option>-?</option></term>

	<listitem>

	  <para>

	    Gives a help message about options and their meanings.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--usage</option></term>

	<listitem>

	  <para>

	    Gives a short usage message.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--version</option></term>

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

	<listitem>

	  <para>

	    Prints the program version.

	  </para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1 id="overview">

    <title>OVERVIEW</title>

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

    <para>

      This program is the client part.  It is run automatically in an

      initial <acronym>RAM</acronym> disk environment.

    </para>

    <para>

      In an initial <acronym>RAM</acronym> disk environment using

      <citerefentry><refentrytitle>systemd</refentrytitle>

      <manvolnum>1</manvolnum></citerefentry>, this program is started

      by the <application>Mandos</application> <citerefentry>

      <refentrytitle>password-agent</refentrytitle>

      <manvolnum>8mandos</manvolnum></citerefentry>, which in turn is

      started automatically by the <citerefentry>

      <refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum>

      </citerefentry> <quote>Password Agent</quote> system.

    </para>

    <para>

      In the case of a non-<citerefentry>

      <refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum>

      </citerefentry> environment, this program is started as a plugin

      of the <application>Mandos</application> <citerefentry>

      <refentrytitle>plugin-runner</refentrytitle>

      <manvolnum>8mandos</manvolnum></citerefentry>, which runs in the

      initial <acronym>RAM</acronym> disk environment because it is

      specified as a <quote>keyscript</quote> in the <citerefentry>

      <refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>

      </citerefentry> file.

    </para>

    <para>

      This program could, theoretically, be used as a keyscript in

      <filename>/etc/crypttab</filename>, but it would then be

      impossible to enter a password for the encrypted root disk at

      the console, since this program does not read from the console

      at all.

    </para>

  </refsect1>

  <refsect1 id="exit_status">

    <title>EXIT STATUS</title>

    <para>

      This program will exit with a successful (zero) exit status if a

      server could be found and the password received from it could be

      successfully decrypted and output on standard output.  The

      program will exit with a non-zero exit status only if a critical

      error occurs.  Otherwise, it will forever connect to any

      discovered <application>Mandos</application> servers, trying to

      get a decryptable password and print it.

    </para>

  </refsect1>

  <refsect1 id="environment">

    <title>ENVIRONMENT</title>

    <variablelist>

      <varlistentry>

	<term><envar>MANDOSPLUGINHELPERDIR</envar></term>

	<listitem>

	  <para>

	    This environment variable will be assumed to contain the

	    directory containing any helper executables.  The use and

	    nature of these helper executables, if any, is purposely

	    not documented.

	</para>

	</listitem>

      </varlistentry>

    </variablelist>

    <para>

      This program does not use any other environment variables, not

      even the ones provided by <citerefentry><refentrytitle

      >cryptsetup</refentrytitle><manvolnum>8</manvolnum>

    </citerefentry>.

    </para>

  </refsect1>

  <refsect1 id="network-hooks">

    <title>NETWORK HOOKS</title>

    <para>

      If a network interface like a bridge or tunnel is required to

      find a Mandos server, this requires the interface to be up and

      running before <command>&COMMANDNAME;</command> starts looking

      for Mandos servers.  This can be accomplished by creating a

      <quote>network hook</quote> program, and placing it in a special

      directory.

    </para>

    <para>

      Before the network is used (and again before program exit), any

      runnable programs found in the network hook directory are run

      with the argument <quote><literal>start</literal></quote> or

      <quote><literal>stop</literal></quote>.  This should bring up or

      down, respectively, any network interface which

      <command>&COMMANDNAME;</command> should use.

    </para>

    <refsect2 id="hook-requirements">

      <title>REQUIREMENTS</title>

      <para>

	A network hook must be an executable file, and its name must

	consist entirely of upper and lower case letters, digits,

	underscores, periods, and hyphens.

      </para>

      <para>

	A network hook will receive one argument, which can be one of

	the following:

      </para>

      <variablelist>

	<varlistentry>

	  <term><literal>start</literal></term>

	  <listitem>

	    <para>

	      This should make the network hook create (if necessary)

	      and bring up a network interface.

	    </para>

	  </listitem>

	</varlistentry>

	<varlistentry>

	  <term><literal>stop</literal></term>

	  <listitem>

	    <para>

	      This should make the network hook take down a network

	      interface, and delete it if it did not exist previously.

	    </para>

	  </listitem>

	</varlistentry>

	<varlistentry>

	  <term><literal>files</literal></term>

	  <listitem>

	    <para>

	      This should make the network hook print, <emphasis>one

	      file per line</emphasis>, all the files needed for it to

	      run.  (These files will be copied into the initial RAM

	      filesystem.)  Typical use is for a network hook which is

	      a shell script to print its needed binaries.

	    </para>

	    <para>

	      It is not necessary to print any non-executable files

	      already in the network hook directory, these will be

	      copied implicitly if they otherwise satisfy the name

	      requirements.

	    </para>

	  </listitem>

	</varlistentry>

	<varlistentry>

	  <term><literal>modules</literal></term>

	  <listitem>

	    <para>

	      This should make the network hook print, <emphasis>on

	      separate lines</emphasis>, all the kernel modules needed

	      for it to run.  (These modules will be copied into the

	      initial RAM filesystem.)  For instance, a tunnel

	      interface needs the

	      <quote><literal>tun</literal></quote> module.

	    </para>

	  </listitem>

	</varlistentry>

      </variablelist>

      <para>

	The network hook will be provided with a number of environment

	variables:

      </para>

      <variablelist>

	<varlistentry>

	  <term><envar>MANDOSNETHOOKDIR</envar></term>

	  <listitem>

	    <para>

	      The network hook directory, specified to

	      <command>&COMMANDNAME;</command> by the

	      <option>--network-hook-dir</option> option.  Note: this

	      should <emphasis>always</emphasis> be used by the

	      network hook to refer to itself or any files in the hook

	      directory it may require.

	    </para>

	  </listitem>

	</varlistentry>

	<varlistentry>

	  <term><envar>DEVICE</envar></term>

	  <listitem>

	    <para>

	      The network interfaces, as specified to

	      <command>&COMMANDNAME;</command> by the

	      <option>--interface</option> option, combined to one

	      string and separated by commas.  If this is set, and

	      does not contain the interface a hook will bring up,

	      there is no reason for a hook to continue.

	    </para>

	  </listitem>

	</varlistentry>

	<varlistentry>

	  <term><envar>MODE</envar></term>

	  <listitem>

	    <para>

	      This will be the same as the first argument;

	      i.e. <quote><literal>start</literal></quote>,

	      <quote><literal>stop</literal></quote>,

	      <quote><literal>files</literal></quote>, or

	      <quote><literal>modules</literal></quote>.

	    </para>

	  </listitem>

	</varlistentry>

	<varlistentry>

	  <term><envar>VERBOSITY</envar></term>

	  <listitem>

	    <para>

	      This will be the <quote><literal>1</literal></quote> if