/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 dracut-module/password-agent.xml

  • Committer: Teddy Hogeborn
  • Date: 2019-07-15 01:59:36 UTC
  • Revision ID: teddy@recompile.se-20190715015936-09xieyg8ogdxvoi2
Debian package change: Add autopkgtest support

* Makefile (check): Run a few more superficial tests.
  (debian/control/[Source: mandos]/Testsuite): New; set to
                                               "autopkgtest".
  (debian/tests/control): New.

Show diffs side-by-side

added added

removed removed

Lines of Context:
dracut-module/password-agent.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 "password-agent">
5
 
<!ENTITY TIMESTAMP "2019-07-24">
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>2019</year>
35
 
      <holder>Teddy Hogeborn</holder>
36
 
      <holder>Björn Påhlsson</holder>
37
 
    </copyright>
38
 
    <xi:include href="../legalnotice.xml"/>
39
 
  </refentryinfo>
40
 
 
41
 
  <refmeta>
42
 
    <refentrytitle>&COMMANDNAME;</refentrytitle>
43
 
    <manvolnum>8mandos</manvolnum>
44
 
  </refmeta>
45
 
 
46
 
  <refnamediv>
47
 
    <refname><command>&COMMANDNAME;</command></refname>
48
 
    <refpurpose>
49
 
      Run Mandos client as a systemd password agent.
50
 
    </refpurpose>
51
 
  </refnamediv>
52
 
 
53
 
  <refsynopsisdiv>
54
 
    <cmdsynopsis>
55
 
      <command>&COMMANDNAME;</command>
56
 
      <arg><option>--agent-directory=<replaceable
57
 
      >DIRECTORY</replaceable></option></arg>
58
 
      <sbr/>
59
 
      <arg><option>--helper-directory=<replaceable
60
 
      >DIRECTORY</replaceable></option></arg>
61
 
      <sbr/>
62
 
      <!-- <arg><option>-\-plugin-helper-dir=<replaceable -->
63
 
      <!-- >DIRECTORY</replaceable></option></arg> -->
64
 
      <!-- <sbr/> -->
65
 
      <arg><option>--user=<replaceable
66
 
      >USERID</replaceable></option></arg>
67
 
      <sbr/>
68
 
      <!-- <arg><option>-\-userid=<replaceable -->
69
 
      <!-- >ID</replaceable></option></arg> -->
70
 
      <!-- <sbr/> -->
71
 
      <arg><option>--group=<replaceable
72
 
      >GROUPID</replaceable></option></arg>
73
 
      <sbr/>
74
 
      <!-- <arg><option>-\-groupid=<replaceable -->
75
 
      <!-- >ID</replaceable></option></arg> -->
76
 
      <!-- <sbr/> -->
77
 
      <arg>--</arg>
78
 
      <arg>
79
 
        <replaceable>MANDOS_CLIENT</replaceable>
80
 
        <group rep="repeat">
81
 
          <arg choice="plain"><replaceable>OPTIONS</replaceable></arg>
82
 
        </group>
83
 
      </arg>
84
 
    </cmdsynopsis>
85
 
    <cmdsynopsis>
86
 
      <command>&COMMANDNAME;</command>
87
 
      <arg choice="plain"><option>--test</option></arg>
88
 
    </cmdsynopsis>
89
 
    <cmdsynopsis>
90
 
      <command>&COMMANDNAME;</command>
91
 
      <group choice="req">
92
 
        <arg choice="plain"><option>--help</option></arg>
93
 
        <arg choice="plain"><option>-?</option></arg>
94
 
      </group>
95
 
    </cmdsynopsis>
96
 
    <cmdsynopsis>
97
 
      <command>&COMMANDNAME;</command>
98
 
      <arg choice="plain"><option>--usage</option></arg>
99
 
    </cmdsynopsis>
100
 
    <cmdsynopsis>
101
 
      <command>&COMMANDNAME;</command>
102
 
      <group choice="req">
