1
<?xml version='1.0' encoding='UTF-8'?>
2
<?xml-stylesheet type="text/xsl"
3
href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
1
<?xml version="1.0" encoding="UTF-8"?>
4
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
5
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
6
<!ENTITY VERSION "1.0">
7
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>&COMMANDNAME;</title>
13
<!-- NWalsh's docbook scripts use this to generate the footer: -->
14
<productname>&COMMANDNAME;</productname>
15
<productnumber>&VERSION;</productnumber>
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>
18
19
<firstname>Björn</firstname>
19
20
<surname>Påhlsson</surname>
21
<email>belorn@fukt.bsnet.se</email>
22
<email>belorn@recompile.se</email>
25
26
<firstname>Teddy</firstname>
26
27
<surname>Hogeborn</surname>
28
<email>teddy@fukt.bsnet.se</email>
29
<email>teddy@recompile.se</email>
34
<holder>Teddy Hogeborn & Björn Påhlsson</holder>
46
<holder>Teddy Hogeborn</holder>
47
<holder>Björn Påhlsson</holder>
38
This manual page is free software: you can redistribute it
39
and/or modify it under the terms of the GNU General Public
40
License as published by the Free Software Foundation,
41
either version 3 of the License, or (at your option) any
46
This manual page is distributed in the hope that it will
47
be useful, but WITHOUT ANY WARRANTY; without even the
48
implied warranty of MERCHANTABILITY or FITNESS FOR A
49
PARTICULAR PURPOSE. See the GNU General Public License
54
You should have received a copy of the GNU General Public
55
License along with this program; If not, see
56
<ulink url="http://www.gnu.org/licenses/"/>.
49
<xi:include href="../legalnotice.xml"/>
62
53
<refentrytitle>&COMMANDNAME;</refentrytitle>
63
54
<manvolnum>8mandos</manvolnum>
67
58
<refname><command>&COMMANDNAME;</command></refname>
69
Passprompt for luks during boot sequence
59
<refpurpose>Prompt for a password and output it.</refpurpose>
75
64
<command>&COMMANDNAME;</command>
76
<arg choice='opt'>--prefix<arg choice='plain'>PREFIX</arg></arg>
77
<arg choice='opt'>--debug</arg>
80
<command>&COMMANDNAME;</command>
81
<arg choice='plain'>--help</arg>
84
<command>&COMMANDNAME;</command>
85
<arg choice='plain'>--usage</arg>
88
<command>&COMMANDNAME;</command>
89
<arg choice='plain'>--version</arg>
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>
93
97
<refsect1 id="description">
94
98
<title>DESCRIPTION</title>
96
<command>&COMMANDNAME;</command> is a terminal program that ask for
97
passwords during boot sequence. It is a plugin to
98
<firstterm>mandos</firstterm>, and is used as a fallback and
99
alternative to retriving passwords from a mandos server. During
100
boot sequence the user is prompted for the disk password, and
101
when a password is given it then gets forwarded to
102
<acronym>LUKS</acronym>.
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.
106
127
<refsect1 id="options">
107
128
<title>OPTIONS</title>
109
Commonly not invoked as command lines but from configuration
110
file of plugin runner.
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
115
<term><literal>-p</literal>, <literal>--prefix=<replaceable>PREFIX
116
</replaceable></literal></term>
119
Prefix used before the passprompt
125
<term><literal>--debug</literal></term>
134
<term><literal>-?</literal>, <literal>--help</literal></term>
143
<term><literal>--usage</literal></term>
146
Gives a short usage message
152
<term><literal>-V</literal>, <literal>--version</literal></term>
155
Prints the program version
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.
162
206
<refsect1 id="exit_status">
163
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.
168
216
<refsect1 id="environment">
169
217
<title>ENVIRONMENT</title>
174
<refsect1 id="files">
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.
180
246
<refsect1 id="bugs">
181
247
<title>BUGS</title>
248
<xi:include href="../bugs.xml"/>
186
251
<refsect1 id="example">
187
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>
192
291
<refsect1 id="security">
193
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
198
316
<refsect1 id="see_also">
199
317
<title>SEE ALSO</title>
201
<citerefentry><refentrytitle>mandos</refentrytitle>
202
<manvolnum>8</manvolnum></citerefentry>, <citerefentry>
203
<refentrytitle>plugin-runner</refentrytitle>
204
<manvolnum>8mandos</manvolnum></citerefentry> and <citerefentry>
205
<refentrytitle>password-request</refentrytitle>
206
<manvolnum>8mandos</manvolnum></citerefentry>
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
