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

<!ENTITY TIMESTAMP "2012-01-01">

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

      <year>2012</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>Prompt for a password and output it.</refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <cmdsynopsis>

      <command>&COMMANDNAME;</command>

      <group choice="opt">

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

	>PREFIX</replaceable></option></arg>

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

	>PREFIX</replaceable></arg>

      </group>

      <sbr/>

      <arg choice="opt"><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>

      All <command>&COMMANDNAME;</command> does is prompt for a

      password and output any given password to standard output.

    </para>

    <para>

      This program is not very useful on its own.  This program is

      really meant to run as a plugin in the <application

      >Mandos</application> client-side system, where it is used as a

      fallback and alternative to retrieving passwords from a

      <application >Mandos</application> server.

    </para>

    <para>

      This program is little more than a <citerefentry><refentrytitle

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

      wrapper, although actual use of that function is not guaranteed

      or implied.

    </para>

  </refsect1>

  <refsect1 id="options">

    <title>OPTIONS</title>

    <para>

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

      is normally started by the <application>Mandos</application>

      plugin runner, see <citerefentry><refentrytitle

      >plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>

      </citerefentry>.  Any command line options this program accepts

      are therefore normally provided by the plugin runner, and not

      directly.

    </para>

    <variablelist>

      <varlistentry>

	<term><option>--prefix=<replaceable

	>PREFIX</replaceable></option></term>

	<term><option>-p

	<replaceable>PREFIX</replaceable></option></term>

	<listitem>

	  <para>

	    Prefix string shown before the password prompt.

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

	</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="exit_status">

    <title>EXIT STATUS</title>

    <para>

      If exit status is 0, the output from the program is the password

      as it was read.  Otherwise, if exit status is other than 0, the

      program has encountered an error, and any output so far could be

      corrupt and/or truncated, and should therefore be ignored.

    </para>

  </refsect1>

  <refsect1 id="environment">

    <title>ENVIRONMENT</title>

    <variablelist>

      <varlistentry>

	<term><envar>CRYPTTAB_SOURCE</envar></term>

	<term><envar>CRYPTTAB_NAME</envar></term>

	<listitem>

	  <para>

	    If set, these environment variables will be assumed to

	    contain the source device name and the target device

	    mapper name, respectively, and will be shown as part of

	    the prompt.

	</para>

	<para>

	  These variables will normally be inherited from

	  <citerefentry><refentrytitle>plugin-runner</refentrytitle>

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

	  normally have inherited them from

	  <filename>/scripts/local-top/cryptroot</filename> in the

	  initial <acronym>RAM</acronym> disk environment, which will

	  have set them from parsing kernel arguments and

	  <filename>/conf/conf.d/cryptroot</filename> (also in the

	  initial RAM disk environment), which in turn will have been

	  created when the initial RAM disk image was created by

	  <filename

	  >/usr/share/initramfs-tools/hooks/cryptroot</filename>, by

	  extracting the information of the root file system from

	  <filename >/etc/crypttab</filename>.

	</para>

	<para>

	  This behavior is meant to exactly mirror the behavior of

	  <command>askpass</command>, the default password prompter.

	</para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1 id="bugs">

    <title>BUGS</title>

    <para>

      None are known at this time.

    </para>

  </refsect1>

  <refsect1 id="example">

    <title>EXAMPLE</title>

    <para>

      Note that normally, command line options will not be given

      directly, but via options for the Mandos <citerefentry

      ><refentrytitle>plugin-runner</refentrytitle>

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

    </para>

    <informalexample>

      <para>

	Normal invocation needs no options:

      </para>

      <para>

	<userinput>&COMMANDNAME;</userinput>

      </para>

    </informalexample>

    <informalexample>

      <para>

	Show a prefix before the prompt; in this case, a host name.

	It might be useful to be reminded of which host needs a

	password, in case of <acronym>KVM</acronym> switches, etc.

      </para>

      <para>

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

<userinput>&COMMANDNAME; --prefix=host.example.org:</userinput>

      </para>

    </informalexample>

    <informalexample>

      <para>

	Run in debug mode.

      </para>

      <para>

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

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

      </para>

    </informalexample>

  </refsect1>

  <refsect1 id="security">

    <title>SECURITY</title>

    <para>

      On its own, this program is very simple, and does not exactly

      present any security risks.  The one thing that could be

      considered worthy of note is this: This program is meant to be

      run by <citerefentry><refentrytitle

      >plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>

      </citerefentry>, and will, when run standalone, outside, in a

      normal environment, immediately output on its standard output

      any presumably secret password it just received.  Therefore,

      when running this program standalone (which should never

      normally be done), take care not to type in any real secret

      password by force of habit, since it would then immediately be

      shown as output.

    </para>

    <para>

      To further alleviate any risk of being locked out of a system,

      the <citerefentry><refentrytitle>plugin-runner</refentrytitle>

      <manvolnum>8mandos</manvolnum></citerefentry> has a fallback

      mode which does the same thing as this program, only with less

      features.

    </para>

  </refsect1>

  <refsect1 id="see_also">

    <title>SEE ALSO</title>

    <para>

      <citerefentry><refentrytitle>intro</refentrytitle>

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

      <citerefentry><refentrytitle>crypttab</refentrytitle>

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

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

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

      <citerefentry><refentrytitle>plugin-runner</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: -->