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 VERSION "1.0">
5
<!ENTITY COMMANDNAME "password-prompt">
6
<!ENTITY TIMESTAMP "2008-09-06">
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
<title>Mandos Manual</title>
12
<!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
<productname>Mandos</productname>
14
<productnumber>&VERSION;</productnumber>
15
<date>&TIMESTAMP;</date>
18
<firstname>Björn</firstname>
19
<surname>Påhlsson</surname>
21
<email>belorn@fukt.bsnet.se</email>
25
<firstname>Teddy</firstname>
26
<surname>Hogeborn</surname>
28
<email>teddy@fukt.bsnet.se</email>
34
<holder>Teddy Hogeborn</holder>
35
<holder>Björn Påhlsson</holder>
37
<xi:include href="../legalnotice.xml"/>
41
<refentrytitle>&COMMANDNAME;</refentrytitle>
42
<manvolnum>8mandos</manvolnum>
46
<refname><command>&COMMANDNAME;</command></refname>
47
<refpurpose>Prompt for a password and output it.</refpurpose>
52
<command>&COMMANDNAME;</command>
54
<arg choice="plain"><option>--prefix <replaceable
55
>PREFIX</replaceable></option></arg>
56
<arg choice="plain"><option>-p </option><replaceable
57
>PREFIX</replaceable></arg>
60
<arg choice="opt"><option>--debug</option></arg>
63
<command>&COMMANDNAME;</command>
65
<arg choice="plain"><option>--help</option></arg>
66
<arg choice="plain"><option>-?</option></arg>
70
<command>&COMMANDNAME;</command>
71
<arg choice="plain"><option>--usage</option></arg>
74
<command>&COMMANDNAME;</command>
76
<arg choice="plain"><option>--version</option></arg>
77
<arg choice="plain"><option>-V</option></arg>
82
<refsect1 id="description">
83
<title>DESCRIPTION</title>
85
All <command>&COMMANDNAME;</command> does is prompt for a
86
password and output any given password to standard output. This
87
is not very useful on its own. This program is really meant to
88
run as a plugin in the <application>Mandos</application>
89
client-side system, where it is used as a fallback and
90
alternative to retrieving passwords from a <application
91
>Mandos</application> server.
94
This program is little more than a <citerefentry><refentrytitle
95
>getpass</refentrytitle><manvolnum>3</manvolnum></citerefentry>
96
wrapper, although actual use of that function is not guaranteed
101
<refsect1 id="options">
102
<title>OPTIONS</title>
104
This program is commonly not invoked from the command line; it
105
is normally started by the <application>Mandos</application>
106
plugin runner, see <citerefentry><refentrytitle
107
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
108
</citerefentry>. Any command line options this program accepts
109
are therefore normally provided by the plugin runner, and not
115
<term><option>--prefix=<replaceable
116
>PREFIX</replaceable></option></term>
118
<replaceable>PREFIX</replaceable></option></term>
121
Prefix string shown before the password prompt.
127
<term><option>--debug</option></term>
130
Enable debug mode. This will enable a lot of output to
131
standard error about what the program is doing. The
132
program will still perform all other functions normally.
138
<term><option>--help</option></term>
139
<term><option>-?</option></term>
142
Gives a help message about options and their meanings.
148
<term><option>--usage</option></term>
151
Gives a short usage message.
157
<term><option>--version</option></term>
158
<term><option>-V</option></term>
161
Prints the program version.
168
<refsect1 id="exit_status">
169
<title>EXIT STATUS</title>
171
If exit status is 0, the output from the program is the password
172
as it was read. Otherwise, if exit status is other than 0, the
173
program has encountered an error, and any output so far could be
174
corrupt and/or truncated, and should therefore be ignored.
178
<refsect1 id="environment">
179
<title>ENVIRONMENT</title>
182
<term><envar>cryptsource</envar></term>
183
<term><envar>crypttarget</envar></term>
186
If set, these environment variables will be assumed to
187
contain the source device name and the target device
188
mapper name, respectively, and will be shown as part of
192
These variables will normally be inherited from
193
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
194
<manvolnum>8mandos</manvolnum></citerefentry>, which will
195
normally have inherited them from
196
<filename>/scripts/local-top/cryptroot</filename> in the
197
initial <acronym>RAM</acronym> disk environment, which will
198
have set them from parsing kernel arguments and
199
<filename>/conf/conf.d/cryptroot</filename> (also in the
200
initial RAM disk environment), which in turn will have been
201
created when the initial RAM disk image was created by
203
>/usr/share/initramfs-tools/hooks/cryptroot</filename>, by
204
extracting the information of the root file system from
205
<filename >/etc/crypttab</filename>.
208
This behavior is meant to exactly mirror the behavior of
209
<command>askpass</command>, the default password prompter.
219
None are known at this time.
223
<refsect1 id="example">
224
<title>EXAMPLE</title>
226
Note that normally, command line options will not be given
227
directly, but via options for the Mandos <citerefentry
228
><refentrytitle>plugin-runner</refentrytitle>
229
<manvolnum>8mandos</manvolnum></citerefentry>.
233
Normal invocation needs no options:
236
<userinput>&COMMANDNAME;</userinput>
241
Show a prefix before the prompt; in this case, a host name.
242
It might be useful to be reminded of which host needs a
243
password, in case of <acronym>KVM</acronym> switches, etc.
247
<!-- do not wrap this line -->
248
<userinput>&COMMANDNAME; --prefix=host.example.org:</userinput>
257
<!-- do not wrap this line -->
258
<userinput>&COMMANDNAME; --debug</userinput>
263
<refsect1 id="security">
264
<title>SECURITY</title>
266
On its own, this program is very simple, and does not exactly
267
present any security risks. The one thing that could be
268
considered worthy of note is this: This program is meant to be
269
run by <citerefentry><refentrytitle
270
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
271
</citerefentry>, and will, when run standalone, outside, in a
272
normal environment, immediately output on its standard output
273
any presumably secret password it just received. Therefore,
274
when running this program standalone (which should never
275
normally be done), take care not to type in any real secret
276
password by force of habit, since it would then immediately be
280
To further alleviate any risk of being locked out of a system,
281
the <citerefentry><refentrytitle>plugin-runner</refentrytitle>
282
<manvolnum>8mandos</manvolnum></citerefentry> has a fallback
283
mode which does the same thing as this program, only with less
288
<refsect1 id="see_also">
289
<title>SEE ALSO</title>
291
<citerefentry><refentrytitle>crypttab</refentrytitle>
292
<manvolnum>5</manvolnum></citerefentry>
293
<citerefentry><refentrytitle>mandos-client</refentrytitle>
294
<manvolnum>8mandos</manvolnum></citerefentry>
295
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
296
<manvolnum>8mandos</manvolnum></citerefentry>,
300
<!-- Local Variables: -->
301
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
302
<!-- time-stamp-end: "[\"']>" -->
303
<!-- time-stamp-format: "%:y-%02m-%02d" -->
added
removed
plugins.d/password-prompt.xml
