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 "2020-09-16">
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://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
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
149
<ulink url="https://systemd.io/PASSWORD_AGENTS/">Password
150
Agents</ulink> specification.
156
<term><option>--helper-directory
157
<replaceable>DIRECTORY</replaceable></option></term>
160
Specify a different helper directory. The default is
161
<quote><filename class="directory"
162
>/lib/mandos/plugin-helpers</filename
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.
169
<citerefentry><refentrytitle>mandos-client</refentrytitle
170
><manvolnum>8mandos</manvolnum></citerefentry>.)
177
<replaceable>USERID</replaceable></option></term>
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.
189
<term><option>--group
190
<replaceable>GROUPID</replaceable></option></term>
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.
202
<term><replaceable>MANDOS_CLIENT</replaceable></term>
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
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
221
<term><option>--help</option></term>
222
<term><option>-?</option></term>
225
Gives a help message about options and their meanings.
231
<term><option>--test</option></term>
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>.
243
<term><option>--usage</option></term>
246
Gives a short usage message.
252
<term><option>--version</option></term>
253
<term><option>-V</option></term>
256
Prints the program version.
263
<refsect1 id="overview">
264
<title>OVERVIEW</title>
265
<xi:include href="../overview.xml"/>
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
272
url="https://systemd.io/PASSWORD_AGENTS/">Password
273
Agents</ulink> mechanism.
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
283
url="https://systemd.io/PASSWORD_AGENTS/">Password Agents</ulink>
284
specification) to all currently unanswered password questions.
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
294
class="directory">/run/systemd/ask-password</filename></quote>
295
(or the directory specified by
296
<option>--agent-directory</option>).
300
<refsect1 id="exit_status">
301
<title>EXIT STATUS</title>
303
Exit status of this program is zero if no errors were
304
encountered, and otherwise not.
308
<refsect1 id="environment">
309
<title>ENVIRONMENT</title>
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>.
320
<refsect1 id="files">
325
<term><filename class="directory"
326
>/run/systemd/ask-password</filename></term>
329
The default directory to watch for password questions as
331
url="https://systemd.io/PASSWORD_AGENTS/">Password
332
Agents</ulink> specification; can be changed by the
333
<option>--agent-directory</option> option.
338
<term><filename class="directory"
339
>/lib/mandos/plugin-helpers</filename
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.
357
<xi:include href="../bugs.xml"/>
360
<refsect1 id="examples">
361
<title>EXAMPLE</title>
364
Normal invocation needs no options:
367
<userinput>&COMMANDNAME;</userinput>
372
Run an alternative <replaceable>MANDOS_CLIENT</replaceable>
376
<userinput>&COMMANDNAME; /usr/local/sbin/alternate</userinput>
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:
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>
394
Use the default location for
395
<citerefentry><refentrytitle>mandos-client</refentrytitle>
396
<manvolnum>8mandos</manvolnum></citerefentry>, but add many
401
<!-- do not wrap this line -->
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>
408
Only run the self-tests:
411
<userinput>&COMMANDNAME; --test</userinput>
415
<refsect1 id="security">
416
<title>SECURITY</title>
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>).
434
<refsect1 id="see_also">
435
<title>SEE ALSO</title>
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>,
447
<ulink url="https://systemd.io/PASSWORD_AGENTS/">Password
452
The specification for systemd <quote>Password
453
Agent</quote> programs, which
454
<command>&COMMANDNAME;</command> follows.
462
<!-- Local Variables: -->
463
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
464
<!-- time-stamp-end: "[\"']>" -->
465
<!-- time-stamp-format: "%:y-%02m-%02d" -->
added
removed
dracut-module/password-agent.xml
