/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk
1127 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">
1221 by teddy at recompile
Change URL of systemd "Password Agents" specification
5
<!ENTITY TIMESTAMP "2020-09-16">
1127 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>
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
1221 by teddy at recompile
Change URL of systemd "Password Agents" specification
116
      url="https://systemd.io/PASSWORD_AGENTS/">Password
117
      Agents</ulink>).  The aim of this program is therefore to
118
      acquire and then send a password to some other program which
1127 by Teddy Hogeborn
Add dracut(8) support
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
1221 by teddy at recompile
Change URL of systemd "Password Agents" specification
149
	    <ulink url="https://systemd.io/PASSWORD_AGENTS/">Password
150
	    Agents</ulink> specification.
1127 by Teddy Hogeborn
Add dracut(8) support
151
	  </para>
152
	</listitem>
153
      </varlistentry>
154
155
      <varlistentry>
156
	<term><option>--helper-directory
157
	<replaceable>DIRECTORY</replaceable></option></term>
158
	<listitem>
159
	  <para>
160
	    Specify a different helper directory.  The default is
161
	    <quote><filename class="directory"
162
			     >/lib/mandos/plugin-helpers</filename
163
			     ></quote>, which
164
	    will exist in the initial <acronym>RAM</acronym> disk
165
	    environment.  (This will simply be passed to the
166
	    <replaceable>MANDOS_CLIENT</replaceable> program via the
167
	    <envar>MANDOSPLUGINHELPERDIR</envar> environment variable.
168
	    See
169
	    <citerefentry><refentrytitle>mandos-client</refentrytitle
170
	    ><manvolnum>8mandos</manvolnum></citerefentry>.)
171
	  </para>
172
	</listitem>
173
      </varlistentry>
174
175
      <varlistentry>
176
	<term><option>--user
177
	<replaceable>USERID</replaceable></option></term>
178
	<listitem>
179
	  <para>
180
	    Change real user ID to <replaceable>USERID</replaceable>
181
	    when running <replaceable>MANDOS_CLIENT</replaceable>.
182
	    The default is 65534.  <emphasis>Note:</emphasis> This
183
	    must be a number, not a name.
184
	  </para>
185
	</listitem>
186
      </varlistentry>
187
188
      <varlistentry>
189
	<term><option>--group
190
	<replaceable>GROUPID</replaceable></option></term>
191
	<listitem>
192
	  <para>
193
	    Change real group ID to <replaceable>GROUPID</replaceable>
194
	    when running <replaceable>MANDOS_CLIENT</replaceable>.
195
	    The default is 65534.  <emphasis>Note:</emphasis> This
196
	    must be a number, not a name.
197
	  </para>
198
	</listitem>
199
      </varlistentry>
200
201
      <varlistentry>
202
	<term><replaceable>MANDOS_CLIENT</replaceable></term>
203
	<listitem>
204
	  <para>
205
	    This specifies the file name for
206
	    <citerefentry><refentrytitle>mandos-client</refentrytitle
207
	    ><manvolnum>8mandos</manvolnum></citerefentry>.  If the
208
	    <quote><option>--</option></quote> option is given, any
209
	    following options are passed to the <replaceable
210
	    >MANDOS_CLIENT</replaceable> program.  The default is
211
	    <quote><filename
212
	    >/lib/mandos/plugins.d/mandos-client</filename ></quote>
213
	    (which is the correct location for the initial
214
	    <acronym>RAM</acronym> disk environment) without any
215
	    options.
216
	  </para>
217
	</listitem>
218
      </varlistentry>
219
220
      <varlistentry>
221
	<term><option>--help</option></term>
222
	<term><option>-?</option></term>
223
	<listitem>
224
	  <para>
225
	    Gives a help message about options and their meanings.
226
	  </para>
227
	</listitem>
228
      </varlistentry>
229
230
      <varlistentry>
231
	<term><option>--test</option></term>
232
	<listitem>
233
	  <para>
234
	    Ignore normal operation; instead only run self-tests.
235
	    Adding the <option>--help</option> option may show more
236
	    options possible in combination with
237
	    <option>--test</option>.
238
	  </para>
239
	</listitem>
240
      </varlistentry>
241
242
      <varlistentry>
243
	<term><option>--usage</option></term>
244
	<listitem>
245
	  <para>
246
	    Gives a short usage message.
247
	  </para>
248
	</listitem>
