/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">
237.7.782 by Teddy Hogeborn
Update copyright year
5
<!ENTITY TIMESTAMP "2021-02-03">
237.7.675 by Teddy Hogeborn
Add dracut(8) support
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>
237.7.782 by Teddy Hogeborn
Update copyright year
35
      <year>2020</year>
237.7.675 by Teddy Hogeborn
Add dracut(8) support
36
      <holder>Teddy Hogeborn</holder>
37
      <holder>Björn Påhlsson</holder>
38
    </copyright>
39
    <xi:include href="../legalnotice.xml"/>
40
  </refentryinfo>
41
42
  <refmeta>
43
    <refentrytitle>&COMMANDNAME;</refentrytitle>
44
    <manvolnum>8mandos</manvolnum>
45
  </refmeta>
46
47
  <refnamediv>
48
    <refname><command>&COMMANDNAME;</command></refname>
49
    <refpurpose>
50
      Run Mandos client as a systemd password agent.
51
    </refpurpose>
52
  </refnamediv>
53
54
  <refsynopsisdiv>
55
    <cmdsynopsis>
56
      <command>&COMMANDNAME;</command>
57
      <arg><option>--agent-directory=<replaceable
58
      >DIRECTORY</replaceable></option></arg>
59
      <sbr/>
60
      <arg><option>--helper-directory=<replaceable
61
      >DIRECTORY</replaceable></option></arg>
62
      <sbr/>
63
      <!-- <arg><option>-\-plugin-helper-dir=<replaceable -->
64
      <!-- >DIRECTORY</replaceable></option></arg> -->
65
      <!-- <sbr/> -->
66
      <arg><option>--user=<replaceable
67
      >USERID</replaceable></option></arg>
68
      <sbr/>
69
      <!-- <arg><option>-\-userid=<replaceable -->
70
      <!-- >ID</replaceable></option></arg> -->
71
      <!-- <sbr/> -->
72
      <arg><option>--group=<replaceable
73
      >GROUPID</replaceable></option></arg>
74
      <sbr/>
75
      <!-- <arg><option>-\-groupid=<replaceable -->
76
      <!-- >ID</replaceable></option></arg> -->
77
      <!-- <sbr/> -->
78
      <arg>--</arg>
79
      <arg>
80
	<replaceable>MANDOS_CLIENT</replaceable>
81
	<group rep="repeat">
82
	  <arg choice="plain"><replaceable>OPTIONS</replaceable></arg>
83
	</group>
84
      </arg>
85
    </cmdsynopsis>
86
    <cmdsynopsis>
87
      <command>&COMMANDNAME;</command>
88
      <arg choice="plain"><option>--test</option></arg>
89
    </cmdsynopsis>
90
    <cmdsynopsis>
91
      <command>&COMMANDNAME;</command>
92
      <group choice="req">
93
	<arg choice="plain"><option>--help</option></arg>
94
	<arg choice="plain"><option>-?</option></arg>
95
      </group>
96
    </cmdsynopsis>
97
    <cmdsynopsis>
98
      <command>&COMMANDNAME;</command>
99
      <arg choice="plain"><option>--usage</option></arg>
100
    </cmdsynopsis>
101
    <cmdsynopsis>
102
      <command>&COMMANDNAME;</command>
103
      <group choice="req">
104
	<arg choice="plain"><option>--version</option></arg>
105
	<arg choice="plain"><option>-V</option></arg>
106
      </group>
107
    </cmdsynopsis>
108
  </refsynopsisdiv>
109
110
  <refsect1 id="description">
111
    <title>DESCRIPTION</title>
112
    <para>
113
      <command>&COMMANDNAME;</command> is a program which is meant to
114
      be a <citerefentry><refentrytitle>systemd</refentrytitle>
115
      <manvolnum>1</manvolnum></citerefentry> <quote>Password
116
      Agent</quote> (See <ulink
237.7.769 by teddy at recompile
Change URL of systemd "Password Agents" specification
117
      url="https://systemd.io/PASSWORD_AGENTS/">Password
118
      Agents</ulink>).  The aim of this program is therefore to
119
      acquire and then send a password to some other program which
237.7.675 by Teddy Hogeborn
Add dracut(8) support
120
      will use the password to unlock the encrypted root disk.
121
    </para>
122
    <para>
123
      This program is not meant to be invoked directly, but can be in
124
      order to test it.
125
    </para>
