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 "2012-01-01">
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>
39
34
<holder>Teddy Hogeborn</holder>
40
35
<holder>Björn Påhlsson</holder>
42
<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/"/>.
46
63
<refentrytitle>&COMMANDNAME;</refentrytitle>
47
64
<manvolnum>8</manvolnum>
53
70
Gives encrypted passwords to authenticated Mandos clients
59
76
<command>&COMMANDNAME;</command>
61
<arg choice="plain"><option>--interface
62
<replaceable>NAME</replaceable></option></arg>
63
<arg choice="plain"><option>-i
64
<replaceable>NAME</replaceable></option></arg>
68
<arg choice="plain"><option>--address
69
<replaceable>ADDRESS</replaceable></option></arg>
70
<arg choice="plain"><option>-a
71
<replaceable>ADDRESS</replaceable></option></arg>
75
<arg choice="plain"><option>--port
76
<replaceable>PORT</replaceable></option></arg>
77
<arg choice="plain"><option>-p
78
<replaceable>PORT</replaceable></option></arg>
81
<arg><option>--priority
82
<replaceable>PRIORITY</replaceable></option></arg>
84
<arg><option>--servicename
85
<replaceable>NAME</replaceable></option></arg>
87
<arg><option>--configdir
88
<replaceable>DIRECTORY</replaceable></option></arg>
90
<arg><option>--debug</option></arg>
92
<arg><option>--debuglevel
93
<replaceable>LEVEL</replaceable></option></arg>
95
<arg><option>--no-dbus</option></arg>
97
<arg><option>--no-ipv6</option></arg>
99
<arg><option>--no-restore</option></arg>
101
<arg><option>--statedir
102
<replaceable>DIRECTORY</replaceable></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>
105
96
<command>&COMMANDNAME;</command>
106
97
<group choice="req">
107
<arg choice="plain"><option>--help</option></arg>
108
<arg choice="plain"><option>-h</option></arg>
98
<arg choice="plain">-h</arg>
99
<arg choice="plain">--help</arg>
112
103
<command>&COMMANDNAME;</command>
113
<arg choice="plain"><option>--version</option></arg>
104
<arg choice="plain">--version</arg>
116
107
<command>&COMMANDNAME;</command>
117
<arg choice="plain"><option>--check</option></arg>
108
<arg choice="plain">--check</arg>
119
110
</refsynopsisdiv>
121
112
<refsect1 id="description">
122
113
<title>DESCRIPTION</title>
124
115
<command>&COMMANDNAME;</command> is a server daemon which
125
116
handles incoming request for passwords for a pre-defined list of
126
client host computers. For an introduction, see
127
<citerefentry><refentrytitle>intro</refentrytitle>
128
<manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server
129
uses Zeroconf to announce itself on the local network, and uses
130
TLS to communicate securely with and to authenticate the
131
clients. The Mandos server uses IPv6 to allow Mandos clients to
132
use IPv6 link-local addresses, since the clients will probably
133
not have any other addresses configured (see <xref
134
linkend="overview"/>). Any authenticated client is then given
135
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.
139
129
<refsect1 id="purpose">
140
130
<title>PURPOSE</title>
142
133
The purpose of this is to enable <emphasis>remote and unattended
143
134
rebooting</emphasis> of client host computer with an
144
135
<emphasis>encrypted root file system</emphasis>. See <xref
145
136
linkend="overview"/> for details.
149
141
<refsect1 id="options">
150
142
<title>OPTIONS</title>
146
<term><option>-h</option></term>
153
147
<term><option>--help</option></term>
154
<term><option>-h</option></term>
157
150
Show a help message and exit
156
<term><option>-i</option>
157
<replaceable>NAME</replaceable></term>
163
158
<term><option>--interface</option>
164
159
<replaceable>NAME</replaceable></term>
165
<term><option>-i</option>
166
<replaceable>NAME</replaceable></term>
168
161
<xi:include href="mandos-options.xml" xpointer="interface"/>
173
<term><option>--address
174
<replaceable>ADDRESS</replaceable></option></term>
176
<replaceable>ADDRESS</replaceable></option></term>
166
<term><literal>-a</literal>, <literal>--address <replaceable>
167
ADDRESS</replaceable></literal></term>
178
169
<xi:include href="mandos-options.xml" xpointer="address"/>
184
<replaceable>PORT</replaceable></option></term>
186
<replaceable>PORT</replaceable></option></term>
174
<term><literal>-p</literal>, <literal>--port <replaceable>
175
PORT</replaceable></literal></term>
188
177
<xi:include href="mandos-options.xml" xpointer="port"/>
193
<term><option>--check</option></term>
182
<term><literal>--check</literal></term>
196
185
Run the server’s self-tests. This includes any unit
203
<term><option>--debug</option></term>
192
<term><literal>--debug</literal></term>
205
194
<xi:include href="mandos-options.xml" xpointer="debug"/>
210
<term><option>--debuglevel
211
<replaceable>LEVEL</replaceable></option></term>
214
Set the debugging log level.
215
<replaceable>LEVEL</replaceable> is a string, one of
216
<quote><literal>CRITICAL</literal></quote>,
217
<quote><literal>ERROR</literal></quote>,
218
<quote><literal>WARNING</literal></quote>,
219
<quote><literal>INFO</literal></quote>, or
220
<quote><literal>DEBUG</literal></quote>, in order of
221
increasing verbosity. The default level is
222
<quote><literal>WARNING</literal></quote>.
228
<term><option>--priority <replaceable>
229
PRIORITY</replaceable></option></term>
199
<term><literal>--priority <replaceable>
200
PRIORITY</replaceable></literal></term>
231
202
<xi:include href="mandos-options.xml" xpointer="priority"/>
236
<term><option>--servicename
237
<replaceable>NAME</replaceable></option></term>
207
<term><literal>--servicename <replaceable>NAME</replaceable>
239
210
<xi:include href="mandos-options.xml"
240
211
xpointer="servicename"/>
245
<term><option>--configdir
246
<replaceable>DIRECTORY</replaceable></option></term>
216
<term><literal>--configdir <replaceable>DIR</replaceable>
249
220
Directory to search for configuration files. Default is
260
<term><option>--version</option></term>
231
<term><literal>--version</literal></term>
263
234
Prints the program version and exit.
269
<term><option>--no-dbus</option></term>
271
<xi:include href="mandos-options.xml" xpointer="dbus"/>
273
See also <xref linkend="dbus_interface"/>.
279
<term><option>--no-ipv6</option></term>
281
<xi:include href="mandos-options.xml" xpointer="ipv6"/>
286
<term><option>--no-restore</option></term>
288
<xi:include href="mandos-options.xml" xpointer="restore"/>
293
<term><option>--statedir
294
<replaceable>DIRECTORY</replaceable></option></term>
296
<xi:include href="mandos-options.xml" xpointer="statedir"/>
302
241
<refsect1 id="overview">
303
242
<title>OVERVIEW</title>
304
243
<xi:include href="overview.xml"/>
306
245
This program is the server part. It is a normal server program
307
246
and will run in a normal system environment, not in an initial
308
<acronym>RAM</acronym> disk environment.
247
RAM disk environment.
312
251
<refsect1 id="protocol">
313
252
<title>NETWORK PROTOCOL</title>
367
306
</tbody></tgroup></table>
370
309
<refsect1 id="checking">
371
310
<title>CHECKING</title>
373
312
The server will, by default, continually check that the clients
374
313
are still up. If a client has not been confirmed as being up
375
314
for some time, the client is assumed to be compromised and is no
376
longer eligible to receive the encrypted password. (Manual
377
intervention is required to re-enable a client.) The timeout,
378
extended timeout, checker program, and interval between checks
379
can be configured both globally and per client; see
380
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
381
<manvolnum>5</manvolnum></citerefentry>. A client successfully
382
receiving its password will also be treated as a successful
387
<refsect1 id="approval">
388
<title>APPROVAL</title>
390
The server can be configured to require manual approval for a
391
client before it is sent its secret. The delay to wait for such
392
approval and the default action (approve or deny) can be
393
configured both globally and per client; see <citerefentry>
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>
394
318
<refentrytitle>mandos-clients.conf</refentrytitle>
395
<manvolnum>5</manvolnum></citerefentry>. By default all clients
396
will be approved immediately without delay.
399
This can be used to deny a client its secret if not manually
400
approved within a specified time. It can also be used to make
401
the server delay before giving a client its secret, allowing
402
optional manual denying of this specific client.
319
<manvolnum>5</manvolnum></citerefentry>.
407
323
<refsect1 id="logging">
408
324
<title>LOGGING</title>
410
326
The server will send log message with various severity levels to
411
<filename class="devicefile">/dev/log</filename>. With the
327
<filename>/dev/log</filename>. With the
412
328
<option>--debug</option> option, it will log even more messages,
413
329
and also show them on the console.
417
<refsect1 id="dbus_interface">
418
<title>D-BUS INTERFACE</title>
420
The server will by default provide a D-Bus system bus interface.
421
This interface will only be accessible by the root user or a
422
Mandos-specific user, if such a user exists. For documentation
423
of the D-Bus API, see the file <filename>DBUS-API</filename>.
427
333
<refsect1 id="exit_status">
428
334
<title>EXIT STATUS</title>
614
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
617
535
For more details on client-side security, see
618
<citerefentry><refentrytitle>mandos-client</refentrytitle>
536
<citerefentry><refentrytitle>password-request</refentrytitle>
619
537
<manvolnum>8mandos</manvolnum></citerefentry>.
624
542
<refsect1 id="see_also">
625
543
<title>SEE ALSO</title>
627
<citerefentry><refentrytitle>intro</refentrytitle>
628
<manvolnum>8mandos</manvolnum></citerefentry>,
629
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
630
<manvolnum>5</manvolnum></citerefentry>,
631
<citerefentry><refentrytitle>mandos.conf</refentrytitle>
632
<manvolnum>5</manvolnum></citerefentry>,
633
<citerefentry><refentrytitle>mandos-client</refentrytitle>
634
<manvolnum>8mandos</manvolnum></citerefentry>,
635
<citerefentry><refentrytitle>sh</refentrytitle>
636
<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>