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-11-13">
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>
35
<holder>Teddy Hogeborn</holder>
36
<holder>Björn Påhlsson</holder>
38
<xi:include href="../legalnotice.xml"/>
42
<refentrytitle>&COMMANDNAME;</refentrytitle>
43
<manvolnum>8mandos</manvolnum>
47
<refname><command>&COMMANDNAME;</command></refname>
49
Run Mandos client as a systemd password agent.
55
<command>&COMMANDNAME;</command>
56
<arg><option>--agent-directory=<replaceable
57
>DIRECTORY</replaceable></option></arg>
59
<arg><option>--helper-directory=<replaceable
60
>DIRECTORY</replaceable></option></arg>
62
<!-- <arg><option>-\-plugin-helper-dir=<replaceable -->
63
<!-- >DIRECTORY</replaceable></option></arg> -->
65
<arg><option>--user=<replaceable
66
>USERID</replaceable></option></arg>
68
<!-- <arg><option>-\-userid=<replaceable -->
69
<!-- >ID</replaceable></option></arg> -->
71
<arg><option>--group=<replaceable
72
>GROUPID</replaceable></option></arg>
74
<!-- <arg><option>-\-groupid=<replaceable -->
75
<!-- >ID</replaceable></option></arg> -->
79
<replaceable>MANDOS_CLIENT</replaceable>
81
<arg choice="plain"><replaceable>OPTIONS</replaceable></arg>
86
<command>&COMMANDNAME;</command>
87
<arg choice="plain"><option>--test</option></arg>
90
<command>&COMMANDNAME;</command>
92
<arg choice="plain"><option>--help</option></arg>
93
<arg choice="plain"><option>-?</option></arg>
97
<command>&COMMANDNAME;</command>
98
<arg choice="plain"><option>--usage</option></arg>
101
<command>&COMMANDNAME;</command>
103
<arg choice="plain"><option>--version</option></arg>
104
<arg choice="plain"><option>-V</option></arg>
109
<refsect1 id="description">
110
<title>DESCRIPTION</title>
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.
122
This program is not meant to be invoked directly, but can be in
127
<refsect1 id="purpose">
128
<title>PURPOSE</title>
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.
138
<title>OPTIONS</title>
142
<term><option>--agent-directory
143
<replaceable>DIRECTORY</replaceable></option></term>
146
Specify a different agent directory. The default is
147
<quote><filename class="directory"
148
>/run/systemd/ask-password</filename ></quote> as per the
150
url="https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents/"
151
>Password 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://www.freedesktop.org/wiki/Software/systemd/PasswordAgents/"
274
>Password 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://www.freedesktop.org/wiki/Software/systemd/PasswordAgents/"
285
>Password Agents</ulink> specification) to all currently
286
unanswered password questions.
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
296
class="directory">/run/systemd/ask-password</filename></quote>
297
(or the directory specified by
298
<option>--agent-directory</option>).
302
<refsect1 id="exit_status">
303
<title>EXIT STATUS</title>
305
Exit status of this program is zero if no errors were
306
encountered, and otherwise not.
310
<refsect1 id="environment">
311
<title>ENVIRONMENT</title>
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>.
322
<refsect1 id="files">
327
<term><filename class="directory"
328
>/run/systemd/ask-password</filename></term>
331
The default directory to watch for password questions as
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.
340
<term><filename class="directory"
341
>/lib/mandos/plugin-helpers</filename
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.
359
<xi:include href="../bugs.xml"/>
362
<refsect1 id="examples">
363
<title>EXAMPLE</title>
366
Normal invocation needs no options:
369
<userinput>&COMMANDNAME;</userinput>
374
Run an alternative <replaceable>MANDOS_CLIENT</replaceable>
378
<userinput>&COMMANDNAME; /usr/local/sbin/alternate</userinput>
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:
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>
396
Use the default location for
397
<citerefentry><refentrytitle>mandos-client</refentrytitle>
398
<manvolnum>8mandos</manvolnum></citerefentry>, but add many
403
<!-- do not wrap this line -->
404
<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>
410
Only run the self-tests:
413
<userinput>&COMMANDNAME; --test</userinput>
417
<refsect1 id="security">
418
<title>SECURITY</title>
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>).
436
<refsect1 id="see_also">
437
<title>SEE ALSO</title>
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>,
450
url="https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents/"
451
>Password Agents</ulink>
455
The specification for systemd <quote>Password
456
Agent</quote> programs, which
457
<command>&COMMANDNAME;</command> follows.
465
<!-- Local Variables: -->
466
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
467
<!-- time-stamp-end: "[\"']>" -->
468
<!-- time-stamp-format: "%:y-%02m-%02d" -->
added
removed
dracut-module/password-agent.xml