249
      </varlistentry>
250
251
      <varlistentry>
252
	<term><option>--version</option></term>
253
	<term><option>-V</option></term>
254
	<listitem>
255
	  <para>
256
	    Prints the program version.
257
	  </para>
258
	</listitem>
259
      </varlistentry>
260
    </variablelist>
261
  </refsect1>
262
263
  <refsect1 id="overview">
264
    <title>OVERVIEW</title>
265
    <xi:include href="../overview.xml"/>
266
    <para>
267
      This program, &COMMANDNAME;, will run on the client side in the
268
      initial <acronym>RAM</acronym> disk environment, and is
269
      responsible for getting a password from the Mandos client
270
      program itself, and to send that password to whatever is
271
      currently asking for a password using the systemd <ulink
1221 by teddy at recompile
Change URL of systemd "Password Agents" specification
272
      url="https://systemd.io/PASSWORD_AGENTS/">Password
273
      Agents</ulink> mechanism.
1127 by Teddy Hogeborn
Add dracut(8) support
274
    </para>
275
    <para>To accomplish this, &COMMANDNAME; runs the
276
    <command>mandos-client</command> program (which is the actual
277
    client program communicating with the Mandos server) or,
278
    alternatively, any executable file specified as
279
    <replaceable>MANDOS_CLIENT</replaceable>, and, as soon as a
280
    password is acquired from the
281
    <replaceable>MANDOS_CLIENT</replaceable> program, sends that
282
    password (as per the <ulink
1221 by teddy at recompile
Change URL of systemd "Password Agents" specification
283
    url="https://systemd.io/PASSWORD_AGENTS/">Password Agents</ulink>
284
    specification) to all currently unanswered password questions.
1127 by Teddy Hogeborn
Add dracut(8) support
285
    </para>
286
    <para>
287
      This program should be started (normally as a systemd service,
288
      which in turn is normally started by a <citerefentry
289
      ><refentrytitle>systemd.path</refentrytitle>
290
      <manvolnum>5</manvolnum></citerefentry> file) as a reaction to
291
      files named <quote><filename>ask.<replaceable>xxxx</replaceable
292
      ></filename></quote> appearing in the agent directory
293
      <quote><filename
294
      class="directory">/run/systemd/ask-password</filename></quote>
295
      (or the directory specified by
296
      <option>--agent-directory</option>).
297
    </para>
298
  </refsect1>
299
300
  <refsect1 id="exit_status">
301
    <title>EXIT STATUS</title>
302
    <para>
303
      Exit status of this program is zero if no errors were
304
      encountered, and otherwise not.
305
    </para>
306
  </refsect1>
307
308
  <refsect1 id="environment">
309
    <title>ENVIRONMENT</title>
310
    <para>
311
      This program does not use any environment variables itself, it
312
      only passes on its environment to
313
      <replaceable>MANDOS_CLIENT</replaceable>.  Also, the
314
      <option>--helper-directory</option> option will affect the
315
      environment variable <envar>MANDOSPLUGINHELPERDIR</envar> for
316
      <replaceable>MANDOS_CLIENT</replaceable>.
317
    </para>
318
  </refsect1>
319
320
  <refsect1 id="files">
321
    <title>FILES</title>
322
    <para>
323
      <variablelist>
324
	<varlistentry>
325
	  <term><filename class="directory"
326
			  >/run/systemd/ask-password</filename></term>
327
	  <listitem>
328
	    <para>
329
	      The default directory to watch for password questions as
330
	      per the <ulink
1221 by teddy at recompile
Change URL of systemd "Password Agents" specification
331
	      url="https://systemd.io/PASSWORD_AGENTS/">Password
332
	      Agents</ulink> specification; can be changed by the
333
	      <option>--agent-directory</option> option.
1127 by Teddy Hogeborn
Add dracut(8) support
334
	    </para>
335
	  </listitem>
336
	</varlistentry>
337
	<varlistentry>
338
	  <term><filename class="directory"
339
			  >/lib/mandos/plugin-helpers</filename
340
			  ></term>
341
	  <listitem>
342
	    <para>
343
	      The helper directory as supplied to
344
	      <replaceable>MANDOS_CLIENT</replaceable> via the
345
	      <envar>MANDOSPLUGINHELPERDIR</envar> environment
346
	      variable; can be changed by the
347
	      <option>--helper-directory</option> option.
348
	    </para>
