/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 VERSION "1.0">

<!ENTITY COMMANDNAME "plugin-runner">

<!ENTITY TIMESTAMP "2008-09-02">

]>

<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@fukt.bsnet.se</email>

	</address>

      </author>

      <author>

	<firstname>Teddy</firstname>

	<surname>Hogeborn</surname>

	<address>

	  <email>teddy@fukt.bsnet.se</email>

	</address>

      </author>

    </authorgroup>

    <copyright>

      <year>2008</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 plugins.  Pass data from first succesful one.

    </refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group rep="repeat">

	<arg choice="plain"><option>--global-env=<replaceable

	>VAR</replaceable><literal>=</literal><replaceable

	>value</replaceable></option></arg>

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

	<replaceable>VAR</replaceable><literal>=</literal><replaceable

	>value</replaceable> </option></arg>

      </group>

      <sbr/>

      <group rep="repeat">

	<arg choice="plain"><option>--env-for=<replaceable

	>PLUGIN</replaceable><literal>:</literal><replaceable

	>ENV</replaceable><literal>=</literal><replaceable

	>value</replaceable></option></arg>

	<arg choice="plain"><option>-E<replaceable>

	PLUGIN</replaceable><literal>:</literal><replaceable

	>ENV</replaceable><literal>=</literal><replaceable

	>value</replaceable> </option></arg>

      </group>

      <sbr/>

      <group rep="repeat">

	<arg choice="plain"><option>--global-options=<replaceable

	>OPTIONS</replaceable></option></arg>

	<arg choice="plain"><option>-g<replaceable>

	OPTIONS</replaceable> </option></arg>

      </group>

      <sbr/>

      <group rep="repeat">

	<arg choice="plain"><option>--options-for=<replaceable

	>PLUGIN</replaceable><literal>:</literal><replaceable

	>OPTIONS</replaceable></option></arg>

	<arg choice="plain"><option>-o<replaceable>

	PLUGIN</replaceable><literal>:</literal><replaceable

	>OPTIONS</replaceable> </option></arg>

      </group>

      <sbr/>

      <group rep="repeat">

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

	>PLUGIN</replaceable></option></arg>

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

	<replaceable>PLUGIN</replaceable> </option></arg>

      </group>

      <sbr/>

      <group rep="repeat">

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

	>PLUGIN</replaceable></option></arg>

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

	<replaceable>PLUGIN</replaceable> </option></arg>

      </group>

      <sbr/>

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

      >ID</replaceable></option></arg>

      <sbr/>

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

      >ID</replaceable></option></arg>

      <sbr/>

      <arg><option>--plugin-dir=<replaceable

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

      <sbr/>

      <arg><option>--config-file=<replaceable

      >FILE</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 program which is meant to

      be specified as <quote>keyscript</quote> in <citerefentry>

      <refentrytitle>crypttab</refentrytitle>

      <manvolnum>5</manvolnum></citerefentry> for the root disk.  The

      aim of this program is therefore to output a password, which

      then <citerefentry><refentrytitle>cryptsetup</refentrytitle>

      <manvolnum>8</manvolnum></citerefentry> will use to try and

      unlock the root disk.

    </para>

    <para>

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

      order to test it.  Note that any password obtained will simply

      be output on standard output.

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

	<replaceable>VAR</replaceable><literal>=</literal><replaceable

	>value</replaceable></option></term>

	<term><option>-e

	<replaceable>VAR</replaceable><literal>=</literal><replaceable

	>value</replaceable></option></term>

	<listitem>

	  <para>

	    This option will add an environment variable setting to

	    all plugins.  This will override any inherited environment

	    variable.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--env-for

	<replaceable>PLUGIN</replaceable><literal>:</literal

	><replaceable>ENV</replaceable><literal>=</literal

	><replaceable>value</replaceable></option></term>

	<term><option>-f

	<replaceable>PLUGIN</replaceable><literal>:</literal

	><replaceable>ENV</replaceable><literal>=</literal

	><replaceable>value</replaceable></option></term>

	<listitem>

	  <para>

	    This option will add an environment variable setting to

	    the <replaceable>PLUGIN</replaceable> plugin.  This will

	    override any inherited environment variables or

	    environment variables specified using

	    <option>--global-env</option>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--global-options

	<replaceable>OPTIONS</replaceable></option></term>

	<term><option>-g

	<replaceable>OPTIONS</replaceable></option></term>

	<listitem>

	  <para>

	    Pass some options to <emphasis>all</emphasis> plugins.

	    <replaceable>OPTIONS</replaceable> is a comma separated

	    list of options.  This is not a very useful option, except

	    for specifying the <quote><option>--debug</option></quote>

	    for all plugins.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--options-for

	<replaceable>PLUGIN</replaceable><literal>:</literal

	><replaceable>OPTION</replaceable></option></term>

	<term><option>-o

	<replaceable>PLUGIN</replaceable><literal>:</literal

	><replaceable>OPTION</replaceable></option></term>

	<listitem>

	  <para>

	    Pass some options to a specific plugin.  <replaceable

	    >PLUGIN</replaceable> is the name (file basename) of a

	    plugin, and <replaceable>OPTIONS</replaceable> is a comma

	    separated list of options.

	  </para>

	  <para>

	    Note that since options are not split on whitespace, the

	    way to pass, to the plugin

	    <quote><filename>foo</filename></quote>, the option

	    <option>--bar</option> with the option argument

	    <quote>baz</quote> is either

	    <userinput>--options-for=foo:--bar=baz</userinput> or

	    <userinput>--options-for=foo:--bar,baz</userinput>, but

	    <emphasis>not</emphasis>

	    <userinput>--options-for="foo:--bar baz"</userinput>.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--disable

	<replaceable>PLUGIN</replaceable></option></term>

	<term><option>-d

	<replaceable>PLUGIN</replaceable></option></term>

	<listitem>

	  <para>

	    Disable the plugin named

	    <replaceable>PLUGIN</replaceable>.  The plugin will not be

	    started.

	  </para>	

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--enable

	<replaceable>PLUGIN</replaceable></option></term>

	<term><option>-e

	<replaceable>PLUGIN</replaceable></option></term>

	<listitem>

	  <para>

	    Re-enable the plugin named

	    <replaceable>PLUGIN</replaceable>.  This is only useful to

	    undo a previous <option>--disable</option> option, maybe

	    from the config file.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--groupid

	<replaceable>ID</replaceable></option></term>

	<listitem>

	  <para>

	    Change to group ID <replaceable>ID</replaceable> on

	    startup.  The default is 65534.  All plugins will be

	    started using this group ID.  <emphasis>Note:</emphasis>

	    This must be a number, not a name.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--userid

	<replaceable>ID</replaceable></option></term>

	<listitem>

	  <para>

	    Change to user ID <replaceable>ID</replaceable> on

	    startup.  The default is 65534.  All plugins will be

	    started using this user ID.  <emphasis>Note:</emphasis>

	    This must be a number, not a name.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--plugin-dir

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

	<listitem>

	  <para>

	    Specify a different plugin directory.  The default is

	    <filename>/lib/mandos/plugins.d</filename>, which will

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

	    environment.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><option>--config-file

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

	<listitem>

	  <para>

	    Specify a different file to read additional options from.

	    See <xref linkend="files"/>.  Other command line options

	    will override options specified in the file.

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

	    The default is to <emphasis>not</emphasis> run in debug

	    mode.

	  </para>

	  <para>

	    The plugins will <emphasis>not</emphasis> be affected by

	    this option.  Use

	    <userinput><option>--global-options=--debug</option></userinput>

	    if complete debugging eruption is desired.

	  </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 will run on the client side in the initial

      <acronym>RAM</acronym> disk environment, and is responsible for

      getting a password.  It does this by running plugins, one of

      which will normally be the actual client program communicating

      with the server.

    </para>

  </refsect1>

  <refsect1 id="plugins">

    <title>PLUGINS</title>

    <para>

      This program will get a password by running a number of

      <firstterm>plugins</firstterm>, which are simply executable

      programs in a directory in the initial <acronym>RAM</acronym>

      disk environment.  The default directory is

      <filename>/lib/mandos/plugins.d</filename>, but this can be

      changed with the <option>--plugin-dir</option> option.  The

      plugins are started in parallel, and the first plugin to output

      a password <emphasis>and</emphasis> exit with a successful exit

      code will make this plugin-runner output the password from that

      plugin, stop any other plugins, and exit.

    </para>

  </refsect1>

  <refsect1 id="fallback">

    <title>FALLBACK</title>

    <para>

      If no plugins succeed, this program will, as a fallback, ask for

      a password on the console using <citerefentry><refentrytitle

      >getpass</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

      and output it.  This is not meant to be the normal mode of

      operation, as there is a separate plugin for getting a password

      from the console.

    </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.  The fallback (see <xref

      linkend="fallback"/>) may or may not have succeeded in either

      case.

    </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 all the plugins.  The

      environment passed to plugins can be modified using the

      <option>--global-env</option> and <option>--env-for</option>

      optins.

    </para>

  </refsect1>

  <refsect1 id="files">

    <title>FILES</title>

    <para>

      <variablelist>

	<varlistentry>

	  <term><filename

	  >/conf/conf.d/mandos/plugin-runner.conf</filename></term>

	  <listitem>

	    <para>

	      Since this program will be run as a keyscript, there is

	      little to no opportunity to pass command line arguments

	      to it.  Therefore, it will <emphasis>also</emphasis>

	      read this file and use its contents as

	      whitespace-separated command line options.  Also,

	      everything from a <quote>#</quote> character to the end

	      of a line is ignored.

	    </para>

	    <para>

	      This program is meant to run in the initial RAM disk

	      environment, so that is where this file is assumed to

	      exist.  The file does not need to exist in the normal

	      file system.

	    </para>

	    <para>

	      This file will be processed <emphasis>before</emphasis>

	      the normal command line options, so the latter can

	      override the former, if need be.

	    </para>

	    <para>

	      This file name is the default; the file to read for

	      arguments can be changed using the

	      <option>--config-file</option> option.

	    </para>

	  </listitem>

	</varlistentry>

      </variablelist>

    </para>

  </refsect1>

  <refsect1 id="bugs">

    <title>BUGS</title>

    <para>

    </para>

  </refsect1>

  <refsect1 id="examples">

    <title>EXAMPLE</title>

    <para>

    </para>

  </refsect1>

  <refsect1 id="security">

    <title>SECURITY</title>

    <para>

    </para>

  </refsect1>

  <refsect1 id="see_also">

    <title>SEE ALSO</title>

    <para>

      <citerefentry><refentrytitle>cryptsetup</refentrytitle>

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

      <citerefentry><refentrytitle>mandos</refentrytitle>

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

      <citerefentry><refentrytitle>password-prompt</refentrytitle>

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

      <citerefentry><refentrytitle>password-request</refentrytitle>

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

    </para>

  </refsect1>

</refentry>

<!-- Local Variables: -->

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

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

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

<!-- End: -->