126
  </refsect1>
127
128
  <refsect1 id="purpose">
129
    <title>PURPOSE</title>
130
    <para>
131
      The purpose of this is to enable <emphasis>remote and unattended
132
      rebooting</emphasis> of client host computer with an
133
      <emphasis>encrypted root file system</emphasis>.  See <xref
134
      linkend="overview"/> for details.
135
    </para>
136
  </refsect1>
137
138
  <refsect1>
139
    <title>OPTIONS</title>
140
    <variablelist>
141
142
      <varlistentry>
143
	<term><option>--agent-directory
144
	<replaceable>DIRECTORY</replaceable></option></term>
145
	<listitem>
146
	  <para>
147
	    Specify a different agent directory.  The default is
148
	    <quote><filename class="directory"
149
	    >/run/systemd/ask-password</filename ></quote> as per the
237.7.769 by teddy at recompile
Change URL of systemd "Password Agents" specification
150
	    <ulink url="https://systemd.io/PASSWORD_AGENTS/">Password
151
	    Agents</ulink> specification.
237.7.675 by Teddy Hogeborn
Add dracut(8) support
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
237.7.769 by teddy at recompile
Change URL of systemd "Password Agents" specification
273
      url="https://systemd.io/PASSWORD_AGENTS/">Password
274
      Agents</ulink> mechanism.
237.7.675 by Teddy Hogeborn
Add dracut(8) support
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
237.7.769 by teddy at recompile
Change URL of systemd "Password Agents" specification
284
    url="https://systemd.io/PASSWORD_AGENTS/">Password Agents</ulink>
285
    specification) to all currently unanswered password questions.
237.7.675 by Teddy Hogeborn
Add dracut(8) support
286
    </para>
287
    <para>
288
      This program should be started (normally as a systemd service,
289
      which in turn is normally started by a <citerefentry
290
      ><refentrytitle>systemd.path</refentrytitle>
291
      <manvolnum>5</manvolnum></citerefentry> file) as a reaction to
292
      files named <quote><filename>ask.<replaceable>xxxx</replaceable
293
      ></filename></quote> appearing in the agent directory
294
      <quote><filename
295
      class="directory">/run/systemd/ask-password</filename></quote>
296
      (or the directory specified by
297
      <option>--agent-directory</option>).
298
    </para>
299
  </refsect1>
300
301
  <refsect1 id="exit_status">
302
    <title>EXIT STATUS</title>
303
    <para>
304
      Exit status of this program is zero if no errors were
305
      encountered, and otherwise not.
306
    </para>
307
  </refsect1>
308
309
  <refsect1 id="environment">
310
    <title>ENVIRONMENT</title>
311
    <para>
312
      This program does not use any environment variables itself, it
313
      only passes on its environment to
314
      <replaceable>MANDOS_CLIENT</replaceable>.  Also, the
315
      <option>--helper-directory</option> option will affect the
316
      environment variable <envar>MANDOSPLUGINHELPERDIR</envar> for
317
      <replaceable>MANDOS_CLIENT</replaceable>.
318
    </para>
319
  </refsect1>
320
321
  <refsect1 id="files">
322
    <title>FILES</title>
323
    <para>
324
      <variablelist>
325
	<varlistentry>
326
	  <term><filename class="directory"
327
			  >/run/systemd/ask-password</filename></term>
328
	  <listitem>
329
	    <para>
330
	      The default directory to watch for password questions as
331
	      per the <ulink
237.7.769 by teddy at recompile
Change URL of systemd "Password Agents" specification
332
	      url="https://systemd.io/PASSWORD_AGENTS/">Password
333
	      Agents</ulink> specification; can be changed by the
334
	      <option>--agent-directory</option> option.
237.7.675 by Teddy Hogeborn
Add dracut(8) support
335
	    </para>
336
	  </listitem>
337
	</varlistentry>
338
	<varlistentry>
339
	  <term><filename class="directory"
340
			  >/lib/mandos/plugin-helpers</filename
341
			  ></term>
342
	  <listitem>
343
	    <para>
344
	      The helper directory as supplied to
345
	      <replaceable>MANDOS_CLIENT</replaceable> via the
346
	      <envar>MANDOSPLUGINHELPERDIR</envar> environment
347
	      variable; can be changed by the
348
	      <option>--helper-directory</option> option.
349
	    </para>
350
	  </listitem>
