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 "plymouth">
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>
44
<holder>Teddy Hogeborn</holder>
45
<holder>Björn Påhlsson</holder>
47
<xi:include href="../legalnotice.xml"/>
51
<refentrytitle>&COMMANDNAME;</refentrytitle>
52
<manvolnum>8mandos</manvolnum>
56
<refname><command>&COMMANDNAME;</command></refname>
57
<refpurpose>Mandos plugin to use plymouth to get a
58
password.</refpurpose>
63
<command>&COMMANDNAME;</command>
65
<option>--prompt <replaceable>PROMPT</replaceable></option>
67
<arg><option>--debug</option></arg>
70
<command>&COMMANDNAME;</command>
72
<arg choice="plain"><option>--help</option></arg>
73
<arg choice="plain"><option>-?</option></arg>
77
<command>&COMMANDNAME;</command>
78
<arg choice="plain"><option>--usage</option></arg>
81
<command>&COMMANDNAME;</command>
83
<arg choice="plain"><option>--version</option></arg>
84
<arg choice="plain"><option>-V</option></arg>
89
<refsect1 id="description">
90
<title>DESCRIPTION</title>
92
This program prompts for a password using <citerefentry>
93
<refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum>
94
</citerefentry> and outputs any given password to standard
95
output. If no <citerefentry><refentrytitle
96
>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>
97
process can be found, this program will immediately exit with an
98
exit code indicating failure.
101
This program is not very useful on its own. This program is
102
really meant to run as a plugin in the <application
103
>Mandos</application> client-side system, where it is used as a
104
fallback and alternative to retrieving passwords from a
105
<application >Mandos</application> server.
108
If this program is killed (presumably by
109
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
110
<manvolnum>8mandos</manvolnum></citerefentry> because some other
111
plugin provided the password), it cannot tell <citerefentry>
112
<refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum>
113
</citerefentry> to abort requesting a password, because
114
<citerefentry><refentrytitle>plymouth</refentrytitle>
115
<manvolnum>8</manvolnum></citerefentry> does not support this.
116
Therefore, this program will then <emphasis>kill</emphasis> the
117
running <citerefentry><refentrytitle>plymouth</refentrytitle>
118
<manvolnum>8</manvolnum></citerefentry> process and start a
119
<emphasis>new</emphasis> one using the same command line
120
arguments as the old one was using.
124
<refsect1 id="options">
125
<title>OPTIONS</title>
127
This program is commonly not invoked from the command line; it
128
is normally started by the <application>Mandos</application>
129
plugin runner, see <citerefentry><refentrytitle
130
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
131
</citerefentry>. Any command line options this program accepts
132
are therefore normally provided by the plugin runner, and not
138
<term><option>--prompt=<replaceable
139
>PROMPT</replaceable></option></term>
142
The password prompt. Note that using this option will
143
make this program ignore the <envar>cryptsource</envar>
144
and <envar>crypttarget</envar> environment variables.
150
<term><option>--debug</option></term>
153
Enable debug mode. This will enable a lot of output to
154
standard error about what the program is doing. The
155
program will still perform all other functions normally.
161
<term><option>--help</option></term>
162
<term><option>-?</option></term>
165
Gives a help message about options and their meanings.
171
<term><option>--usage</option></term>
174
Gives a short usage message.
180
<term><option>--version</option></term>
181
<term><option>-V</option></term>
184
Prints the program version.
191
<refsect1 id="exit_status">
192
<title>EXIT STATUS</title>
194
If exit status is 0, the output from the program is the password
195
as it was read. Otherwise, if exit status is other than 0, the
196
program was interrupted or encountered an error, and any output
197
so far could be corrupt and/or truncated, and should therefore
202
<refsect1 id="environment">
203
<title>ENVIRONMENT</title>
206
<term><envar>cryptsource</envar></term>
207
<term><envar>crypttarget</envar></term>
210
If set, and if the <option>--prompt</option> option is not
211
used, these environment variables will be assumed to
212
contain the source device name and the target device
213
mapper name, respectively, and will be shown as part of
217
These variables will normally be inherited from
218
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
219
<manvolnum>8mandos</manvolnum></citerefentry>, which might
220
have in turn inherited them from its calling process.
223
This behavior is meant to exactly mirror the behavior of
224
<command>askpass</command>, the default password prompter
225
from initramfs-tools.
232
<refsect1 id="files">
236
<term><filename>/bin/plymouth</filename></term>
239
This is the command run to retrieve a password from
240
<citerefentry><refentrytitle>plymouth</refentrytitle>
241
<manvolnum>8</manvolnum></citerefentry>.
246
<term><filename class="directory">/proc</filename></term>
249
To find the running <citerefentry><refentrytitle
250
>plymouth</refentrytitle><manvolnum>8</manvolnum>
251
</citerefentry>, this directory will be searched for
252
numeric entries which will be assumed to be directories.
253
In all those directories, the <filename>exe</filename> and
254
<filename>cmdline</filename> entries will be used to
255
determine the name of the running binary, effective user
256
and group <abbrev>ID</abbrev>, and the command line
257
arguments. See <citerefentry><refentrytitle
258
>proc</refentrytitle><manvolnum>5</manvolnum>
264
<term><filename>/sbin/plymouthd</filename></term>
267
This is the name of the binary which will be searched for
268
in the process list. See <citerefentry><refentrytitle
269
>plymouth</refentrytitle><manvolnum>8</manvolnum>
280
Killing the <citerefentry><refentrytitle
281
>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>
282
daemon and starting a new one is ugly, but necessary as long as
283
it does not support aborting a password request.
285
<xi:include href="../bugs.xml"/>
288
<refsect1 id="example">
289
<title>EXAMPLE</title>
291
Note that normally, this program will not be invoked directly,
292
but instead started by the Mandos <citerefentry><refentrytitle
293
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
298
Normal invocation needs no options:
301
<userinput>&COMMANDNAME;</userinput>
306
Show a different prompt.
309
<userinput>&COMMANDNAME; --prompt=Password</userinput>
314
<refsect1 id="security">
315
<title>SECURITY</title>
317
If this program is killed by a signal, it will kill the process
318
<abbrev>ID</abbrev> which at the start of this program was
319
determined to run <citerefentry><refentrytitle
320
>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>
321
as root (see also <xref linkend="files"/>). There is a very
322
slight risk that, in the time between those events, that process
323
<abbrev>ID</abbrev> was freed and then taken up by another
324
process; the wrong process would then be killed. Now, this
325
program can only be killed by the user who started it; see
326
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
327
<manvolnum>8mandos</manvolnum></citerefentry>. This program
328
should therefore be started by a completely separate
329
non-privileged user, and no other programs should be allowed to
330
run as that special user. This means that it is not recommended
331
to use the user "nobody" to start this program, as other
332
possibly less trusted programs could be running as "nobody", and
333
they would then be able to kill this program, triggering the
334
killing of the process <abbrev>ID</abbrev> which may or may not
335
be <citerefentry><refentrytitle>plymouth</refentrytitle>
336
<manvolnum>8</manvolnum></citerefentry>.
339
The only other thing that could be considered worthy of note is
340
this: This program is meant to be run by <citerefentry>
341
<refentrytitle>plugin-runner</refentrytitle><manvolnum
342
>8mandos</manvolnum></citerefentry>, and will, when run
343
standalone, outside, in a normal environment, immediately output
344
on its standard output any presumably secret password it just
345
received. Therefore, when running this program standalone
346
(which should never normally be done), take care not to type in
347
any real secret password by force of habit, since it would then
348
immediately be shown as output.
352
<refsect1 id="see_also">
353
<title>SEE ALSO</title>
355
<citerefentry><refentrytitle>intro</refentrytitle>
356
<manvolnum>8mandos</manvolnum></citerefentry>,
357
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
358
<manvolnum>8mandos</manvolnum></citerefentry>,
359
<citerefentry><refentrytitle>proc</refentrytitle>
360
<manvolnum>5</manvolnum></citerefentry>,
361
<citerefentry><refentrytitle>plymouth</refentrytitle>
362
<manvolnum>8</manvolnum></citerefentry>
366
<!-- Local Variables: -->
367
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
368
<!-- time-stamp-end: "[\"']>" -->
369
<!-- time-stamp-format: "%:y-%02m-%02d" -->
added
removed
plugins.d/plymouth.xml
