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 "2008-10-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>
35
<holder>Teddy Hogeborn</holder>
36
<holder>Björn Påhlsson</holder>
38
<xi:include href="../legalnotice.xml"/>
42
<refentrytitle>&COMMANDNAME;</refentrytitle>
43
<manvolnum>8mandos</manvolnum>
47
<refname><command>&COMMANDNAME;</command></refname>
48
<refpurpose>Prompt for a password and output it.</refpurpose>
53
<command>&COMMANDNAME;</command>
55
<arg choice="plain"><option>--prefix <replaceable
56
>PREFIX</replaceable></option></arg>
57
<arg choice="plain"><option>-p </option><replaceable
58
>PREFIX</replaceable></arg>
61
<arg choice="opt"><option>--debug</option></arg>
64
<command>&COMMANDNAME;</command>
66
<arg choice="plain"><option>--help</option></arg>
67
<arg choice="plain"><option>-?</option></arg>
71
<command>&COMMANDNAME;</command>
72
<arg choice="plain"><option>--usage</option></arg>
75
<command>&COMMANDNAME;</command>
77
<arg choice="plain"><option>--version</option></arg>
78
<arg choice="plain"><option>-V</option></arg>
83
<refsect1 id="description">
84
<title>DESCRIPTION</title>
86
All <command>&COMMANDNAME;</command> does is prompt for a
87
password and output any given password to standard output.
90
This program is not very useful on its own. This program is
91
really meant to run as a plugin in the <application
92
>Mandos</application> client-side system, where it is used as a
93
fallback and alternative to retrieving passwords from a
94
<application >Mandos</application> server.
97
This program is little more than a <citerefentry><refentrytitle
98
>getpass</refentrytitle><manvolnum>3</manvolnum></citerefentry>
99
wrapper, although actual use of that function is not guaranteed
104
<refsect1 id="options">
105
<title>OPTIONS</title>
107
This program is commonly not invoked from the command line; it
108
is normally started by the <application>Mandos</application>
109
plugin runner, see <citerefentry><refentrytitle
110
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
111
</citerefentry>. Any command line options this program accepts
112
are therefore normally provided by the plugin runner, and not
118
<term><option>--prefix=<replaceable
119
>PREFIX</replaceable></option></term>
121
<replaceable>PREFIX</replaceable></option></term>
124
Prefix string shown before the password prompt.
130
<term><option>--debug</option></term>
133
Enable debug mode. This will enable a lot of output to
134
standard error about what the program is doing. The
135
program will still perform all other functions normally.
141
<term><option>--help</option></term>
142
<term><option>-?</option></term>
145
Gives a help message about options and their meanings.
151
<term><option>--usage</option></term>
154
Gives a short usage message.
160
<term><option>--version</option></term>
161
<term><option>-V</option></term>
164
Prints the program version.
171
<refsect1 id="exit_status">
172
<title>EXIT STATUS</title>
174
If exit status is 0, the output from the program is the password
175
as it was read. Otherwise, if exit status is other than 0, the
176
program has encountered an error, and any output so far could be
177
corrupt and/or truncated, and should therefore be ignored.
181
<refsect1 id="environment">
182
<title>ENVIRONMENT</title>
185
<term><envar>cryptsource</envar></term>
186
<term><envar>crypttarget</envar></term>
189
If set, these environment variables will be assumed to
190
contain the source device name and the target device
191
mapper name, respectively, and will be shown as part of
195
These variables will normally be inherited from
196
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
197
<manvolnum>8mandos</manvolnum></citerefentry>, which will
198
normally have inherited them from
199
<filename>/scripts/local-top/cryptroot</filename> in the
200
initial <acronym>RAM</acronym> disk environment, which will
201
have set them from parsing kernel arguments and
202
<filename>/conf/conf.d/cryptroot</filename> (also in the
203
initial RAM disk environment), which in turn will have been
204
created when the initial RAM disk image was created by
206
>/usr/share/initramfs-tools/hooks/cryptroot</filename>, by
207
extracting the information of the root file system from
208
<filename >/etc/crypttab</filename>.
211
This behavior is meant to exactly mirror the behavior of
212
<command>askpass</command>, the default password prompter.
222
None are known at this time.
226
<refsect1 id="example">
227
<title>EXAMPLE</title>
229
Note that normally, command line options will not be given
230
directly, but via options for the Mandos <citerefentry
231
><refentrytitle>plugin-runner</refentrytitle>
232
<manvolnum>8mandos</manvolnum></citerefentry>.
236
Normal invocation needs no options:
239
<userinput>&COMMANDNAME;</userinput>
244
Show a prefix before the prompt; in this case, a host name.
245
It might be useful to be reminded of which host needs a
246
password, in case of <acronym>KVM</acronym> switches, etc.
250
<!-- do not wrap this line -->
251
<userinput>&COMMANDNAME; --prefix=host.example.org:</userinput>
260
<!-- do not wrap this line -->
261
<userinput>&COMMANDNAME; --debug</userinput>
266
<refsect1 id="security">
267
<title>SECURITY</title>
269
On its own, this program is very simple, and does not exactly
270
present any security risks. The one thing that could be
271
considered worthy of note is this: This program is meant to be
272
run by <citerefentry><refentrytitle
273
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
274
</citerefentry>, and will, when run standalone, outside, in a
275
normal environment, immediately output on its standard output
276
any presumably secret password it just received. Therefore,
277
when running this program standalone (which should never
278
normally be done), take care not to type in any real secret
279
password by force of habit, since it would then immediately be
283
To further alleviate any risk of being locked out of a system,
284
the <citerefentry><refentrytitle>plugin-runner</refentrytitle>
285
<manvolnum>8mandos</manvolnum></citerefentry> has a fallback
286
mode which does the same thing as this program, only with less
291
<refsect1 id="see_also">
292
<title>SEE ALSO</title>
294
<citerefentry><refentrytitle>crypttab</refentrytitle>
295
<manvolnum>5</manvolnum></citerefentry>
296
<citerefentry><refentrytitle>mandos-client</refentrytitle>
297
<manvolnum>8mandos</manvolnum></citerefentry>
298
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
299
<manvolnum>8mandos</manvolnum></citerefentry>,
303
<!-- Local Variables: -->
304
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
305
<!-- time-stamp-end: "[\"']>" -->
306
<!-- time-stamp-format: "%:y-%02m-%02d" -->
added
removed
plugins.d/password-prompt.xml
