/mandos/release

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

« back to all changes in this revision

Viewing changes to plugins.d/plymouth.xml

  • Committer: Teddy Hogeborn
  • Date: 2024-09-08 07:15:13 UTC
  • mto: This revision was merged to the branch mainline in revision 410.
  • Revision ID: teddy@recompile.se-20240908071513-2jnx7ja8hlct42hl
Minor fix for manual Makefile uninstallations

If the Mandos systemd unit file was not installed, it was still
removed by the "purge-server" target.  If systemd is not installed,
this could mean removal of "mandos.service" from the root directory.

(Note: this was *not* used by the Debian package as a method of
uninstallation; this was only ever done by the Makefile if "make
purge-server" was called by hand.  And a "mandos.service" file was
presumably also unlikely to exist in the root directory.)

* Makefile (purge-server): Only remove systemd service file
  "mandos.service" if the same conditions exist which permitted its
  initial installation in the "install-server" target.

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: -->