103
 
        <arg choice="plain"><option>--version</option></arg>
104
 
        <arg choice="plain"><option>-V</option></arg>
105
 
      </group>
106
 
    </cmdsynopsis>
107
 
  </refsynopsisdiv>
108
 
 
109
 
  <refsect1 id="description">
110
 
    <title>DESCRIPTION</title>
111
 
    <para>
112
 
      <command>&COMMANDNAME;</command> is a program which is meant to
113
 
      be a <citerefentry><refentrytitle>systemd</refentrytitle>
114
 
      <manvolnum>1</manvolnum></citerefentry> <quote>Password
115
 
      Agent</quote> (See <ulink
116
 
      url="https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents/"
117
 
      >Password Agents</ulink>).  The aim of this program is therefore
118
 
      to acquire and then send a password to some other program which
119
 
      will use the password to unlock the encrypted root disk.
120
 
    </para>
121
 
    <para>
122
 
      This program is not meant to be invoked directly, but can be in
123
 
      order to test it.
124
 
    </para>
125
 
  </refsect1>
126
 
 
127
 
  <refsect1 id="purpose">
128
 
    <title>PURPOSE</title>
129
 
    <para>
130
 
      The purpose of this is to enable <emphasis>remote and unattended
131
 
      rebooting</emphasis> of client host computer with an
132
 
      <emphasis>encrypted root file system</emphasis>.  See <xref
133
 
      linkend="overview"/> for details.
134
 
    </para>
135
 
  </refsect1>
136
 
 
137
 
  <refsect1>
138
 
    <title>OPTIONS</title>
139
 
    <variablelist>
140
 
 
141
 
      <varlistentry>
142
 
        <term><option>--agent-directory
143
 
        <replaceable>DIRECTORY</replaceable></option></term>
144
 
        <listitem>
145
 
          <para>
146
 
            Specify a different agent directory.  The default is
147
 
            <quote><filename class="directory"
148
 
            >/run/systemd/ask-password</filename ></quote> as per the
149
 
            <ulink
150
 
            url="https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents/"
151
 
            >Password Agents</ulink> specification.
152
 
          </para>
153
 
        </listitem>
154
 
      </varlistentry>
155
 
 
156
 
      <varlistentry>
157
 
        <term><option>--helper-directory
158
 
        <replaceable>DIRECTORY</replaceable></option></term>
159
 
        <listitem>
160
 
          <para>
161
 
            Specify a different helper directory.  The default is
162
 
            <quote><filename class="directory"
163
 
                             >/lib/mandos/plugin-helpers</filename
164
 
                             ></quote>, which
165
 
            will exist in the initial <acronym>RAM</acronym> disk
166
 
            environment.  (This will simply be passed to the
167
 
            <replaceable>MANDOS_CLIENT</replaceable> program via the
168
 
            <envar>MANDOSPLUGINHELPERDIR</envar> environment variable.
169
 
            See
170
 
            <citerefentry><refentrytitle>mandos-client</refentrytitle
171
 
            ><manvolnum>8mandos</manvolnum></citerefentry>.)
172
 
          </para>
173
 
        </listitem>
174
 
      </varlistentry>
175
 
 
176
 
      <varlistentry>
177
 
        <term><option>--user
178
 
        <replaceable>USERID</replaceable></option></term>
179
 
        <listitem>
180
 
          <para>
181
 
            Change real user ID to <replaceable>USERID</replaceable>
182
 
            when running <replaceable>MANDOS_CLIENT</replaceable>.
183
 
            The default is 65534.  <emphasis>Note:</emphasis> This
184
 
            must be a number, not a name.
185
 
          </para>
186
 
        </listitem>
187
 
      </varlistentry>
188
 
 
189
 
      <varlistentry>
190
 
        <term><option>--group
191
 
        <replaceable>GROUPID</replaceable></option></term>
192
 
        <listitem>
193
 
          <para>
