/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk

« back to all changes in this revision

Viewing changes to plugins.d/plymouth.xml

plugbasedclient
        Parse a single argument as a plus-separated list of options

Show diffs side-by-side

added added

removed removed

Lines of Context:
plugins.d/plymouth.xml
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">
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>
22
 
          <email>belorn@recompile.se</email>
23
 
        </address>
24
 
      </author>
25
 
      <author>
26
 
        <firstname>Teddy</firstname>
27
 
        <surname>Hogeborn</surname>
28
 
        <address>
29
 
          <email>teddy@recompile.se</email>
30
 
        </address>
31
 
      </author>
32
 
    </authorgroup>
33
 
    <copyright>
34
 
      <year>2010</year>
35
 
      <year>2011</year>
36
 
      <year>2012</year>
37
 
      <year>2013</year>
38
 
      <year>2014</year>
39
 
      <year>2015</year>
40
 
      <year>2016</year>
41
 
      <year>2017</year>
42
 
      <year>2018</year>
43
 
      <year>2019</year>
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>
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>
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>
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.
134
 
    </para>
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>
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>
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
214
 
            the prompt.
215
 
        </para>
216
 
        <para>
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.
221
 
        </para>
222
 
        <para>
223
 
          This behavior is meant to exactly mirror the behavior of
224
 
          <command>askpass</command>, the default password prompter
225
 
          from initramfs-tools.
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>
246
 
        <term><filename class="directory">/proc</filename></term>
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>
285
 
    <xi:include href="../bugs.xml"/>
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>
298
 
        Normal invocation needs no options:
299
 
      </para>
300
 
      <para>
301
 
        <userinput>&COMMANDNAME;</userinput>
302
 
      </para>
303
 
    </informalexample>
304
 
    <informalexample>
305
 
      <para>
306
 
        Show a different prompt.
307
 
      </para>
308
 
      <para>
309
 
        <userinput>&COMMANDNAME; --prompt=Password</userinput>
310
 
      </para>
311
 
    </informalexample>
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>
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>
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: -->