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 "2019-07-27">
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@recompile.se</email>
26
<firstname>Teddy</firstname>
27
<surname>Hogeborn</surname>
29
<email>teddy@recompile.se</email>
46
<holder>Teddy Hogeborn</holder>
47
<holder>Björn Påhlsson</holder>
49
<xi:include href="../legalnotice.xml"/>
53
<refentrytitle>&COMMANDNAME;</refentrytitle>
54
<manvolnum>8mandos</manvolnum>
58
<refname><command>&COMMANDNAME;</command></refname>
59
<refpurpose>Prompt for a password and output it.</refpurpose>
64
<command>&COMMANDNAME;</command>
66
<arg choice="plain"><option>--prefix <replaceable
67
>PREFIX</replaceable></option></arg>
68
<arg choice="plain"><option>-p </option><replaceable
69
>PREFIX</replaceable></arg>
73
<option>--prompt <replaceable>PROMPT</replaceable></option>
75
<arg choice="opt"><option>--debug</option></arg>
78
<command>&COMMANDNAME;</command>
80
<arg choice="plain"><option>--help</option></arg>
81
<arg choice="plain"><option>-?</option></arg>
85
<command>&COMMANDNAME;</command>
86
<arg choice="plain"><option>--usage</option></arg>
89
<command>&COMMANDNAME;</command>
91
<arg choice="plain"><option>--version</option></arg>
92
<arg choice="plain"><option>-V</option></arg>
97
<refsect1 id="description">
98
<title>DESCRIPTION</title>
100
All <command>&COMMANDNAME;</command> does is prompt for a
101
password and output any given password to standard output.
104
This program is not very useful on its own. This program is
105
really meant to run as a plugin in the <application
106
>Mandos</application> client-side system, where it is used as a
107
fallback and alternative to retrieving passwords from a
108
<application >Mandos</application> server.
111
This program is little more than a <citerefentry><refentrytitle
112
>getpass</refentrytitle><manvolnum>3</manvolnum></citerefentry>
113
wrapper, although actual use of that function is not guaranteed
117
This program tries to detect if a Plymouth daemon
118
(<citerefentry><refentrytitle
119
>plymouthd</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
120
is running, by looking for a
121
<filename>/run/plymouth/pid</filename> file or a process named
122
<quote><literal>plymouthd</literal></quote>. If it is detected,
123
this process will immediately exit without doing anything.
127
<refsect1 id="options">
128
<title>OPTIONS</title>
130
This program is commonly not invoked from the command line; it
131
is normally started by the <application>Mandos</application>
132
plugin runner, see <citerefentry><refentrytitle
133
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
134
</citerefentry>. Any command line options this program accepts
135
are therefore normally provided by the plugin runner, and not
141
<term><option>--prefix=<replaceable
142
>PREFIX</replaceable></option></term>
144
<replaceable>PREFIX</replaceable></option></term>
147
Prefix string shown before the password prompt.
153
<term><option>--prompt=<replaceable
154
>PROMPT</replaceable></option></term>
157
The password prompt. Using this option will make this
158
program ignore the <envar>CRYPTTAB_SOURCE</envar> and
159
<envar>CRYPTTAB_NAME</envar> environment variables.
165
<term><option>--debug</option></term>
168
Enable debug mode. This will enable a lot of output to
169
standard error about what the program is doing. The
170
program will still perform all other functions normally.
176
<term><option>--help</option></term>
177
<term><option>-?</option></term>
180
Gives a help message about options and their meanings.
186
<term><option>--usage</option></term>
189
Gives a short usage message.
195
<term><option>--version</option></term>
196
<term><option>-V</option></term>
199
Prints the program version.
206
<refsect1 id="exit_status">
207
<title>EXIT STATUS</title>
209
If exit status is 0, the output from the program is the password
210
as it was read. Otherwise, if exit status is other than 0, the
211
program has encountered an error, and any output so far could be
212
corrupt and/or truncated, and should therefore be ignored.
216
<refsect1 id="environment">
217
<title>ENVIRONMENT</title>
220
<term><envar>CRYPTTAB_SOURCE</envar></term>
221
<term><envar>CRYPTTAB_NAME</envar></term>
224
If set, and if the <option>--prompt</option> option is not
225
used, these environment variables will be assumed to
226
contain the source device name and the target device
227
mapper name, respectively, and will be shown as part of
231
These variables will normally be inherited from
232
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
233
<manvolnum>8mandos</manvolnum></citerefentry>, which might
234
have in turn inherited them from its calling process.
237
This behavior is meant to exactly mirror the behavior of
238
<command>askpass</command>, the default password prompter
239
from initramfs-tools.
248
<xi:include href="../bugs.xml"/>
251
<refsect1 id="example">
252
<title>EXAMPLE</title>
254
Note that normally, command line options will not be given
255
directly, but via options for the Mandos <citerefentry
256
><refentrytitle>plugin-runner</refentrytitle>
257
<manvolnum>8mandos</manvolnum></citerefentry>.
261
Normal invocation needs no options:
264
<userinput>&COMMANDNAME;</userinput>
269
Show a prefix before the prompt; in this case, a host name.
270
It might be useful to be reminded of which host needs a
271
password, in case of <acronym>KVM</acronym> switches, etc.
275
<!-- do not wrap this line -->
276
<userinput>&COMMANDNAME; --prefix=host.example.org:</userinput>
285
<!-- do not wrap this line -->
286
<userinput>&COMMANDNAME; --debug</userinput>
291
<refsect1 id="security">
292
<title>SECURITY</title>
294
On its own, this program is very simple, and does not exactly
295
present any security risks. The one thing that could be
296
considered worthy of note is this: This program is meant to be
297
run by <citerefentry><refentrytitle
298
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
299
</citerefentry>, and will, when run standalone, outside, in a
300
normal environment, immediately output on its standard output
301
any presumably secret password it just received. Therefore,
302
when running this program standalone (which should never
303
normally be done), take care not to type in any real secret
304
password by force of habit, since it would then immediately be
308
To further alleviate any risk of being locked out of a system,
309
the <citerefentry><refentrytitle>plugin-runner</refentrytitle>
310
<manvolnum>8mandos</manvolnum></citerefentry> has a fallback
311
mode which does the same thing as this program, only with less
316
<refsect1 id="see_also">
317
<title>SEE ALSO</title>
319
<citerefentry><refentrytitle>intro</refentrytitle>
320
<manvolnum>8mandos</manvolnum></citerefentry>,
321
<citerefentry><refentrytitle>mandos-client</refentrytitle>
322
<manvolnum>8mandos</manvolnum></citerefentry>,
323
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
324
<manvolnum>8mandos</manvolnum></citerefentry>,
325
<citerefentry><refentrytitle>plymouthd</refentrytitle>
326
<manvolnum>8</manvolnum></citerefentry>
330
<!-- Local Variables: -->
331
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
332
<!-- time-stamp-end: "[\"']>" -->
333
<!-- time-stamp-format: "%:y-%02m-%02d" -->
added
removed
plugins.d/password-prompt.xml