194
 
            Change real group ID to <replaceable>GROUPID</replaceable>
195
 
            when running <replaceable>MANDOS_CLIENT</replaceable>.
196
 
            The default is 65534.  <emphasis>Note:</emphasis> This
197
 
            must be a number, not a name.
198
 
          </para>
199
 
        </listitem>
200
 
      </varlistentry>
201
 
 
202
 
      <varlistentry>
203
 
        <term><replaceable>MANDOS_CLIENT</replaceable></term>
204
 
        <listitem>
205
 
          <para>
206
 
            This specifies the file name for
207
 
            <citerefentry><refentrytitle>mandos-client</refentrytitle
208
 
            ><manvolnum>8mandos</manvolnum></citerefentry>.  If the
209
 
            <quote><option>--</option></quote> option is given, any
210
 
            following options are passed to the <replaceable
211
 
            >MANDOS_CLIENT</replaceable> program.  The default is
212
 
            <quote><filename
213
 
            >/lib/mandos/plugins.d/mandos-client</filename ></quote>
214
 
            (which is the correct location for the initial
215
 
            <acronym>RAM</acronym> disk environment) without any
216
 
            options.
217
 
          </para>
218
 
        </listitem>
219
 
      </varlistentry>
220
 
 
221
 
      <varlistentry>
222
 
        <term><option>--help</option></term>
223
 
        <term><option>-?</option></term>
224
 
        <listitem>
225
 
          <para>
226
 
            Gives a help message about options and their meanings.
227
 
          </para>
228
 
        </listitem>
229
 
      </varlistentry>
230
 
 
231
 
      <varlistentry>
232
 
        <term><option>--test</option></term>
233
 
        <listitem>
234
 
          <para>
235
 
            Ignore normal operation; instead only run self-tests.
236
 
            Adding the <option>--help</option> option may show more
237
 
            options possible in combination with
238
 
            <option>--test</option>.
239
 
          </para>
240
 
        </listitem>
241
 
      </varlistentry>
242
 
 
243
 
      <varlistentry>
244
 
        <term><option>--usage</option></term>
245
 
        <listitem>
246
 
          <para>
247
 
            Gives a short usage message.
248
 
          </para>
249
 
        </listitem>
250
 
      </varlistentry>
251
 
 
252
 
      <varlistentry>
253
 
        <term><option>--version</option></term>
254
 
        <term><option>-V</option></term>
255
 
        <listitem>
256
 
          <para>
257
 
            Prints the program version.
258
 
          </para>
259
 
        </listitem>
260
 
      </varlistentry>
261
 
    </variablelist>
262
 
  </refsect1>
263
 
 
264
 
  <refsect1 id="overview">
265
 
    <title>OVERVIEW</title>
266
 
    <xi:include href="../overview.xml"/>
267
 
    <para>
268
 
      This program, &COMMANDNAME;, will run on the client side in the
269
 
      initial <acronym>RAM</acronym> disk environment, and is
270
 
      responsible for getting a password from the Mandos client
271
 
      program itself, and to send that password to whatever is
272
 
      currently asking for a password using the systemd <ulink
273
 
      url="https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents/"
274
 
      >Password Agents</ulink> mechanism.
275
 
    </para>
276
 
    <para>To accomplish this, &COMMANDNAME; runs the
277
 
    <command>mandos-client</command> program (which is the actual
278
 
    client program communicating with the Mandos server) or,
279
 
    alternatively, any executable file specified as
280
 
    <replaceable>MANDOS_CLIENT</replaceable>, and, as soon as a
281
 
    password is acquired from the
282
 
    <replaceable>MANDOS_CLIENT</replaceable> program, sends that
283
 
    password (as per the <ulink
284
 
    url="https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents/"
285
 
    >Password Agents</ulink> specification) to all currently
286
 
    unanswered password questions.
287
 
    </para>
288
 
    <para>
