1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
<!ENTITY COMMANDNAME "password-prompt">
5
<!ENTITY TIMESTAMP "2009-01-04">
6
<!ENTITY % common SYSTEM "../common.ent">
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
12
<title>Mandos Manual</title>
13
<!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
<productname>Mandos</productname>
15
<productnumber>&version;</productnumber>
16
<date>&TIMESTAMP;</date>
19
<firstname>Björn</firstname>
20
<surname>Påhlsson</surname>
22
<email>belorn@fukt.bsnet.se</email>
26
<firstname>Teddy</firstname>
27
<surname>Hogeborn</surname>
29
<email>teddy@fukt.bsnet.se</email>
36
<holder>Teddy Hogeborn</holder>
37
<holder>Björn Påhlsson</holder>
39
<xi:include href="../legalnotice.xml"/>
43
<refentrytitle>&COMMANDNAME;</refentrytitle>
44
<manvolnum>8mandos</manvolnum>
48
<refname><command>&COMMANDNAME;</command></refname>
49
<refpurpose>Prompt for a password and output it.</refpurpose>
54
<command>&COMMANDNAME;</command>
56
<arg choice="plain"><option>--prefix <replaceable
57
>PREFIX</replaceable></option></arg>
58
<arg choice="plain"><option>-p </option><replaceable
59
>PREFIX</replaceable></arg>
62
<arg choice="opt"><option>--debug</option></arg>
65
<command>&COMMANDNAME;</command>
67
<arg choice="plain"><option>--help</option></arg>
68
<arg choice="plain"><option>-?</option></arg>
72
<command>&COMMANDNAME;</command>
73
<arg choice="plain"><option>--usage</option></arg>
76
<command>&COMMANDNAME;</command>
78
<arg choice="plain"><option>--version</option></arg>
79
<arg choice="plain"><option>-V</option></arg>
84
<refsect1 id="description">
85
<title>DESCRIPTION</title>
87
All <command>&COMMANDNAME;</command> does is prompt for a
88
password and output any given password to standard output.
91
This program is not very useful on its own. This program is
92
really meant to run as a plugin in the <application
93
>Mandos</application> client-side system, where it is used as a
94
fallback and alternative to retrieving passwords from a
95
<application >Mandos</application> server.
98
This program is little more than a <citerefentry><refentrytitle
99
>getpass</refentrytitle><manvolnum>3</manvolnum></citerefentry>
100
wrapper, although actual use of that function is not guaranteed
105
<refsect1 id="options">
106
<title>OPTIONS</title>
108
This program is commonly not invoked from the command line; it
109
is normally started by the <application>Mandos</application>
110
plugin runner, see <citerefentry><refentrytitle
111
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
112
</citerefentry>. Any command line options this program accepts
113
are therefore normally provided by the plugin runner, and not
119
<term><option>--prefix=<replaceable
120
>PREFIX</replaceable></option></term>
122
<replaceable>PREFIX</replaceable></option></term>
125
Prefix string shown before the password prompt.
131
<term><option>--debug</option></term>
134
Enable debug mode. This will enable a lot of output to
135
standard error about what the program is doing. The
136
program will still perform all other functions normally.
142
<term><option>--help</option></term>
143
<term><option>-?</option></term>
146
Gives a help message about options and their meanings.
152
<term><option>--usage</option></term>
155
Gives a short usage message.
161
<term><option>--version</option></term>
162
<term><option>-V</option></term>
165
Prints the program version.
172
<refsect1 id="exit_status">
173
<title>EXIT STATUS</title>
175
If exit status is 0, the output from the program is the password
176
as it was read. Otherwise, if exit status is other than 0, the
177
program has encountered an error, and any output so far could be
178
corrupt and/or truncated, and should therefore be ignored.
182
<refsect1 id="environment">
183
<title>ENVIRONMENT</title>
186
<term><envar>cryptsource</envar></term>
187
<term><envar>crypttarget</envar></term>
190
If set, these environment variables will be assumed to
191
contain the source device name and the target device
192
mapper name, respectively, and will be shown as part of
196
These variables will normally be inherited from
197
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
198
<manvolnum>8mandos</manvolnum></citerefentry>, which will
199
normally have inherited them from
200
<filename>/scripts/local-top/cryptroot</filename> in the
201
initial <acronym>RAM</acronym> disk environment, which will
202
have set them from parsing kernel arguments and
203
<filename>/conf/conf.d/cryptroot</filename> (also in the
204
initial RAM disk environment), which in turn will have been
205
created when the initial RAM disk image was created by
207
>/usr/share/initramfs-tools/hooks/cryptroot</filename>, by
208
extracting the information of the root file system from
209
<filename >/etc/crypttab</filename>.
212
This behavior is meant to exactly mirror the behavior of
213
<command>askpass</command>, the default password prompter.
223
None are known at this time.
227
<refsect1 id="example">
228
<title>EXAMPLE</title>
230
Note that normally, command line options will not be given
231
directly, but via options for the Mandos <citerefentry
232
><refentrytitle>plugin-runner</refentrytitle>
233
<manvolnum>8mandos</manvolnum></citerefentry>.
237
Normal invocation needs no options:
240
<userinput>&COMMANDNAME;</userinput>
245
Show a prefix before the prompt; in this case, a host name.
246
It might be useful to be reminded of which host needs a
247
password, in case of <acronym>KVM</acronym> switches, etc.
251
<!-- do not wrap this line -->
252
<userinput>&COMMANDNAME; --prefix=host.example.org:</userinput>
261
<!-- do not wrap this line -->
262
<userinput>&COMMANDNAME; --debug</userinput>
267
<refsect1 id="security">
268
<title>SECURITY</title>
270
On its own, this program is very simple, and does not exactly
271
present any security risks. The one thing that could be
272
considered worthy of note is this: This program is meant to be
273
run by <citerefentry><refentrytitle
274
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
275
</citerefentry>, and will, when run standalone, outside, in a
276
normal environment, immediately output on its standard output
277
any presumably secret password it just received. Therefore,
278
when running this program standalone (which should never
279
normally be done), take care not to type in any real secret
280
password by force of habit, since it would then immediately be
284
To further alleviate any risk of being locked out of a system,
285
the <citerefentry><refentrytitle>plugin-runner</refentrytitle>
286
<manvolnum>8mandos</manvolnum></citerefentry> has a fallback
287
mode which does the same thing as this program, only with less
292
<refsect1 id="see_also">
293
<title>SEE ALSO</title>
295
<citerefentry><refentrytitle>crypttab</refentrytitle>
296
<manvolnum>5</manvolnum></citerefentry>
297
<citerefentry><refentrytitle>mandos-client</refentrytitle>
298
<manvolnum>8mandos</manvolnum></citerefentry>
299
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
300
<manvolnum>8mandos</manvolnum></citerefentry>,
304
<!-- Local Variables: -->
305
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
306
<!-- time-stamp-end: "[\"']>" -->
307
<!-- time-stamp-format: "%:y-%02m-%02d" -->
added
removed
plugins.d/password-prompt.xml
