/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 "password-agent">

<!ENTITY TIMESTAMP "2020-09-16">

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

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

      Run Mandos client as a systemd password agent.

    </refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <arg><option>--agent-directory=<replaceable

      >DIRECTORY</replaceable></option></arg>

      <sbr/>

      <arg><option>--helper-directory=<replaceable

      >DIRECTORY</replaceable></option></arg>

      <sbr/>

      <!-- <arg><option>-\-plugin-helper-dir=<replaceable -->

      <!-- >DIRECTORY</replaceable></option></arg> -->

      <!-- <sbr/> -->

      <arg><option>--user=<replaceable

      >USERID</replaceable></option></arg>

      <sbr/>

      <!-- <arg><option>-\-userid=<replaceable -->

      <!-- >ID</replaceable></option></arg> -->

      <!-- <sbr/> -->

      <arg><option>--group=<replaceable

      >GROUPID</replaceable></option></arg>

      <sbr/>

      <!-- <arg><option>-\-groupid=<replaceable -->

      <!-- >ID</replaceable></option></arg> -->

      <!-- <sbr/> -->

      <arg>--</arg>

      <arg>

	<replaceable>MANDOS_CLIENT</replaceable>

	<group rep="repeat">

	  <arg choice="plain"><replaceable>OPTIONS</replaceable></arg>

	</group>

      </arg>

    </cmdsynopsis>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <arg choice="plain"><option>--test</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 program which is meant to

      be a <citerefentry><refentrytitle>systemd</refentrytitle>

      <manvolnum>1</manvolnum></citerefentry> <quote>Password

      Agent</quote> (See <ulink

      url="https://systemd.io/PASSWORD_AGENTS/">Password

      Agents</ulink>).  The aim of this program is therefore to

      acquire and then send a password to some other program which

      will use the password to unlock the encrypted root disk.

    </para>

    <para>

      This program is not meant to be invoked directly, but can be in

      order to test it.

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

    <title>OPTIONS</title>

    <variablelist>

      <varlistentry>

	<term><option>--agent-directory

	<replaceable>DIRECTORY</replaceable></option></term>

	<listitem>

	  <para>

	    Specify a different agent directory.  The default is

	    <quote><filename class="directory"

	    >/run/systemd/ask-password</filename ></quote> as per the

	    <ulink url="https://systemd.io/PASSWORD_AGENTS/">Password

	    Agents</ulink> specification.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--helper-directory

	<replaceable>DIRECTORY</replaceable></option></term>

	<listitem>

	  <para>

	    Specify a different helper directory.  The default is

	    <quote><filename class="directory"

			     >/lib/mandos/plugin-helpers</filename

			     ></quote>, which

	    will exist in the initial <acronym>RAM</acronym> disk

	    environment.  (This will simply be passed to the

	    <replaceable>MANDOS_CLIENT</replaceable> program via the

	    <envar>MANDOSPLUGINHELPERDIR</envar> environment variable.

	    See

	    <citerefentry><refentrytitle>mandos-client</refentrytitle

	    ><manvolnum>8mandos</manvolnum></citerefentry>.)

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--user

	<replaceable>USERID</replaceable></option></term>

	<listitem>

	  <para>

	    Change real user ID to <replaceable>USERID</replaceable>

	    when running <replaceable>MANDOS_CLIENT</replaceable>.

	    The default is 65534.  <emphasis>Note:</emphasis> This

	    must be a number, not a name.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--group

	<replaceable>GROUPID</replaceable></option></term>

	<listitem>

	  <para>

	    Change real group ID to <replaceable>GROUPID</replaceable>

	    when running <replaceable>MANDOS_CLIENT</replaceable>.

	    The default is 65534.  <emphasis>Note:</emphasis> This

	    must be a number, not a name.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><replaceable>MANDOS_CLIENT</replaceable></term>

	<listitem>

	  <para>

	    This specifies the file name for

	    <citerefentry><refentrytitle>mandos-client</refentrytitle

	    ><manvolnum>8mandos</manvolnum></citerefentry>.  If the

	    <quote><option>--</option></quote> option is given, any

	    following options are passed to the <replaceable

	    >MANDOS_CLIENT</replaceable> program.  The default is

	    <quote><filename

	    >/lib/mandos/plugins.d/mandos-client</filename ></quote>

	    (which is the correct location for the initial

	    <acronym>RAM</acronym> disk environment) without any

	    options.

	  </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>--test</option></term>

	<listitem>

	  <para>

	    Ignore normal operation; instead only run self-tests.

	    Adding the <option>--help</option> option may show more

	    options possible in combination with

	    <option>--test</option>.

	  </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, &COMMANDNAME;, will run on the client side in the

      initial <acronym>RAM</acronym> disk environment, and is

      responsible for getting a password from the Mandos client

      program itself, and to send that password to whatever is

      currently asking for a password using the systemd <ulink

      url="https://systemd.io/PASSWORD_AGENTS/">Password

      Agents</ulink> mechanism.

    </para>

    <para>To accomplish this, &COMMANDNAME; runs the

    <command>mandos-client</command> program (which is the actual

    client program communicating with the Mandos server) or,

    alternatively, any executable file specified as

    <replaceable>MANDOS_CLIENT</replaceable>, and, as soon as a

    password is acquired from the

    <replaceable>MANDOS_CLIENT</replaceable> program, sends that

    password (as per the <ulink

    url="https://systemd.io/PASSWORD_AGENTS/">Password Agents</ulink>

    specification) to all currently unanswered password questions.

    </para>

    <para>

      This program should be started (normally as a systemd service,

      which in turn is normally started by a <citerefentry

      ><refentrytitle>systemd.path</refentrytitle>

      <manvolnum>5</manvolnum></citerefentry> file) as a reaction to

      files named <quote><filename>ask.<replaceable>xxxx</replaceable

      ></filename></quote> appearing in the agent directory

      <quote><filename

      class="directory">/run/systemd/ask-password</filename></quote>

      (or the directory specified by

      <option>--agent-directory</option>).

    </para>

  </refsect1>

  <refsect1 id="exit_status">

    <title>EXIT STATUS</title>

    <para>

      Exit status of this program is zero if no errors were

      encountered, and otherwise not.

    </para>

  </refsect1>

  <refsect1 id="environment">

    <title>ENVIRONMENT</title>

    <para>

      This program does not use any environment variables itself, it

      only passes on its environment to

      <replaceable>MANDOS_CLIENT</replaceable>.  Also, the

      <option>--helper-directory</option> option will affect the

      environment variable <envar>MANDOSPLUGINHELPERDIR</envar> for

      <replaceable>MANDOS_CLIENT</replaceable>.

    </para>

  </refsect1>

  <refsect1 id="files">

    <title>FILES</title>

    <para>

      <variablelist>

	<varlistentry>

	  <term><filename class="directory"

			  >/run/systemd/ask-password</filename></term>

	  <listitem>

	    <para>

	      The default directory to watch for password questions as

	      per the <ulink

	      url="https://systemd.io/PASSWORD_AGENTS/">Password

	      Agents</ulink> specification; can be changed by the

	      <option>--agent-directory</option> option.

	    </para>

	  </listitem>

	</varlistentry>

	<varlistentry>

	  <term><filename class="directory"

			  >/lib/mandos/plugin-helpers</filename

			  ></term>

	  <listitem>

	    <para>

	      The helper directory as supplied to

	      <replaceable>MANDOS_CLIENT</replaceable> via the

	      <envar>MANDOSPLUGINHELPERDIR</envar> environment

	      variable; can be changed by the

	      <option>--helper-directory</option> option.

	    </para>

	  </listitem>

	</varlistentry>

      </variablelist>

    </para>

  </refsect1>

  <refsect1 id="bugs">

    <title>BUGS</title>

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

  </refsect1>

  <refsect1 id="examples">

    <title>EXAMPLE</title>

    <informalexample>

      <para>

	Normal invocation needs no options:

      </para>

      <para>

	<userinput>&COMMANDNAME;</userinput>

      </para>

    </informalexample>

    <informalexample>

      <para>

	Run an alternative <replaceable>MANDOS_CLIENT</replaceable>

	program::

      </para>

      <para>

	<userinput>&COMMANDNAME; /usr/local/sbin/alternate</userinput>

      </para>

    </informalexample>

    <informalexample>

      <para>

	Use alternative locations for the helper directory and the

	Mandos client, and add extra options suitable for running in

	the normal file system:

      </para>

      <para>

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

	<userinput>&COMMANDNAME; --helper-directory=/usr/lib/x86_64-linux-gnu/mandos/plugin-helpers -- /usr/lib/x86_64-linux-gnu/mandos/plugins.d/mandos-client --pubkey=/etc/keys/mandos/pubkey.txt --seckey=/etc/keys/mandos/seckey.txt --tls-pubkey=/etc/keys/mandos/tls-pubkey.pem --tls-privkey=/etc/keys/mandos/tls-privkey.pem</userinput>

      </para>

    </informalexample>

    <informalexample>

      <para>

	Use the default location for

	<citerefentry><refentrytitle>mandos-client</refentrytitle>

	<manvolnum>8mandos</manvolnum></citerefentry>, but add many

	options to it:

      </para>

      <para>

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

