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">
4
5
<!ENTITY COMMANDNAME "mandos">
5
<!ENTITY TIMESTAMP "2015-07-20">
6
<!ENTITY % common SYSTEM "common.ent">
6
<!ENTITY TIMESTAMP "2008-08-30">
10
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
12
11
<title>Mandos Manual</title>
13
12
<!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
13
<productname>Mandos</productname>
15
<productnumber>&version;</productnumber>
14
<productnumber>&VERSION;</productnumber>
16
15
<date>&TIMESTAMP;</date>
19
18
<firstname>Björn</firstname>
20
19
<surname>Påhlsson</surname>
22
<email>belorn@recompile.se</email>
21
<email>belorn@fukt.bsnet.se</email>
26
25
<firstname>Teddy</firstname>
27
26
<surname>Hogeborn</surname>
29
<email>teddy@recompile.se</email>
28
<email>teddy@fukt.bsnet.se</email>
40
34
<holder>Teddy Hogeborn</holder>
41
35
<holder>Björn Påhlsson</holder>
43
<xi:include href="legalnotice.xml"/>
39
This manual page is free software: you can redistribute it
40
and/or modify it under the terms of the GNU General Public
41
License as published by the Free Software Foundation,
42
either version 3 of the License, or (at your option) any
47
This manual page is distributed in the hope that it will
48
be useful, but WITHOUT ANY WARRANTY; without even the
49
implied warranty of MERCHANTABILITY or FITNESS FOR A
50
PARTICULAR PURPOSE. See the GNU General Public License
55
You should have received a copy of the GNU General Public
56
License along with this program; If not, see
57
<ulink url="http://www.gnu.org/licenses/"/>.
47
63
<refentrytitle>&COMMANDNAME;</refentrytitle>
48
64
<manvolnum>8</manvolnum>
54
70
Gives encrypted passwords to authenticated Mandos clients
60
76
<command>&COMMANDNAME;</command>
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>
77
<arg>--interface<arg choice="plain">NAME</arg></arg>
78
<arg>--address<arg choice="plain">ADDRESS</arg></arg>
79
<arg>--port<arg choice="plain">PORT</arg></arg>
80
<arg>--priority<arg choice="plain">PRIORITY</arg></arg>
81
<arg>--servicename<arg choice="plain">NAME</arg></arg>
82
<arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
86
<command>&COMMANDNAME;</command>
87
<arg>-i<arg choice="plain">NAME</arg></arg>
88
<arg>-a<arg choice="plain">ADDRESS</arg></arg>
89
<arg>-p<arg choice="plain">PORT</arg></arg>
90
<arg>--priority<arg choice="plain">PRIORITY</arg></arg>
91
<arg>--servicename<arg choice="plain">NAME</arg></arg>
92
<arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
113
96
<command>&COMMANDNAME;</command>
114
97
<group choice="req">
115
<arg choice="plain"><option>--help</option></arg>
116
<arg choice="plain"><option>-h</option></arg>
98
<arg choice="plain">-h</arg>
99
<arg choice="plain">--help</arg>
120
103
<command>&COMMANDNAME;</command>
121
<arg choice="plain"><option>--version</option></arg>
104
<arg choice="plain">--version</arg>
124
107
<command>&COMMANDNAME;</command>
125
<arg choice="plain"><option>--check</option></arg>
108
<arg choice="plain">--check</arg>
127
110
</refsynopsisdiv>
129
112
<refsect1 id="description">
130
113
<title>DESCRIPTION</title>
132
115
<command>&COMMANDNAME;</command> is a server daemon which
133
116
handles incoming request for passwords for a pre-defined list of
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.
117
client host computers. The Mandos server uses Zeroconf to
118
announce itself on the local network, and uses TLS to
119
communicate securely with and to authenticate the clients. The
120
Mandos server uses IPv6 to allow Mandos clients to use IPv6
121
link-local addresses, since the clients will probably not have
122
any other addresses configured (see <xref linkend="overview"/>).
123
Any authenticated client is then given the stored pre-encrypted
124
password for that specific client.
147
129
<refsect1 id="purpose">
148
130
<title>PURPOSE</title>
150
133
The purpose of this is to enable <emphasis>remote and unattended
151
134
rebooting</emphasis> of client host computer with an
152
135
<emphasis>encrypted root file system</emphasis>. See <xref
153
136
linkend="overview"/> for details.
157
141
<refsect1 id="options">
158
142
<title>OPTIONS</title>
146
<term><option>-h</option></term>
161
147
<term><option>--help</option></term>
162
<term><option>-h</option></term>
165
150
Show a help message and exit
156
<term><option>-i</option>
157
<replaceable>NAME</replaceable></term>
171
158
<term><option>--interface</option>
172
159
<replaceable>NAME</replaceable></term>
173
<term><option>-i</option>
174
<replaceable>NAME</replaceable></term>
176
161
<xi:include href="mandos-options.xml" xpointer="interface"/>
181
<term><option>--address
182
<replaceable>ADDRESS</replaceable></option></term>
184
<replaceable>ADDRESS</replaceable></option></term>
166
<term><literal>-a</literal>, <literal>--address <replaceable>
167
ADDRESS</replaceable></literal></term>
186
169
<xi:include href="mandos-options.xml" xpointer="address"/>
192
<replaceable>PORT</replaceable></option></term>
194
<replaceable>PORT</replaceable></option></term>
174
<term><literal>-p</literal>, <literal>--port <replaceable>
175
PORT</replaceable></literal></term>
196
177
<xi:include href="mandos-options.xml" xpointer="port"/>
201
<term><option>--check</option></term>
182
<term><literal>--check</literal></term>
204
185
Run the server’s self-tests. This includes any unit
211
<term><option>--debug</option></term>
192
<term><literal>--debug</literal></term>
213
194
<xi:include href="mandos-options.xml" xpointer="debug"/>
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>
199
<term><literal>--priority <replaceable>
200
PRIORITY</replaceable></literal></term>
239
202
<xi:include href="mandos-options.xml" xpointer="priority"/>
244
<term><option>--servicename
245
<replaceable>NAME</replaceable></option></term>
207
<term><literal>--servicename <replaceable>NAME</replaceable>
247
210
<xi:include href="mandos-options.xml"
248
211
xpointer="servicename"/>
253
<term><option>--configdir
254
<replaceable>DIRECTORY</replaceable></option></term>
216
<term><literal>--configdir <replaceable>DIR</replaceable>
257
220
Directory to search for configuration files. Default is
268
<term><option>--version</option></term>
231
<term><literal>--version</literal></term>
271
234
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"/>
337
241
<refsect1 id="overview">
338
242
<title>OVERVIEW</title>
339
243
<xi:include href="overview.xml"/>
341
245
This program is the server part. It is a normal server program
342
246
and will run in a normal system environment, not in an initial
343
<acronym>RAM</acronym> disk environment.
247
RAM disk environment.
347
251
<refsect1 id="protocol">
348
252
<title>NETWORK PROTOCOL</title>
402
306
</tbody></tgroup></table>
405
309
<refsect1 id="checking">
406
310
<title>CHECKING</title>
408
312
The server will, by default, continually check that the clients
409
313
are still up. If a client has not been confirmed as being up
410
314
for some time, the client is assumed to be compromised and is no
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>
315
longer eligible to receive the encrypted password. The timeout,
316
checker program, and interval between checks can be configured
317
both globally and per client; see <citerefentry>
318
<refentrytitle>mandos-clients.conf</refentrytitle>
416
319
<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>
427
<refentrytitle>mandos-clients.conf</refentrytitle>
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.
440
323
<refsect1 id="logging">
441
324
<title>LOGGING</title>
443
326
The server will send log message with various severity levels to
444
<filename class="devicefile">/dev/log</filename>. With the
327
<filename>/dev/log</filename>. With the
445
328
<option>--debug</option> option, it will log even more messages,
446
329
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>.
472
333
<refsect1 id="exit_status">
473
334
<title>EXIT STATUS</title>
660
516
compromised if they are gone for too long.
519
If a client is compromised, its downtime should be duly noted
520
by the server which would therefore declare the client
521
invalid. But if the server was ever restarted, it would
522
re-read its client list from its configuration file and again
523
regard all clients therein as valid, and hence eligible to
524
receive their passwords. Therefore, be careful when
525
restarting servers if it is suspected that a client has, in
526
fact, been compromised by parties who may now be running a
527
fake Mandos client with the keys from the non-encrypted
528
initial RAM image of the client host. What should be done in
529
that case (if restarting the server program really is
530
necessary) is to stop the server program, edit the
531
configuration file to omit any suspect clients, and restart
663
535
For more details on client-side security, see
664
<citerefentry><refentrytitle>mandos-client</refentrytitle>
536
<citerefentry><refentrytitle>password-request</refentrytitle>
665
537
<manvolnum>8mandos</manvolnum></citerefentry>.
670
542
<refsect1 id="see_also">
671
543
<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>
546
<refentrytitle>mandos-clients.conf</refentrytitle>
547
<manvolnum>5</manvolnum></citerefentry>, <citerefentry>
548
<refentrytitle>mandos.conf</refentrytitle>
549
<manvolnum>5</manvolnum></citerefentry>, <citerefentry>
550
<refentrytitle>password-request</refentrytitle>
551
<manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
552
<refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>