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 "usplash">
5
<!ENTITY TIMESTAMP "2012-01-01">
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>
38
<holder>Teddy Hogeborn</holder>
39
<holder>Björn Påhlsson</holder>
41
<xi:include href="../legalnotice.xml"/>
45
<refentrytitle>&COMMANDNAME;</refentrytitle>
46
<manvolnum>8mandos</manvolnum>
50
<refname><command>&COMMANDNAME;</command></refname>
51
<refpurpose>Mandos plugin to use usplash to get a
52
password.</refpurpose>
57
<command>&COMMANDNAME;</command>
61
<refsect1 id="description">
62
<title>DESCRIPTION</title>
64
This program prompts for a password using <citerefentry>
65
<refentrytitle>usplash</refentrytitle><manvolnum>8</manvolnum>
66
</citerefentry> and outputs any given password to standard
67
output. If no <citerefentry><refentrytitle
68
>usplash</refentrytitle><manvolnum>8</manvolnum></citerefentry>
69
process can be found, this program will immediately exit with an
70
exit code indicating failure.
73
This program is not very useful on its own. This program is
74
really meant to run as a plugin in the <application
75
>Mandos</application> client-side system, where it is used as a
76
fallback and alternative to retrieving passwords from a
77
<application >Mandos</application> server.
80
If this program is killed (presumably by
81
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
82
<manvolnum>8mandos</manvolnum></citerefentry> because some other
83
plugin provided the password), it cannot tell <citerefentry>
84
<refentrytitle>usplash</refentrytitle><manvolnum>8</manvolnum>
85
</citerefentry> to abort requesting a password, because
86
<citerefentry><refentrytitle>usplash</refentrytitle>
87
<manvolnum>8</manvolnum></citerefentry> does not support this.
88
Therefore, this program will then <emphasis>kill</emphasis> the
89
running <citerefentry><refentrytitle>usplash</refentrytitle>
90
<manvolnum>8</manvolnum></citerefentry> process and start a
91
<emphasis>new</emphasis> one using the same command line
92
arguments as the old one was using.
96
<refsect1 id="options">
97
<title>OPTIONS</title>
99
This program takes no options.
103
<refsect1 id="exit_status">
104
<title>EXIT STATUS</title>
106
If exit status is 0, the output from the program is the password
107
as it was read. Otherwise, if exit status is other than 0, the
108
program was interrupted or encountered an error, and any output
109
so far could be corrupt and/or truncated, and should therefore
114
<refsect1 id="environment">
115
<title>ENVIRONMENT</title>
118
<term><envar>cryptsource</envar></term>
119
<term><envar>crypttarget</envar></term>
122
If set, these environment variables will be assumed to
123
contain the source device name and the target device
124
mapper name, respectively, and will be shown as part of
128
These variables will normally be inherited from
129
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
130
<manvolnum>8mandos</manvolnum></citerefentry>, which will
131
normally have inherited them from
132
<filename>/scripts/local-top/cryptroot</filename> in the
133
initial <acronym>RAM</acronym> disk environment, which will
134
have set them from parsing kernel arguments and
135
<filename>/conf/conf.d/cryptroot</filename> (also in the
136
initial RAM disk environment), which in turn will have been
137
created when the initial RAM disk image was created by
139
>/usr/share/initramfs-tools/hooks/cryptroot</filename>, by
140
extracting the information of the root file system from
141
<filename >/etc/crypttab</filename>.
144
This behavior is meant to exactly mirror the behavior of
145
<command>askpass</command>, the default password prompter.
152
<refsect1 id="files">
156
<term><filename>/dev/.initramfs/usplash_fifo</filename></term>
159
This is the <acronym>FIFO</acronym> to where this program
160
will write the commands for <citerefentry><refentrytitle
161
>usplash</refentrytitle><manvolnum>8</manvolnum>
162
</citerefentry>. See <citerefentry><refentrytitle
163
>fifo</refentrytitle><manvolnum>7</manvolnum>
169
<term><filename>/dev/.initramfs/usplash_outfifo</filename></term>
172
This is the <acronym>FIFO</acronym> where this program
173
will read the password from <citerefentry><refentrytitle
174
>usplash</refentrytitle><manvolnum>8</manvolnum>
175
</citerefentry>. See <citerefentry><refentrytitle
176
>fifo</refentrytitle><manvolnum>7</manvolnum>
182
<term><filename class="directory">/proc</filename></term>
185
To find the running <citerefentry><refentrytitle
186
>usplash</refentrytitle><manvolnum>8</manvolnum>
187
</citerefentry>, this directory will be searched for
188
numeric entries which will be assumed to be directories.
189
In all those directories, the <filename>exe</filename> and
190
<filename>cmdline</filename> entries will be used to
191
determine the name of the running binary, effective user
192
and group <abbrev>ID</abbrev>, and the command line
193
arguments. See <citerefentry><refentrytitle
194
>proc</refentrytitle><manvolnum>5</manvolnum>
200
<term><filename>/sbin/usplash</filename></term>
203
This is the name of the binary which will be searched for
204
in the process list. See <citerefentry><refentrytitle
205
>usplash</refentrytitle><manvolnum>8</manvolnum>
216
Killing <citerefentry><refentrytitle>usplash</refentrytitle>
217
<manvolnum>8</manvolnum></citerefentry> and starting a new one
218
is ugly, but necessary as long as it does not support aborting a
223
<refsect1 id="example">
224
<title>EXAMPLE</title>
226
Note that normally, this program will not be invoked directly,
227
but instead started by the Mandos <citerefentry><refentrytitle
228
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
233
This program takes no options.
236
<userinput>&COMMANDNAME;</userinput>
241
<refsect1 id="security">
242
<title>SECURITY</title>
244
If this program is killed by a signal, it will kill the process
245
<abbrev>ID</abbrev> which at the start of this program was
246
determined to run <citerefentry><refentrytitle
247
>usplash</refentrytitle><manvolnum>8</manvolnum></citerefentry>
248
as root (see also <xref linkend="files"/>). There is a very
249
slight risk that, in the time between those events, that process
250
<abbrev>ID</abbrev> was freed and then taken up by another
251
process; the wrong process would then be killed. Now, this
252
program can only be killed by the user who started it; see
253
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
254
<manvolnum>8mandos</manvolnum></citerefentry>. This program
255
should therefore be started by a completely separate
256
non-privileged user, and no other programs should be allowed to
257
run as that special user. This means that it is not recommended
258
to use the user "nobody" to start this program, as other
259
possibly less trusted programs could be running as "nobody", and
260
they would then be able to kill this program, triggering the
261
killing of the process <abbrev>ID</abbrev> which may or may not
262
be <citerefentry><refentrytitle>usplash</refentrytitle>
263
<manvolnum>8</manvolnum></citerefentry>.
266
The only other thing that could be considered worthy of note is
267
this: This program is meant to be run by <citerefentry>
268
<refentrytitle>plugin-runner</refentrytitle><manvolnum
269
>8mandos</manvolnum></citerefentry>, and will, when run
270
standalone, outside, in a normal environment, immediately output
271
on its standard output any presumably secret password it just
272
received. Therefore, when running this program standalone
273
(which should never normally be done), take care not to type in
274
any real secret password by force of habit, since it would then
275
immediately be shown as output.
279
<refsect1 id="see_also">
280
<title>SEE ALSO</title>
282
<citerefentry><refentrytitle>intro</refentrytitle>
283
<manvolnum>8mandos</manvolnum></citerefentry>,
284
<citerefentry><refentrytitle>crypttab</refentrytitle>
285
<manvolnum>5</manvolnum></citerefentry>,
286
<citerefentry><refentrytitle>fifo</refentrytitle>
287
<manvolnum>7</manvolnum></citerefentry>,
288
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
289
<manvolnum>8mandos</manvolnum></citerefentry>,
290
<citerefentry><refentrytitle>proc</refentrytitle>
291
<manvolnum>5</manvolnum></citerefentry>,
292
<citerefentry><refentrytitle>usplash</refentrytitle>
293
<manvolnum>8</manvolnum></citerefentry>
297
<!-- Local Variables: -->
298
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
299
<!-- time-stamp-end: "[\"']>" -->
300
<!-- time-stamp-format: "%:y-%02m-%02d" -->
added
removed
plugins.d/usplash.xml