289
 
      This program should be started (normally as a systemd service,
290
 
      which in turn is normally started by a <citerefentry
291
 
      ><refentrytitle>systemd.path</refentrytitle>
292
 
      <manvolnum>5</manvolnum></citerefentry> file) as a reaction to
293
 
      files named <quote><filename>ask.<replaceable>xxxx</replaceable
294
 
      ></filename></quote> appearing in the agent directory
295
 
      <quote><filename
296
 
      class="directory">/run/systemd/ask-password</filename></quote>
297
 
      (or the directory specified by
298
 
      <option>--agent-directory</option>).
299
 
    </para>
300
 
  </refsect1>
301
 
 
302
 
  <refsect1 id="exit_status">
303
 
    <title>EXIT STATUS</title>
304
 
    <para>
305
 
      Exit status of this program is zero if no errors were
306
 
      encountered, and otherwise not.
307
 
    </para>
308
 
  </refsect1>
309
 
 
310
 
  <refsect1 id="environment">
311
 
    <title>ENVIRONMENT</title>
312
 
    <para>
313
 
      This program does not use any environment variables itself, it
314
 
      only passes on its environment to
315
 
      <replaceable>MANDOS_CLIENT</replaceable>.  Also, the
316
 
      <option>--helper-directory</option> option will affect the
317
 
      environment variable <envar>MANDOSPLUGINHELPERDIR</envar> for
318
 
      <replaceable>MANDOS_CLIENT</replaceable>.
319
 
    </para>
320
 
  </refsect1>
321
 
 
322
 
  <refsect1 id="files">
323
 
    <title>FILES</title>
324
 
    <para>
325
 
      <variablelist>
326
 
        <varlistentry>
327
 
          <term><filename class="directory"
328
 
                          >/run/systemd/ask-password</filename></term>
329
 
          <listitem>
330
 
            <para>
331
 
              The default directory to watch for password questions as
332
 
              per the <ulink
333
 
              url="https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents/"
334
 
              >Password Agents</ulink> specification; can be changed
335
 
              by the <option>--agent-directory</option> option.
336
 
            </para>
337
 
          </listitem>
338
 
        </varlistentry>
339
 
        <varlistentry>
340
 
          <term><filename class="directory"
341
 
                          >/lib/mandos/plugin-helpers</filename
342
 
                          ></term>
343
 
          <listitem>
344
 
            <para>
345
 
              The helper directory as supplied to
346
 
              <replaceable>MANDOS_CLIENT</replaceable> via the
347
 
              <envar>MANDOSPLUGINHELPERDIR</envar> environment
348
 
              variable; can be changed by the
349
 
              <option>--helper-directory</option> option.
350
 
            </para>
351
 
          </listitem>
352
 
        </varlistentry>
353
 
      </variablelist>
354
 
    </para>
355
 
  </refsect1>
356
 
 
357
 
  <refsect1 id="bugs">
358
 
    <title>BUGS</title>
359
 
    <xi:include href="../bugs.xml"/>
360
 
  </refsect1>
361
 
 
362
 
  <refsect1 id="examples">
363
 
    <title>EXAMPLE</title>
364
 
    <informalexample>
365
 
      <para>
366
 
        Normal invocation needs no options:
367
 
      </para>
368
 
      <para>
369
 
        <userinput>&COMMANDNAME;</userinput>
370
 
      </para>
371
 
    </informalexample>
372
 
    <informalexample>
373
 
      <para>
374
 
        Run an alternative <replaceable>MANDOS_CLIENT</replaceable>
375
 
        program::
376
 
      </para>
377
 
      <para>
378
 
        <userinput>&COMMANDNAME; /usr/local/sbin/alternate</userinput>
379
 
      </para>
380
 
    </informalexample>
381
 
    <informalexample>
382
 
      <para>
383
 
        Use alternative locations for the helper directory and the
384
 
        Mandos client, and add extra options suitable for running in
385
 
        the normal file system:
386
 
      </para>
387
 
      <para>
