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 "2011-10-03">
6
<!ENTITY % common SYSTEM "common.ent">
6
<!ENTITY OVERVIEW SYSTEM "overview.xml">
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
12
<title>Mandos Manual</title>
11
<title>&COMMANDNAME;</title>
13
12
<!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
<productname>Mandos</productname>
15
<productnumber>&version;</productnumber>
16
<date>&TIMESTAMP;</date>
13
<productname>&COMMANDNAME;</productname>
14
<productnumber>&VERSION;</productnumber>
19
17
<firstname>Björn</firstname>
20
18
<surname>Påhlsson</surname>
22
<email>belorn@recompile.se</email>
20
<email>belorn@fukt.bsnet.se</email>
26
24
<firstname>Teddy</firstname>
27
25
<surname>Hogeborn</surname>
29
<email>teddy@recompile.se</email>
27
<email>teddy@fukt.bsnet.se</email>
38
33
<holder>Teddy Hogeborn</holder>
39
34
<holder>Björn Påhlsson</holder>
41
<xi:include href="legalnotice.xml"/>
38
This manual page is free software: you can redistribute it
39
and/or modify it under the terms of the GNU General Public
40
License as published by the Free Software Foundation,
41
either version 3 of the License, or (at your option) any
46
This manual page is distributed in the hope that it will
47
be useful, but WITHOUT ANY WARRANTY; without even the
48
implied warranty of MERCHANTABILITY or FITNESS FOR A
49
PARTICULAR PURPOSE. See the GNU General Public License
54
You should have received a copy of the GNU General Public
55
License along with this program; If not, see
56
<ulink url="http://www.gnu.org/licenses/"/>.
45
62
<refentrytitle>&COMMANDNAME;</refentrytitle>
46
63
<manvolnum>8</manvolnum>
50
67
<refname><command>&COMMANDNAME;</command></refname>
52
Gives encrypted passwords to authenticated Mandos clients
69
Sends encrypted passwords to authenticated Mandos clients
58
75
<command>&COMMANDNAME;</command>
60
<arg choice="plain"><option>--interface
61
<replaceable>NAME</replaceable></option></arg>
62
<arg choice="plain"><option>-i
63
<replaceable>NAME</replaceable></option></arg>
67
<arg choice="plain"><option>--address
68
<replaceable>ADDRESS</replaceable></option></arg>
69
<arg choice="plain"><option>-a
70
<replaceable>ADDRESS</replaceable></option></arg>
74
<arg choice="plain"><option>--port
75
<replaceable>PORT</replaceable></option></arg>
76
<arg choice="plain"><option>-p
77
<replaceable>PORT</replaceable></option></arg>
80
<arg><option>--priority
81
<replaceable>PRIORITY</replaceable></option></arg>
83
<arg><option>--servicename
84
<replaceable>NAME</replaceable></option></arg>
86
<arg><option>--configdir
87
<replaceable>DIRECTORY</replaceable></option></arg>
89
<arg><option>--debug</option></arg>
91
<arg><option>--debuglevel
92
<replaceable>LEVEL</replaceable></option></arg>
94
<arg><option>--no-dbus</option></arg>
96
<arg><option>--no-ipv6</option></arg>
98
<arg><option>--no-restore</option></arg>
101
<command>&COMMANDNAME;</command>
103
<arg choice="plain"><option>--help</option></arg>
104
<arg choice="plain"><option>-h</option></arg>
108
<command>&COMMANDNAME;</command>
109
<arg choice="plain"><option>--version</option></arg>
112
<command>&COMMANDNAME;</command>
113
<arg choice="plain"><option>--check</option></arg>
76
<arg choice="opt">--interface<arg choice="plain">IF</arg></arg>
77
<arg choice="opt">--address<arg choice="plain">ADDRESS</arg></arg>
78
<arg choice="opt">--port<arg choice="plain">PORT</arg></arg>
79
<arg choice="opt">--priority<arg choice="plain">PRIORITY</arg></arg>
80
<arg choice="opt">--servicename<arg choice="plain">NAME</arg></arg>
81
<arg choice="opt">--configdir<arg choice="plain">DIRECTORY</arg></arg>
82
<arg choice="opt">--debug</arg>
85
<command>&COMMANDNAME;</command>
86
<arg choice="opt">-i<arg choice="plain">IF</arg></arg>
87
<arg choice="opt">-a<arg choice="plain">ADDRESS</arg></arg>
88
<arg choice="opt">-p<arg choice="plain">PORT</arg></arg>
89
<arg choice="opt">--priority<arg choice="plain">PRIORITY</arg></arg>
90
<arg choice="opt">--servicename<arg choice="plain">NAME</arg></arg>
91
<arg choice="opt">--configdir<arg choice="plain">DIRECTORY</arg></arg>
92
<arg choice="opt">--debug</arg>
95
<command>&COMMANDNAME;</command>
96
<arg choice="plain">--help</arg>
99
<command>&COMMANDNAME;</command>
100
<arg choice="plain">--version</arg>
103
<command>&COMMANDNAME;</command>
104
<arg choice="plain">--check</arg>
115
106
</refsynopsisdiv>
117
108
<refsect1 id="description">
118
109
<title>DESCRIPTION</title>
120
111
<command>&COMMANDNAME;</command> is a server daemon which
121
112
handles incoming request for passwords for a pre-defined list of
122
client host computers. For an introduction, see
123
<citerefentry><refentrytitle>intro</refentrytitle>
124
<manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server
125
uses Zeroconf to announce itself on the local network, and uses
126
TLS to communicate securely with and to authenticate the
127
clients. The Mandos server uses IPv6 to allow Mandos clients to
128
use IPv6 link-local addresses, since the clients will probably
129
not have any other addresses configured (see <xref
130
linkend="overview"/>). Any authenticated client is then given
131
the stored pre-encrypted password for that specific client.
113
client host computers. The Mandos server uses Zeroconf to
114
announce itself on the local network, and uses TLS to
115
communicate securely with and to authenticate the clients. The
116
Mandos server uses IPv6 to allow Mandos clients to use IPv6
117
link-local addresses, since the clients will probably not have
118
any other addresses configured (see <xref linkend="overview"/>).
119
Any authenticated client is then given the stored pre-encrypted
120
password for that specific client.
135
125
<refsect1 id="purpose">
136
126
<title>PURPOSE</title>
138
129
The purpose of this is to enable <emphasis>remote and unattended
139
130
rebooting</emphasis> of client host computer with an
140
131
<emphasis>encrypted root file system</emphasis>. See <xref
141
132
linkend="overview"/> for details.
145
137
<refsect1 id="options">
146
138
<title>OPTIONS</title>
149
<term><option>--help</option></term>
150
<term><option>-h</option></term>
142
<term><literal>-h</literal>, <literal>--help</literal></term>
153
145
Show a help message and exit
159
<term><option>--interface</option>
160
<replaceable>NAME</replaceable></term>
161
<term><option>-i</option>
162
<replaceable>NAME</replaceable></term>
164
<xi:include href="mandos-options.xml" xpointer="interface"/>
169
<term><option>--address
170
<replaceable>ADDRESS</replaceable></option></term>
172
<replaceable>ADDRESS</replaceable></option></term>
174
<xi:include href="mandos-options.xml" xpointer="address"/>
180
<replaceable>PORT</replaceable></option></term>
182
<replaceable>PORT</replaceable></option></term>
184
<xi:include href="mandos-options.xml" xpointer="port"/>
189
<term><option>--check</option></term>
151
<term><literal>-i</literal>, <literal>--interface <replaceable>
152
IF</replaceable></literal></term>
155
Only announce the server and listen to requests on network
156
interface <replaceable>IF</replaceable>. Default is to
157
use all available interfaces.
163
<term><literal>-a</literal>, <literal>--address <replaceable>
164
ADDRESS</replaceable></literal></term>
167
If this option is used, the server will only listen to a
168
specific address. This must currently be an IPv6 address;
169
an IPv4 address can be specified using the
170
<quote><literal>::FFFF:192.0.2.3</literal></quote> syntax.
171
Also, if a link-local address is specified, an interface
172
should be set, since a link-local address is only valid on
173
a single interface. By default, the server will listen to
174
all available addresses.
180
<term><literal>-p</literal>, <literal>--port <replaceable>
181
PORT</replaceable></literal></term>
184
If this option is used, the server to bind to that
185
port. By default, the server will listen to an arbitrary
186
port given by the operating system.
192
<term><literal>--check</literal></term>
192
195
Run the server’s self-tests. This includes any unit
199
<term><option>--debug</option></term>
201
<xi:include href="mandos-options.xml" xpointer="debug"/>
206
<term><option>--debuglevel
207
<replaceable>LEVEL</replaceable></option></term>
210
Set the debugging log level.
211
<replaceable>LEVEL</replaceable> is a string, one of
212
<quote><literal>CRITICAL</literal></quote>,
213
<quote><literal>ERROR</literal></quote>,
214
<quote><literal>WARNING</literal></quote>,
215
<quote><literal>INFO</literal></quote>, or
216
<quote><literal>DEBUG</literal></quote>, in order of
217
increasing verbosity. The default level is
218
<quote><literal>WARNING</literal></quote>.
224
<term><option>--priority <replaceable>
225
PRIORITY</replaceable></option></term>
227
<xi:include href="mandos-options.xml" xpointer="priority"/>
232
<term><option>--servicename
233
<replaceable>NAME</replaceable></option></term>
235
<xi:include href="mandos-options.xml"
236
xpointer="servicename"/>
241
<term><option>--configdir
242
<replaceable>DIRECTORY</replaceable></option></term>
202
<term><literal>--debug</literal></term>
205
If the server is run in debug mode, it will run in the
206
foreground and print a lot of debugging information. The
207
default is <emphasis>not</emphasis> to run in debug mode.
213
<term><literal>--priority <replaceable>
214
PRIORITY</replaceable></literal></term>
217
GnuTLS priority string for the TLS handshake with the
218
clients. The default is
219
<quote><literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal></quote>.
220
See <citerefentry><refentrytitle>gnutls_priority_init
221
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
222
for the syntax. <emphasis>Warning</emphasis>: changing
223
this may make the TLS handshake fail, making communication
224
with clients impossible.
230
<term><literal>--servicename <replaceable>NAME</replaceable>
234
Zeroconf service name. The default is
235
<quote><literal>Mandos</literal></quote>. You only need
236
to change this if you for some reason want to run more
237
than one server on the same <emphasis>host</emphasis>,
238
which would not normally be useful. If there are name
239
collisions on the same <emphasis>network</emphasis>, the
240
newer server will automatically rename itself to
241
<quote><literal>Mandos #2</literal></quote>, and so on;
242
therefore, this option is not needed in that case.
248
<term><literal>--configdir <replaceable>DIR</replaceable>
245
252
Directory to search for configuration files. Default is
355
338
</tbody></tgroup></table>
358
341
<refsect1 id="checking">
359
342
<title>CHECKING</title>
361
344
The server will, by default, continually check that the clients
362
345
are still up. If a client has not been confirmed as being up
363
346
for some time, the client is assumed to be compromised and is no
364
longer eligible to receive the encrypted password. (Manual
365
intervention is required to re-enable a client.) The timeout,
366
extended timeout, checker program, and interval between checks
367
can be configured both globally and per client; see
368
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
369
<manvolnum>5</manvolnum></citerefentry>. A client successfully
370
receiving its password will also be treated as a successful
375
<refsect1 id="approval">
376
<title>APPROVAL</title>
378
The server can be configured to require manual approval for a
379
client before it is sent its secret. The delay to wait for such
380
approval and the default action (approve or deny) can be
381
configured both globally and per client; see <citerefentry>
347
longer eligible to receive the encrypted password. The timeout,
348
checker program, and interval between checks can be configured
349
both globally and per client; see <citerefentry>
350
<refentrytitle>mandos.conf</refentrytitle>
351
<manvolnum>5</manvolnum></citerefentry> and <citerefentry>
382
352
<refentrytitle>mandos-clients.conf</refentrytitle>
383
<manvolnum>5</manvolnum></citerefentry>. By default all clients
384
will be approved immediately without delay.
387
This can be used to deny a client its secret if not manually
388
approved within a specified time. It can also be used to make
389
the server delay before giving a client its secret, allowing
390
optional manual denying of this specific client.
353
<manvolnum>5</manvolnum></citerefentry>.
395
357
<refsect1 id="logging">
396
358
<title>LOGGING</title>
398
The server will send log message with various severity levels to
399
<filename>/dev/log</filename>. With the
360
The server will send log messaged with various severity levels
361
to <filename>/dev/log</filename>. With the
400
362
<option>--debug</option> option, it will log even more messages,
401
363
and also show them on the console.
405
<refsect1 id="dbus_interface">
406
<title>D-BUS INTERFACE</title>
408
The server will by default provide a D-Bus system bus interface.
409
This interface will only be accessible by the root user or a
410
Mandos-specific user, if such a user exists. For documentation
411
of the D-Bus API, see the file <filename>DBUS-API</filename>.
415
367
<refsect1 id="exit_status">
416
368
<title>EXIT STATUS</title>
596
499
compromised if they are gone for too long.
599
If a client is compromised, its downtime should be duly noted
600
by the server which would therefore disable the client. But
601
if the server was ever restarted, it would re-read its client
602
list from its configuration file and again regard all clients
603
therein as enabled, and hence eligible to receive their
604
passwords. Therefore, be careful when restarting servers if
605
it is suspected that a client has, in fact, been compromised
606
by parties who may now be running a fake Mandos client with
607
the keys from the non-encrypted initial <acronym>RAM</acronym>
608
image of the client host. What should be done in that case
609
(if restarting the server program really is necessary) is to
610
stop the server program, edit the configuration file to omit
611
any suspect clients, and restart the server program.
614
502
For more details on client-side security, see
615
<citerefentry><refentrytitle>mandos-client</refentrytitle>
503
<citerefentry><refentrytitle>password-request</refentrytitle>
616
504
<manvolnum>8mandos</manvolnum></citerefentry>.
621
509
<refsect1 id="see_also">
622
510
<title>SEE ALSO</title>
624
<citerefentry><refentrytitle>intro</refentrytitle>
625
<manvolnum>8mandos</manvolnum></citerefentry>,
626
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
627
<manvolnum>5</manvolnum></citerefentry>,
628
<citerefentry><refentrytitle>mandos.conf</refentrytitle>
629
<manvolnum>5</manvolnum></citerefentry>,
630
<citerefentry><refentrytitle>mandos-client</refentrytitle>
631
<manvolnum>8mandos</manvolnum></citerefentry>,
632
<citerefentry><refentrytitle>sh</refentrytitle>
633
<manvolnum>1</manvolnum></citerefentry>
515
<refentrytitle>password-request</refentrytitle>
516
<manvolnum>8mandos</manvolnum>
521
This is the actual program which talks to this server.
522
Note that it is normally not invoked directly, and is only
523
run in the initial RAM disk environment, and not on a
524
fully started system.
638
530
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
673
RFC 4291: <citetitle>IP Version 6 Addressing
674
Architecture</citetitle>
565
<citation>RFC 4291: <citetitle>IP Version 6 Addressing
566
Architecture</citetitle>, section 2.5.6, Link-Local IPv6
567
Unicast Addresses</citation>
679
<term>Section 2.2: <citetitle>Text Representation of
680
Addresses</citetitle></term>
681
<listitem><para/></listitem>
684
<term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
685
Address</citetitle></term>
686
<listitem><para/></listitem>
689
<term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
690
Addresses</citetitle></term>
693
The clients use IPv6 link-local addresses, which are
694
immediately usable since a link-local addresses is
695
automatically assigned to a network interfaces when it
571
The clients use IPv6 link-local addresses, which are
572
immediately usable since a link-local addresses is
573
automatically assigned to a network interfaces when it is
705
RFC 4346: <citetitle>The Transport Layer Security (TLS)
706
Protocol Version 1.1</citetitle>
580
<citation>RFC 4346: <citetitle>The Transport Layer Security
581
(TLS) Protocol Version 1.1</citetitle></citation>