/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
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">
237.7.675 by Teddy Hogeborn
Add dracut(8) support
5
<!ENTITY TIMESTAMP "2019-07-27">
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
6
<!ENTITY % common SYSTEM "../common.ent">
7
%common;
8
]>
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
  <refentryinfo>
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>
17
    <authorgroup>
18
      <author>
19
	<firstname>Björn</firstname>
20
	<surname>Påhlsson</surname>
21
	<address>
237.11.2 by Teddy Hogeborn
Change "fukt.bsnet.se" to "recompile.se" throughout.
22
	  <email>belorn@recompile.se</email>
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
23
	</address>
24
      </author>
25
      <author>
26
	<firstname>Teddy</firstname>
27
	<surname>Hogeborn</surname>
28
	<address>
237.11.2 by Teddy Hogeborn
Change "fukt.bsnet.se" to "recompile.se" throughout.
29
	  <email>teddy@recompile.se</email>
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
30
	</address>
31
      </author>
32
    </authorgroup>
33
    <copyright>
237.2.207 by Teddy Hogeborn
Update copyright year to "2010" wherever appropriate.
34
      <year>2010</year>
237.7.14 by Teddy Hogeborn
Update copyright year to "2011" wherever appropriate.
35
      <year>2011</year>
237.7.92 by Teddy Hogeborn
Updated year in copyright notices.
36
      <year>2012</year>
237.7.326 by Teddy Hogeborn
Update copyright year.
37
      <year>2013</year>
38
      <year>2014</year>
39
      <year>2015</year>
237.7.355 by Teddy Hogeborn
Update copyright year.
40
      <year>2016</year>
237.7.447 by Teddy Hogeborn
Update copyright year to 2017
41
      <year>2017</year>
237.7.471 by Teddy Hogeborn
Update copyright year to 2018
42
      <year>2018</year>
237.7.517 by Teddy Hogeborn
Update copyright year to 2019
43
      <year>2019</year>
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
44
      <holder>Teddy Hogeborn</holder>
45
      <holder>Björn Påhlsson</holder>
46
    </copyright>
47
    <xi:include href="../legalnotice.xml"/>
48
  </refentryinfo>
49
  
50
  <refmeta>
51
    <refentrytitle>&COMMANDNAME;</refentrytitle>
52
    <manvolnum>8mandos</manvolnum>
53
  </refmeta>
54
  
55
  <refnamediv>
56
    <refname><command>&COMMANDNAME;</command></refname>
57
    <refpurpose>Mandos plugin to use plymouth to get a
58
    password.</refpurpose>
59
  </refnamediv>
60
  
61
  <refsynopsisdiv>
62
    <cmdsynopsis>
63
      <command>&COMMANDNAME;</command>
237.7.675 by Teddy Hogeborn
Add dracut(8) support
64
      <arg choice="opt">
65
	<option>--prompt <replaceable>PROMPT</replaceable></option>
66
      </arg>
67
      <arg><option>--debug</option></arg>
68
    </cmdsynopsis>
69
    <cmdsynopsis>
70
      <command>&COMMANDNAME;</command>
71
      <group choice="req">
72
	<arg choice="plain"><option>--help</option></arg>
73
	<arg choice="plain"><option>-?</option></arg>
74
      </group>
75
    </cmdsynopsis>
76
    <cmdsynopsis>
77
      <command>&COMMANDNAME;</command>
78
      <arg choice="plain"><option>--usage</option></arg>
79
    </cmdsynopsis>
80
    <cmdsynopsis>
81
      <command>&COMMANDNAME;</command>
82
      <group choice="req">
83
	<arg choice="plain"><option>--version</option></arg>
84
	<arg choice="plain"><option>-V</option></arg>
85
      </group>
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
86
    </cmdsynopsis>
87
  </refsynopsisdiv>
88
  
89
  <refsect1 id="description">
90
    <title>DESCRIPTION</title>
91
    <para>
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.
99
    </para>
100
    <para>
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.
106
    </para>
107
    <para>
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.
121
    </para>
122
  </refsect1>
123
  
124
  <refsect1 id="options">
125
    <title>OPTIONS</title>
126
    <para>
237.7.675 by Teddy Hogeborn
Add dracut(8) support
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
133
      directly.
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
134
    </para>
237.7.675 by Teddy Hogeborn
Add dracut(8) support
135
    
136
    <variablelist>
137
      <varlistentry>
138
	<term><option>--prompt=<replaceable
139
	>PROMPT</replaceable></option></term>
140
	<listitem>
141
	  <para>
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.
145
	  </para>
146
	</listitem>
147
      </varlistentry>
148
      
149
      <varlistentry>
150
	<term><option>--debug</option></term>
151
	<listitem>
152
	  <para>
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.
156
	  </para>
157
	</listitem>
158
      </varlistentry>
159
      
160
      <varlistentry>
161
	<term><option>--help</option></term>
162
	<term><option>-?</option></term>
163
	<listitem>
164
	  <para>
165
	    Gives a help message about options and their meanings.
166
	  </para>
167
	</listitem>
168
      </varlistentry>
169
      
170
      <varlistentry>
171
	<term><option>--usage</option></term>
