1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
<!ENTITY VERSION "1.0">
5
4
<!ENTITY COMMANDNAME "mandos">
5
<!ENTITY TIMESTAMP "2015-07-20">
6
<!ENTITY % common SYSTEM "common.ent">
8
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
<title>&COMMANDNAME;</title>
12
<title>Mandos Manual</title>
11
13
<!-- NWalsh’s docbook scripts use this to generate the footer: -->
12
<productname>&COMMANDNAME;</productname>
13
<productnumber>&VERSION;</productnumber>
14
<productname>Mandos</productname>
15
<productnumber>&version;</productnumber>
16
<date>&TIMESTAMP;</date>
16
19
<firstname>Björn</firstname>
17
20
<surname>Påhlsson</surname>
19
<email>belorn@fukt.bsnet.se</email>
22
<email>belorn@recompile.se</email>
23
26
<firstname>Teddy</firstname>
24
27
<surname>Hogeborn</surname>
26
<email>teddy@fukt.bsnet.se</email>
29
<email>teddy@recompile.se</email>
32
40
<holder>Teddy Hogeborn</holder>
33
41
<holder>Björn Påhlsson</holder>
37
This manual page is free software: you can redistribute it
38
and/or modify it under the terms of the GNU General Public
39
License as published by the Free Software Foundation,
40
either version 3 of the License, or (at your option) any
45
This manual page is distributed in the hope that it will
46
be useful, but WITHOUT ANY WARRANTY; without even the
47
implied warranty of MERCHANTABILITY or FITNESS FOR A
48
PARTICULAR PURPOSE. See the GNU General Public License
53
You should have received a copy of the GNU General Public
54
License along with this program; If not, see
55
<ulink url="http://www.gnu.org/licenses/"/>.
43
<xi:include href="legalnotice.xml"/>
61
47
<refentrytitle>&COMMANDNAME;</refentrytitle>
62
48
<manvolnum>8</manvolnum>
66
52
<refname><command>&COMMANDNAME;</command></refname>
68
Sends encrypted passwords to authenticated Mandos clients
54
Gives encrypted passwords to authenticated Mandos clients
74
60
<command>&COMMANDNAME;</command>
75
<arg>--interface<arg choice="plain">IF</arg></arg>
76
<arg>--address<arg choice="plain">ADDRESS</arg></arg>
77
<arg>--port<arg choice="plain">PORT</arg></arg>
78
<arg>--priority<arg choice="plain">PRIORITY</arg></arg>
79
<arg>--servicename<arg choice="plain">NAME</arg></arg>
80
<arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
84
<command>&COMMANDNAME;</command>
85
<arg>-i<arg choice="plain">IF</arg></arg>
86
<arg>-a<arg choice="plain">ADDRESS</arg></arg>
87
<arg>-p<arg choice="plain">PORT</arg></arg>
88
<arg>--priority<arg choice="plain">PRIORITY</arg></arg>
89
<arg>--servicename<arg choice="plain">NAME</arg></arg>
90
<arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
62
<arg choice="plain"><option>--interface
63
<replaceable>NAME</replaceable></option></arg>
64
<arg choice="plain"><option>-i
65
<replaceable>NAME</replaceable></option></arg>
69
<arg choice="plain"><option>--address
70
<replaceable>ADDRESS</replaceable></option></arg>
71
<arg choice="plain"><option>-a
72
<replaceable>ADDRESS</replaceable></option></arg>
76
<arg choice="plain"><option>--port
77
<replaceable>PORT</replaceable></option></arg>
78
<arg choice="plain"><option>-p
79
<replaceable>PORT</replaceable></option></arg>
82
<arg><option>--priority
83
<replaceable>PRIORITY</replaceable></option></arg>
85
<arg><option>--servicename
86
<replaceable>NAME</replaceable></option></arg>
88
<arg><option>--configdir
89
<replaceable>DIRECTORY</replaceable></option></arg>
91
<arg><option>--debug</option></arg>
93
<arg><option>--debuglevel
94
<replaceable>LEVEL</replaceable></option></arg>
96
<arg><option>--no-dbus</option></arg>
98
<arg><option>--no-ipv6</option></arg>
100
<arg><option>--no-restore</option></arg>
102
<arg><option>--statedir
103
<replaceable>DIRECTORY</replaceable></option></arg>
105
<arg><option>--socket
106
<replaceable>FD</replaceable></option></arg>
108
<arg><option>--foreground</option></arg>
110
<arg><option>--no-zeroconf</option></arg>
94
113
<command>&COMMANDNAME;</command>
95
114
<group choice="req">
96
<arg choice="plain">-h</arg>
97
<arg choice="plain">--help</arg>
115
<arg choice="plain"><option>--help</option></arg>
116
<arg choice="plain"><option>-h</option></arg>
101
120
<command>&COMMANDNAME;</command>
102
<arg choice="plain">--version</arg>
121
<arg choice="plain"><option>--version</option></arg>
105
124
<command>&COMMANDNAME;</command>
106
<arg choice="plain">--check</arg>
125
<arg choice="plain"><option>--check</option></arg>
108
127
</refsynopsisdiv>
110
129
<refsect1 id="description">
111
130
<title>DESCRIPTION</title>
113
132
<command>&COMMANDNAME;</command> is a server daemon which
114
133
handles incoming request for passwords for a pre-defined list of
115
client host computers. The Mandos server uses Zeroconf to
116
announce itself on the local network, and uses TLS to
117
communicate securely with and to authenticate the clients. The
118
Mandos server uses IPv6 to allow Mandos clients to use IPv6
119
link-local addresses, since the clients will probably not have
120
any other addresses configured (see <xref linkend="overview"/>).
121
Any authenticated client is then given the stored pre-encrypted
122
password for that specific client.
134
client host computers. For an introduction, see
135
<citerefentry><refentrytitle>intro</refentrytitle>
136
<manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server
137
uses Zeroconf to announce itself on the local network, and uses
138
TLS to communicate securely with and to authenticate the
139
clients. The Mandos server uses IPv6 to allow Mandos clients to
140
use IPv6 link-local addresses, since the clients will probably
141
not have any other addresses configured (see <xref
142
linkend="overview"/>). Any authenticated client is then given
143
the stored pre-encrypted password for that specific client.
127
147
<refsect1 id="purpose">
128
148
<title>PURPOSE</title>
131
150
The purpose of this is to enable <emphasis>remote and unattended
132
151
rebooting</emphasis> of client host computer with an
133
152
<emphasis>encrypted root file system</emphasis>. See <xref
134
153
linkend="overview"/> for details.
139
157
<refsect1 id="options">
140
158
<title>OPTIONS</title>
144
<term><literal>-h</literal>, <literal>--help</literal></term>
161
<term><option>--help</option></term>
162
<term><option>-h</option></term>
147
165
Show a help message and exit
153
<term><literal>-i</literal>, <literal>--interface <replaceable>
154
IF</replaceable></literal></term>
171
<term><option>--interface</option>
172
<replaceable>NAME</replaceable></term>
173
<term><option>-i</option>
174
<replaceable>NAME</replaceable></term>
156
176
<xi:include href="mandos-options.xml" xpointer="interface"/>
161
<term><literal>-a</literal>, <literal>--address <replaceable>
162
ADDRESS</replaceable></literal></term>
181
<term><option>--address
182
<replaceable>ADDRESS</replaceable></option></term>
184
<replaceable>ADDRESS</replaceable></option></term>
164
186
<xi:include href="mandos-options.xml" xpointer="address"/>
169
<term><literal>-p</literal>, <literal>--port <replaceable>
170
PORT</replaceable></literal></term>
192
<replaceable>PORT</replaceable></option></term>
194
<replaceable>PORT</replaceable></option></term>
172
196
<xi:include href="mandos-options.xml" xpointer="port"/>
177
<term><literal>--check</literal></term>
201
<term><option>--check</option></term>
180
204
Run the server’s self-tests. This includes any unit
187
<term><literal>--debug</literal></term>
211
<term><option>--debug</option></term>
189
213
<xi:include href="mandos-options.xml" xpointer="debug"/>
194
<term><literal>--priority <replaceable>
195
PRIORITY</replaceable></literal></term>
218
<term><option>--debuglevel
219
<replaceable>LEVEL</replaceable></option></term>
222
Set the debugging log level.
223
<replaceable>LEVEL</replaceable> is a string, one of
224
<quote><literal>CRITICAL</literal></quote>,
225
<quote><literal>ERROR</literal></quote>,
226
<quote><literal>WARNING</literal></quote>,
227
<quote><literal>INFO</literal></quote>, or
228
<quote><literal>DEBUG</literal></quote>, in order of
229
increasing verbosity. The default level is
230
<quote><literal>WARNING</literal></quote>.
236
<term><option>--priority <replaceable>
237
PRIORITY</replaceable></option></term>
197
239
<xi:include href="mandos-options.xml" xpointer="priority"/>
202
<term><literal>--servicename <replaceable>NAME</replaceable>
244
<term><option>--servicename
245
<replaceable>NAME</replaceable></option></term>
205
247
<xi:include href="mandos-options.xml"
206
248
xpointer="servicename"/>
211
<term><literal>--configdir <replaceable>DIR</replaceable>
253
<term><option>--configdir
254
<replaceable>DIRECTORY</replaceable></option></term>
215
257
Directory to search for configuration files. Default is
226
<term><literal>--version</literal></term>
268
<term><option>--version</option></term>
229
271
Prints the program version and exit.
277
<term><option>--no-dbus</option></term>
279
<xi:include href="mandos-options.xml" xpointer="dbus"/>
281
See also <xref linkend="dbus_interface"/>.
287
<term><option>--no-ipv6</option></term>
289
<xi:include href="mandos-options.xml" xpointer="ipv6"/>
294
<term><option>--no-restore</option></term>
296
<xi:include href="mandos-options.xml" xpointer="restore"/>
298
See also <xref linkend="persistent_state"/>.
304
<term><option>--statedir
305
<replaceable>DIRECTORY</replaceable></option></term>
307
<xi:include href="mandos-options.xml" xpointer="statedir"/>
312
<term><option>--socket
313
<replaceable>FD</replaceable></option></term>
315
<xi:include href="mandos-options.xml" xpointer="socket"/>
320
<term><option>--foreground</option></term>
322
<xi:include href="mandos-options.xml"
323
xpointer="foreground"/>
328
<term><option>--no-zeroconf</option></term>
330
<xi:include href="mandos-options.xml" xpointer="zeroconf"/>
236
337
<refsect1 id="overview">
237
338
<title>OVERVIEW</title>
238
339
<xi:include href="overview.xml"/>
240
341
This program is the server part. It is a normal server program
241
342
and will run in a normal system environment, not in an initial
242
RAM disk environment.
343
<acronym>RAM</acronym> disk environment.
246
347
<refsect1 id="protocol">
247
348
<title>NETWORK PROTOCOL</title>
301
402
</tbody></tgroup></table>
304
405
<refsect1 id="checking">
305
406
<title>CHECKING</title>
307
408
The server will, by default, continually check that the clients
308
409
are still up. If a client has not been confirmed as being up
309
410
for some time, the client is assumed to be compromised and is no
310
longer eligible to receive the encrypted password. The timeout,
311
checker program, and interval between checks can be configured
312
both globally and per client; see <citerefentry>
313
<refentrytitle>mandos.conf</refentrytitle>
314
<manvolnum>5</manvolnum></citerefentry> and <citerefentry>
411
longer eligible to receive the encrypted password. (Manual
412
intervention is required to re-enable a client.) The timeout,
413
extended timeout, checker program, and interval between checks
414
can be configured both globally and per client; see
415
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
416
<manvolnum>5</manvolnum></citerefentry>.
420
<refsect1 id="approval">
421
<title>APPROVAL</title>
423
The server can be configured to require manual approval for a
424
client before it is sent its secret. The delay to wait for such
425
approval and the default action (approve or deny) can be
426
configured both globally and per client; see <citerefentry>
315
427
<refentrytitle>mandos-clients.conf</refentrytitle>
316
<manvolnum>5</manvolnum></citerefentry>.
428
<manvolnum>5</manvolnum></citerefentry>. By default all clients
429
will be approved immediately without delay.
432
This can be used to deny a client its secret if not manually
433
approved within a specified time. It can also be used to make
434
the server delay before giving a client its secret, allowing
435
optional manual denying of this specific client.
320
440
<refsect1 id="logging">
321
441
<title>LOGGING</title>
323
The server will send log messaged with various severity levels
324
to <filename>/dev/log</filename>. With the
443
The server will send log message with various severity levels to
444
<filename class="devicefile">/dev/log</filename>. With the
325
445
<option>--debug</option> option, it will log even more messages,
326
446
and also show them on the console.
450
<refsect1 id="persistent_state">
451
<title>PERSISTENT STATE</title>
453
Client settings, initially read from
454
<filename>clients.conf</filename>, are persistent across
455
restarts, and run-time changes will override settings in
456
<filename>clients.conf</filename>. However, if a setting is
457
<emphasis>changed</emphasis> (or a client added, or removed) in
458
<filename>clients.conf</filename>, this will take precedence.
462
<refsect1 id="dbus_interface">
463
<title>D-BUS INTERFACE</title>
465
The server will by default provide a D-Bus system bus interface.
466
This interface will only be accessible by the root user or a
467
Mandos-specific user, if such a user exists. For documentation
468
of the D-Bus API, see the file <filename>DBUS-API</filename>.
330
472
<refsect1 id="exit_status">
331
473
<title>EXIT STATUS</title>
513
660
compromised if they are gone for too long.
516
If a client is compromised, its downtime should be duly noted
517
by the server which would therefore declare the client
518
invalid. But if the server was ever restarted, it would
519
re-read its client list from its configuration file and again
520
regard all clients therein as valid, and hence eligible to
521
receive their passwords. Therefore, be careful when
522
restarting servers if it is suspected that a client has, in
523
fact, been compromised by parties who may now be running a
524
fake Mandos client with the keys from the non-encrypted
525
initial RAM image of the client host. What should be done in
526
that case (if restarting the server program really is
527
necessary) is to stop the server program, edit the
528
configuration file to omit any suspect clients, and restart
532
663
For more details on client-side security, see
533
<citerefentry><refentrytitle>password-request</refentrytitle>
664
<citerefentry><refentrytitle>mandos-client</refentrytitle>
534
665
<manvolnum>8mandos</manvolnum></citerefentry>.
539
670
<refsect1 id="see_also">
540
671
<title>SEE ALSO</title>
673
<citerefentry><refentrytitle>intro</refentrytitle>
674
<manvolnum>8mandos</manvolnum></citerefentry>,
675
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
676
<manvolnum>5</manvolnum></citerefentry>,
677
<citerefentry><refentrytitle>mandos.conf</refentrytitle>
678
<manvolnum>5</manvolnum></citerefentry>,
679
<citerefentry><refentrytitle>mandos-client</refentrytitle>
680
<manvolnum>8mandos</manvolnum></citerefentry>,
681
<citerefentry><refentrytitle>sh</refentrytitle>
682
<manvolnum>1</manvolnum></citerefentry>
545
<refentrytitle>password-request</refentrytitle>
546
<manvolnum>8mandos</manvolnum>
551
This is the actual program which talks to this server.
552
Note that it is normally not invoked directly, and is only
553
run in the initial RAM disk environment, and not on a
554
fully started system.
560
687
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
595
<citation>RFC 4291: <citetitle>IP Version 6 Addressing
596
Architecture</citetitle>, section 2.5.6, Link-Local IPv6
597
Unicast Addresses</citation>
721
RFC 4291: <citetitle>IP Version 6 Addressing
722
Architecture</citetitle>
601
The clients use IPv6 link-local addresses, which are
602
immediately usable since a link-local addresses is
603
automatically assigned to a network interfaces when it is
727
<term>Section 2.2: <citetitle>Text Representation of
728
Addresses</citetitle></term>
729
<listitem><para/></listitem>
732
<term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
733
Address</citetitle></term>
734
<listitem><para/></listitem>
737
<term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
738
Addresses</citetitle></term>
741
The clients use IPv6 link-local addresses, which are
742
immediately usable since a link-local addresses is
743
automatically assigned to a network interfaces when it
610
<citation>RFC 4346: <citetitle>The Transport Layer Security
611
(TLS) Protocol Version 1.1</citetitle></citation>
753
RFC 5246: <citetitle>The Transport Layer Security (TLS)
754
Protocol Version 1.2</citetitle>
615
TLS 1.1 is the protocol implemented by GnuTLS.
758
TLS 1.2 is the protocol implemented by GnuTLS.
621
<citation>RFC 4880: <citetitle>OpenPGP Message
622
Format</citetitle></citation>
764
RFC 4880: <citetitle>OpenPGP Message Format</citetitle>