388
 
        
389
 
        <!-- do not wrap this line -->
390
 
        <userinput>&COMMANDNAME; --helper-directory=/usr/lib/x86_64-linux-gnu/mandos/plugin-helpers -- /usr/lib/x86_64-linux-gnu/mandos/plugins.d/mandos-client --pubkey=/etc/keys/mandos/pubkey.txt --seckey=/etc/keys/mandos/seckey.txt --tls-pubkey=/etc/keys/mandos/tls-pubkey.pem --tls-privkey=/etc/keys/mandos/tls-privkey.pem</userinput>
391
 
        
392
 
      </para>
393
 
    </informalexample>
394
 
    <informalexample>
395
 
      <para>
396
 
        Use the default location for
397
 
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
398
 
        <manvolnum>8mandos</manvolnum></citerefentry>, but add many
399
 
        options to it:
400
 
      </para>
401
 
      <para>
402
 
 
403
 
<!-- do not wrap this line -->
404
 
<userinput>&COMMANDNAME; -- /lib/mandos/mandos-client --pubkey=/etc/mandos/keys/pubkey.txt --seckey=/etc/mandos/keys/seckey.txt --tls-pubkey=/etc/mandos/keys/tls-pubkey.pem --tls-privkey=/etc/mandos/keys/tls-privkey.pem</userinput>
405
 
 
406
 
      </para>
407
 
    </informalexample>
408
 
    <informalexample>
409
 
      <para>
410
 
        Only run the self-tests:
411
 
      </para>
412
 
      <para>
413
 
        <userinput>&COMMANDNAME; --test</userinput>
414
 
      </para>
415
 
    </informalexample>
416
 
  </refsect1>
417
 
  <refsect1 id="security">
418
 
    <title>SECURITY</title>
419
 
    <para>
420
 
      This program will need to run as the root user in order to read
421
 
      the agent directory and the <quote><filename
422
 
      >ask.<replaceable>xxxx</replaceable></filename></quote> files
423
 
      there, and will, when starting the Mandos client program,
424
 
      require the ability to set the <quote>real</quote> user and
425
 
      group ids to another user, by default user and group 65534,
426
 
      which are assumed to be non-privileged.  This is done in order
427
 
      to match the expectations of <citerefentry><refentrytitle
428
 
      >mandos-client</refentrytitle><manvolnum>8mandos</manvolnum
429
 
      ></citerefentry>, which assumes that its executable file is
430
 
      owned by the root user and also has the set-user-ID bit set (see
431
 
      <citerefentry><refentrytitle>execve</refentrytitle><manvolnum
432
 
      >2</manvolnum></citerefentry>).
433
 
    </para>
434
 
  </refsect1>
435
 
 
436
 
  <refsect1 id="see_also">
437
 
    <title>SEE ALSO</title>
438
 
    <para>
439
 
      <citerefentry><refentrytitle>intro</refentrytitle>
440
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
441
 
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
442
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
443
 
      <citerefentry><refentrytitle>systemd</refentrytitle>
444
 
      <manvolnum>1</manvolnum></citerefentry>,
445
 
    </para>
446
 
    <variablelist>
447
 
      <varlistentry>
448
 
        <term>
449
 
          <ulink
450
 
              url="https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents/"
451
 
              >Password Agents</ulink>
452
 
        </term>
453
 
        <listitem>
454
 
          <para>
455
 
            The specification for systemd <quote>Password
456
 
            Agent</quote> programs, which
457
 
            <command>&COMMANDNAME;</command> follows.
458
 
          </para>
459
 
        </listitem>
460
 
      </varlistentry>
461
 
    </variablelist>
462
 
  </refsect1>
463
 
 
464
 
</refentry>
465
 
<!-- Local Variables: -->
466
 
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
467
 
<!-- time-stamp-end: "[\"']>" -->
468
 
<!-- time-stamp-format: "%:y-%02m-%02d" -->
469
 
<!-- End: -->