351
	</varlistentry>
352
      </variablelist>
353
    </para>
354
  </refsect1>
355
356
  <refsect1 id="bugs">
357
    <title>BUGS</title>
358
    <xi:include href="../bugs.xml"/>
359
  </refsect1>
360
361
  <refsect1 id="examples">
362
    <title>EXAMPLE</title>
363
    <informalexample>
364
      <para>
365
	Normal invocation needs no options:
366
      </para>
367
      <para>
368
	<userinput>&COMMANDNAME;</userinput>
369
      </para>
370
    </informalexample>
371
    <informalexample>
372
      <para>
373
	Run an alternative <replaceable>MANDOS_CLIENT</replaceable>
374
	program::
375
      </para>
376
      <para>
377
	<userinput>&COMMANDNAME; /usr/local/sbin/alternate</userinput>
378
      </para>
379
    </informalexample>
380
    <informalexample>
381
      <para>
382
	Use alternative locations for the helper directory and the
383
	Mandos client, and add extra options suitable for running in
384
	the normal file system:
385
      </para>
386
      <para>
387
	
388
	<!-- do not wrap this line -->
389
	<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>
390
	
391
      </para>
392
    </informalexample>
393
    <informalexample>
394
      <para>
395
	Use the default location for
396
	<citerefentry><refentrytitle>mandos-client</refentrytitle>
397
	<manvolnum>8mandos</manvolnum></citerefentry>, but add many
398
	options to it:
399
      </para>
400
      <para>
401
402
<!-- do not wrap this line -->
237.7.735 by Teddy Hogeborn
Documentation fix: Correct example in password-agent(8mandos)
403
<userinput>&COMMANDNAME; -- /lib/mandos/plugins.d/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>
237.7.675 by Teddy Hogeborn
Add dracut(8) support
404
405
      </para>
406
    </informalexample>
407
    <informalexample>
408
      <para>
409
	Only run the self-tests:
410
      </para>
411
      <para>
412
	<userinput>&COMMANDNAME; --test</userinput>
413
      </para>
414
    </informalexample>
415
  </refsect1>
416
  <refsect1 id="security">
417
    <title>SECURITY</title>
418
    <para>
419
      This program will need to run as the root user in order to read
420
      the agent directory and the <quote><filename
421
      >ask.<replaceable>xxxx</replaceable></filename></quote> files
422
      there, and will, when starting the Mandos client program,
423
      require the ability to set the <quote>real</quote> user and
424
      group ids to another user, by default user and group 65534,
425
      which are assumed to be non-privileged.  This is done in order
426
      to match the expectations of <citerefentry><refentrytitle
427
      >mandos-client</refentrytitle><manvolnum>8mandos</manvolnum
428
      ></citerefentry>, which assumes that its executable file is
429
      owned by the root user and also has the set-user-ID bit set (see
430
      <citerefentry><refentrytitle>execve</refentrytitle><manvolnum
431
      >2</manvolnum></citerefentry>).
432
    </para>
433
  </refsect1>
434
435
  <refsect1 id="see_also">
436
    <title>SEE ALSO</title>
437
    <para>
438
      <citerefentry><refentrytitle>intro</refentrytitle>
439
      <manvolnum>8mandos</manvolnum></citerefentry>,
440
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
441
      <manvolnum>8mandos</manvolnum></citerefentry>,
442
      <citerefentry><refentrytitle>systemd</refentrytitle>
443
      <manvolnum>1</manvolnum></citerefentry>,
444
    </para>
445
    <variablelist>
446
      <varlistentry>
447
	<term>
237.7.769 by teddy at recompile
Change URL of systemd "Password Agents" specification
448
	  <ulink url="https://systemd.io/PASSWORD_AGENTS/">Password
449
	  Agents</ulink>
237.7.675 by Teddy Hogeborn
Add dracut(8) support
450
	</term>
451
	<listitem>
452
	  <para>
453
	    The specification for systemd <quote>Password
454
	    Agent</quote> programs, which
455
	    <command>&COMMANDNAME;</command> follows.
456
	  </para>
457
	</listitem>
458
      </varlistentry>
459
    </variablelist>
460
  </refsect1>
461
462
</refentry>
463
<!-- Local Variables: -->
464
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
465
<!-- time-stamp-end: "[\"']>" -->
466
<!-- time-stamp-format: "%:y-%02m-%02d" -->
467
<!-- End: -->