172
	<listitem>
173
	  <para>
174
	    Gives a short usage message.
175
	  </para>
176
	</listitem>
177
      </varlistentry>
178
      
179
      <varlistentry>
180
	<term><option>--version</option></term>
181
	<term><option>-V</option></term>
182
	<listitem>
183
	  <para>
184
	    Prints the program version.
185
	  </para>
186
	</listitem>
187
      </varlistentry>
188
    </variablelist>
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
189
  </refsect1>
190
  
191
  <refsect1 id="exit_status">
192
    <title>EXIT STATUS</title>
193
    <para>
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
198
      be ignored.
199
    </para>
200
  </refsect1>
201
  
202
  <refsect1 id="environment">
203
    <title>ENVIRONMENT</title>
204
    <variablelist>
205
      <varlistentry>
206
	<term><envar>cryptsource</envar></term>
207
	<term><envar>crypttarget</envar></term>
208
	<listitem>
209
	  <para>
237.7.675 by Teddy Hogeborn
Add dracut(8) support
210
	    If set, and if the <option>--prompt</option> option is not
211
	    used, these environment variables will be assumed to
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
212
	    contain the source device name and the target device
213
	    mapper name, respectively, and will be shown as part of
214
	    the prompt.
215
	</para>
216
	<para>
217
	  These variables will normally be inherited from
218
	  <citerefentry><refentrytitle>plugin-runner</refentrytitle>
237.7.675 by Teddy Hogeborn
Add dracut(8) support
219
	  <manvolnum>8mandos</manvolnum></citerefentry>, which might
220
	  have in turn inherited them from its calling process.
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
221
	</para>
222
	<para>
223
	  This behavior is meant to exactly mirror the behavior of
237.7.675 by Teddy Hogeborn
Add dracut(8) support
224
	  <command>askpass</command>, the default password prompter
225
	  from initramfs-tools.
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
226
	</para>
227
	</listitem>
228
      </varlistentry>
229
    </variablelist>
230
  </refsect1>
231
  
232
  <refsect1 id="files">
233
    <title>FILES</title>
234
    <variablelist>
235
      <varlistentry>
236
	<term><filename>/bin/plymouth</filename></term>
237
	<listitem>
238
	  <para>
239
	    This is the command run to retrieve a password from
240
	    <citerefentry><refentrytitle>plymouth</refentrytitle>
241
	    <manvolnum>8</manvolnum></citerefentry>.
242
	  </para>
243
	</listitem>
244
      </varlistentry>
245
      <varlistentry>
237.13.1 by teddy at bsnet
* plugins.d/mandos-client.c (SYNOPSIS, OPTIONS): Document
246
	<term><filename class="directory">/proc</filename></term>
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
247
	<listitem>
248
	  <para>
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>
259
	    </citerefentry>.
260
	  </para>
261
	</listitem>
262
      </varlistentry>
263
      <varlistentry>
264
	<term><filename>/sbin/plymouthd</filename></term>
265
	<listitem>
266
	  <para>
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>
270
	    </citerefentry>.
271
	  </para>
272
	</listitem>
273
      </varlistentry>
274
    </variablelist>
275
  </refsect1>
276
  
277
  <refsect1 id="bugs">
278
    <title>BUGS</title>
279
    <para>
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.
284
    </para>
237.7.369 by Teddy Hogeborn
Add bug reporting information to manual pages
285
    <xi:include href="../bugs.xml"/>
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
286
  </refsect1>
287
  
288
  <refsect1 id="example">
289
    <title>EXAMPLE</title>
290
    <para>
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>
294
      </citerefentry>.
295
    </para>
296
    <informalexample>
297
      <para>
237.7.675 by Teddy Hogeborn
Add dracut(8) support
298
	Normal invocation needs no options:
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
299
      </para>
300
      <para>
301
	<userinput>&COMMANDNAME;</userinput>
302
      </para>
303
    </informalexample>
237.7.675 by Teddy Hogeborn
Add dracut(8) support
304
    <informalexample>
305
      <para>
306
	Show a different prompt.
307
      </para>
308
      <para>
309
	<userinput>&COMMANDNAME; --prompt=Password</userinput>
310
      </para>
311
    </informalexample>
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
312
  </refsect1>
313
  
314
  <refsect1 id="security">
315
    <title>SECURITY</title>
316
    <para>
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>.
337
    </para>
338
    <para>
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.
349
    </para>
350
  </refsect1>
351
  
352
  <refsect1 id="see_also">
353
    <title>SEE ALSO</title>
354
    <para>
237.7.41 by Teddy Hogeborn
* Makefile (DOCS): Added "intro.8mandos".
355
      <citerefentry><refentrytitle>intro</refentrytitle>
356
      <manvolnum>8mandos</manvolnum></citerefentry>,
237.2.198 by teddy at bsnet
* Makefile (DOCS): Added "plymouth.8mandos".
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>
363
    </para>
364
  </refsect1>
365
</refentry>
366
<!-- Local Variables: -->
367
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
368
<!-- time-stamp-end: "[\"']>" -->
369
<!-- time-stamp-format: "%:y-%02m-%02d" -->
370
<!-- End: -->