/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release
237.7.675 by Teddy Hogeborn
Add dracut(8) support
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: -->