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 "2021-02-03">
6
<!ENTITY % common SYSTEM "../common.ent">
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
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>
19
<firstname>Björn</firstname>
20
<surname>Påhlsson</surname>
22
<email>belorn@recompile.se</email>
26
<firstname>Teddy</firstname>
27
<surname>Hogeborn</surname>
29
<email>teddy@recompile.se</email>
36
<holder>Teddy Hogeborn</holder>
37
<holder>Björn Påhlsson</holder>
39
<xi:include href="../legalnotice.xml"/>
43
<refentrytitle>&COMMANDNAME;</refentrytitle>
44
<manvolnum>8mandos</manvolnum>
48
<refname><command>&COMMANDNAME;</command></refname>
50
Run Mandos client as a systemd password agent.
56
<command>&COMMANDNAME;</command>
57
<arg><option>--agent-directory=<replaceable
58
>DIRECTORY</replaceable></option></arg>
60
<arg><option>--helper-directory=<replaceable
61
>DIRECTORY</replaceable></option></arg>
63
<!-- <arg><option>-\-plugin-helper-dir=<replaceable -->
64
<!-- >DIRECTORY</replaceable></option></arg> -->
66
<arg><option>--user=<replaceable
67
>USERID</replaceable></option></arg>
69
<!-- <arg><option>-\-userid=<replaceable -->
70
<!-- >ID</replaceable></option></arg> -->
72
<arg><option>--group=<replaceable
73
>GROUPID</replaceable></option></arg>
75
<!-- <arg><option>-\-groupid=<replaceable -->
76
<!-- >ID</replaceable></option></arg> -->
80
<replaceable>MANDOS_CLIENT</replaceable>
82
<arg choice="plain"><replaceable>OPTIONS</replaceable></arg>
87
<command>&COMMANDNAME;</command>
88
<arg choice="plain"><option>--test</option></arg>
91
<command>&COMMANDNAME;</command>
93
<arg choice="plain"><option>--help</option></arg>
94
<arg choice="plain"><option>-?</option></arg>
98
<command>&COMMANDNAME;</command>
99
<arg choice="plain"><option>--usage</option></arg>
102
<command>&COMMANDNAME;</command>
104
<arg choice="plain"><option>--version</option></arg>
105
<arg choice="plain"><option>-V</option></arg>
110
<refsect1 id="description">
111
<title>DESCRIPTION</title>
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
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
120
will use the password to unlock the encrypted root disk.
123
This program is not meant to be invoked directly, but can be in
128
<refsect1 id="purpose">
129
<title>PURPOSE</title>
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.
139
<title>OPTIONS</title>
143
<term><option>--agent-directory
144
<replaceable>DIRECTORY</replaceable></option></term>
147
Specify a different agent directory. The default is
148
<quote><filename class="directory"
149
>/run/systemd/ask-password</filename ></quote> as per the
150
<ulink url="https://systemd.io/PASSWORD_AGENTS/">Password
151
Agents</ulink> specification.
157
<term><option>--helper-directory
158
<replaceable>DIRECTORY</replaceable></option></term>
161
Specify a different helper directory. The default is
162
<quote><filename class="directory"
163
>/lib/mandos/plugin-helpers</filename
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.
170
<citerefentry><refentrytitle>mandos-client</refentrytitle
171
><manvolnum>8mandos</manvolnum></citerefentry>.)
178
<replaceable>USERID</replaceable></option></term>
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.
190
<term><option>--group
191
<replaceable>GROUPID</replaceable></option></term>
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.
203
<term><replaceable>MANDOS_CLIENT</replaceable></term>
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
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
222
<term><option>--help</option></term>
223
<term><option>-?</option></term>
226
Gives a help message about options and their meanings.
232
<term><option>--test</option></term>
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>.
244
<term><option>--usage</option></term>
247
Gives a short usage message.
253
<term><option>--version</option></term>
254
<term><option>-V</option></term>
257
Prints the program version.
264
<refsect1 id="overview">
265
<title>OVERVIEW</title>
266
<xi:include href="../overview.xml"/>
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://systemd.io/PASSWORD_AGENTS/">Password
274
Agents</ulink> mechanism.
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://systemd.io/PASSWORD_AGENTS/">Password Agents</ulink>
285
specification) to all currently unanswered password questions.
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
295
class="directory">/run/systemd/ask-password</filename></quote>
296
(or the directory specified by
297
<option>--agent-directory</option>).
301
<refsect1 id="exit_status">
302
<title>EXIT STATUS</title>
304
Exit status of this program is zero if no errors were
305
encountered, and otherwise not.
309
<refsect1 id="environment">
310
<title>ENVIRONMENT</title>
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>.
321
<refsect1 id="files">
326
<term><filename class="directory"
327
>/run/systemd/ask-password</filename></term>
330
The default directory to watch for password questions as
332
url="https://systemd.io/PASSWORD_AGENTS/">Password
333
Agents</ulink> specification; can be changed by the
334
<option>--agent-directory</option> option.
339
<term><filename class="directory"
340
>/lib/mandos/plugin-helpers</filename
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.
358
<xi:include href="../bugs.xml"/>
361
<refsect1 id="examples">
362
<title>EXAMPLE</title>
365
Normal invocation needs no options:
368
<userinput>&COMMANDNAME;</userinput>
373
Run an alternative <replaceable>MANDOS_CLIENT</replaceable>
377
<userinput>&COMMANDNAME; /usr/local/sbin/alternate</userinput>
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:
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>
395
Use the default location for
396
<citerefentry><refentrytitle>mandos-client</refentrytitle>
397
<manvolnum>8mandos</manvolnum></citerefentry>, but add many
402
<!-- do not wrap this line -->
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>
409
Only run the self-tests:
412
<userinput>&COMMANDNAME; --test</userinput>
416
<refsect1 id="security">
417
<title>SECURITY</title>
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>).
435
<refsect1 id="see_also">
436
<title>SEE ALSO</title>
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>,
448
<ulink url="https://systemd.io/PASSWORD_AGENTS/">Password
453
The specification for systemd <quote>Password
454
Agent</quote> programs, which
455
<command>&COMMANDNAME;</command> follows.
463
<!-- Local Variables: -->
464
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
465
<!-- time-stamp-end: "[\"']>" -->
466
<!-- time-stamp-format: "%:y-%02m-%02d" -->
added
removed
dracut-module/password-agent.xml