<userinput>&COMMANDNAME; -- /lib/mandos/plugins.d/mandos-client --pubkey=/etc/mandos/keys/pubkey.txt --seckey=/etc/mandos/keys/seckey.txt --tls-pubkey=/etc/mandos/keys/tls-pubkey.pem --tls-privkey=/etc/mandos/keys/tls-privkey.pem</userinput>

      </para>

    </informalexample>

    <informalexample>

      <para>

	Only run the self-tests:

      </para>

      <para>

	<userinput>&COMMANDNAME; --test</userinput>

      </para>

    </informalexample>

  </refsect1>

  <refsect1 id="security">

    <title>SECURITY</title>

    <para>

      This program will need to run as the root user in order to read

      the agent directory and the <quote><filename

      >ask.<replaceable>xxxx</replaceable></filename></quote> files

      there, and will, when starting the Mandos client program,

      require the ability to set the <quote>real</quote> user and

      group ids to another user, by default user and group 65534,

      which are assumed to be non-privileged.  This is done in order

      to match the expectations of <citerefentry><refentrytitle

      >mandos-client</refentrytitle><manvolnum>8mandos</manvolnum

      ></citerefentry>, which assumes that its executable file is

      owned by the root user and also has the set-user-ID bit set (see

      <citerefentry><refentrytitle>execve</refentrytitle><manvolnum

      >2</manvolnum></citerefentry>).

    </para>

  </refsect1>

  <refsect1 id="see_also">

    <title>SEE ALSO</title>

    <para>

      <citerefentry><refentrytitle>intro</refentrytitle>

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

      <citerefentry><refentrytitle>mandos-client</refentrytitle>

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

      <citerefentry><refentrytitle>systemd</refentrytitle>

      <manvolnum>1</manvolnum></citerefentry>,

    </para>

    <variablelist>

      <varlistentry>

	<term>

	  <ulink url="https://systemd.io/PASSWORD_AGENTS/">Password

	  Agents</ulink>

	</term>

	<listitem>

	  <para>

	    The specification for systemd <quote>Password

	    Agent</quote> programs, which

	    <command>&COMMANDNAME;</command> follows.

	  </para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

</refentry>

<!-- Local Variables: -->

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

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

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

<!-- End: -->