349
	  </listitem>
350
	</varlistentry>
351
      </variablelist>
352
    </para>
353
  </refsect1>
354
355
  <refsect1 id="bugs">
356
    <title>BUGS</title>
357
    <xi:include href="../bugs.xml"/>
358
  </refsect1>
359
360
  <refsect1 id="examples">
361
    <title>EXAMPLE</title>
362
    <informalexample>
363
      <para>
364
	Normal invocation needs no options:
365
      </para>
366
      <para>
367
	<userinput>&COMMANDNAME;</userinput>
368
      </para>
369
    </informalexample>
370
    <informalexample>
371
      <para>
372
	Run an alternative <replaceable>MANDOS_CLIENT</replaceable>
373
	program::
374
      </para>
375
      <para>
376
	<userinput>&COMMANDNAME; /usr/local/sbin/alternate</userinput>
377
      </para>
378
    </informalexample>
379
    <informalexample>
380
      <para>
381
	Use alternative locations for the helper directory and the
382
	Mandos client, and add extra options suitable for running in
383
	the normal file system:
384
      </para>
385
      <para>
386
	
387
	<!-- do not wrap this line -->
388
	<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>
389
	
390
      </para>
391
    </informalexample>
392
    <informalexample>
393
      <para>
394
	Use the default location for
395
	<citerefentry><refentrytitle>mandos-client</refentrytitle>
396
	<manvolnum>8mandos</manvolnum></citerefentry>, but add many
397
	options to it:
398
      </para>
399
      <para>
400
401
<!-- do not wrap this line -->
1187 by Teddy Hogeborn
Documentation fix: Correct example in password-agent(8mandos)
402
<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>
1127 by Teddy Hogeborn
Add dracut(8) support
403
404
      </para>
405
    </informalexample>
406
    <informalexample>
407
      <para>
408
	Only run the self-tests:
409
      </para>
410
      <para>
411
	<userinput>&COMMANDNAME; --test</userinput>
412
      </para>
413
    </informalexample>
414
  </refsect1>
415
  <refsect1 id="security">
416
    <title>SECURITY</title>
417
    <para>
418
      This program will need to run as the root user in order to read
419
      the agent directory and the <quote><filename
420
      >ask.<replaceable>xxxx</replaceable></filename></quote> files
421
      there, and will, when starting the Mandos client program,
422
      require the ability to set the <quote>real</quote> user and
423
      group ids to another user, by default user and group 65534,
424
      which are assumed to be non-privileged.  This is done in order
425
      to match the expectations of <citerefentry><refentrytitle
426
      >mandos-client</refentrytitle><manvolnum>8mandos</manvolnum
427
      ></citerefentry>, which assumes that its executable file is
428
      owned by the root user and also has the set-user-ID bit set (see
429
      <citerefentry><refentrytitle>execve</refentrytitle><manvolnum
430
      >2</manvolnum></citerefentry>).
431
    </para>
432
  </refsect1>
433
434
  <refsect1 id="see_also">
435
    <title>SEE ALSO</title>
436
    <para>
437
      <citerefentry><refentrytitle>intro</refentrytitle>
438
      <manvolnum>8mandos</manvolnum></citerefentry>,
439
      <citerefentry><refentrytitle>mandos-client</refentrytitle>
440
      <manvolnum>8mandos</manvolnum></citerefentry>,
441
      <citerefentry><refentrytitle>systemd</refentrytitle>
442
      <manvolnum>1</manvolnum></citerefentry>,
443
    </para>
444
    <variablelist>
445
      <varlistentry>
446
	<term>
1221 by teddy at recompile
Change URL of systemd "Password Agents" specification
447
	  <ulink url="https://systemd.io/PASSWORD_AGENTS/">Password
448
	  Agents</ulink>
1127 by Teddy Hogeborn
Add dracut(8) support
449
	</term>
450
	<listitem>
451
	  <para>
452
	    The specification for systemd <quote>Password
453
	    Agent</quote> programs, which
454
	    <command>&COMMANDNAME;</command> follows.
455
	  </para>
456
	</listitem>
457
      </varlistentry>
458
    </variablelist>
459
  </refsect1>
460
461
</refentry>
462
<!-- Local Variables: -->
463
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
464
<!-- time-stamp-end: "[\"']>" -->
465
<!-- time-stamp-format: "%:y-%02m-%02d" -->
466
<!-- End: -->