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

  • Committer: Teddy Hogeborn
  • Date: 2019-08-24 14:46:13 UTC
  • mto: This revision was merged to the branch mainline in revision 392.
  • Revision ID: teddy@recompile.se-20190824144613-z46mn4m8v5x2ifnj
Server: Show Python warnings

* mandos: Show Python warnings, and use the logging system to do it.

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