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 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>
40
33
<holder>Teddy Hogeborn</holder>
41
34
<holder>Björn Påhlsson</holder>
43
<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/"/>.
47
62
<refentrytitle>&COMMANDNAME;</refentrytitle>
48
63
<manvolnum>8</manvolnum>
52
67
<refname><command>&COMMANDNAME;</command></refname>
54
Gives encrypted passwords to authenticated Mandos clients
69
Sends encrypted passwords to authenticated Mandos clients
60
75
<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>
113
<command>&COMMANDNAME;</command>
115
<arg choice="plain"><option>--help</option></arg>
116
<arg choice="plain"><option>-h</option></arg>
120
<command>&COMMANDNAME;</command>
121
<arg choice="plain"><option>--version</option></arg>
124
<command>&COMMANDNAME;</command>
125
<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>
127
106
</refsynopsisdiv>
129
108
<refsect1 id="description">
130
109
<title>DESCRIPTION</title>
132
111
<command>&COMMANDNAME;</command> is a server daemon which
133
112
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.
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.
147
125
<refsect1 id="purpose">
148
126
<title>PURPOSE</title>
150
129
The purpose of this is to enable <emphasis>remote and unattended
151
130
rebooting</emphasis> of client host computer with an
152
131
<emphasis>encrypted root file system</emphasis>. See <xref
153
132
linkend="overview"/> for details.
157
137
<refsect1 id="options">
158
138
<title>OPTIONS</title>
161
<term><option>--help</option></term>
162
<term><option>-h</option></term>
142
<term><literal>-h</literal>, <literal>--help</literal></term>
165
145
Show a help message and exit
171
<term><option>--interface</option>
172
<replaceable>NAME</replaceable></term>
173
<term><option>-i</option>
174
<replaceable>NAME</replaceable></term>
176
<xi:include href="mandos-options.xml" xpointer="interface"/>
181
<term><option>--address
182
<replaceable>ADDRESS</replaceable></option></term>
184
<replaceable>ADDRESS</replaceable></option></term>
186
<xi:include href="mandos-options.xml" xpointer="address"/>
192
<replaceable>PORT</replaceable></option></term>
194
<replaceable>PORT</replaceable></option></term>
196
<xi:include href="mandos-options.xml" xpointer="port"/>
201
<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>
204
195
Run the server’s self-tests. This includes any unit
211
<term><option>--debug</option></term>
213
<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>
239
<xi:include href="mandos-options.xml" xpointer="priority"/>
244
<term><option>--servicename
245
<replaceable>NAME</replaceable></option></term>
247
<xi:include href="mandos-options.xml"
248
xpointer="servicename"/>
253
<term><option>--configdir
254
<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>
257
252
Directory to search for configuration files. Default is
268
<term><option>--version</option></term>
263
<term><literal>--version</literal></term>
271
266
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
273
<refsect1 id="overview">
338
274
<title>OVERVIEW</title>
339
<xi:include href="overview.xml"/>
341
277
This program is the server part. It is a normal server program
342
278
and will run in a normal system environment, not in an initial
343
<acronym>RAM</acronym> disk environment.
279
RAM disk environment.
347
283
<refsect1 id="protocol">
348
284
<title>NETWORK PROTOCOL</title>
402
338
</tbody></tgroup></table>
405
341
<refsect1 id="checking">
406
342
<title>CHECKING</title>
408
344
The server will, by default, continually check that the clients
409
345
are still up. If a client has not been confirmed as being up
410
346
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>
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>
352
<refentrytitle>mandos-clients.conf</refentrytitle>
416
353
<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
357
<refsect1 id="logging">
441
358
<title>LOGGING</title>
443
The server will send log message with various severity levels to
444
<filename class="devicefile">/dev/log</filename>. With the
360
The server will send log messaged with various severity levels
361
to <filename>/dev/log</filename>. With the
445
362
<option>--debug</option> option, it will log even more messages,
446
363
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
367
<refsect1 id="exit_status">
473
368
<title>EXIT STATUS</title>
565
<term><filename>/bin/sh</filename></term>
568
This is used to start the configured checker command for
569
each client. See <citerefentry>
570
<refentrytitle>mandos-clients.conf</refentrytitle>
571
<manvolnum>5</manvolnum></citerefentry> for details.
578
424
<refsect1 id="bugs">
579
425
<title>BUGS</title>
581
427
This server might, on especially fatal errors, emit a Python
582
428
backtrace. This could be considered a feature.
585
There is no fine-grained control over logging and debug output.
588
This server does not check the expire time of clients’ OpenPGP
593
<refsect1 id="example">
594
<title>EXAMPLE</title>
432
<refsect1 id="examples">
433
<title>EXAMPLES</title>
595
434
<informalexample>
597
436
Normal invocation needs no options:
600
<userinput>&COMMANDNAME;</userinput>
439
<userinput>mandos</userinput>
602
441
</informalexample>
603
442
<informalexample>
605
444
Run the server in debug mode, read configuration files from
606
the <filename class="directory">~/mandos</filename> directory,
607
and use the Zeroconf service name <quote>Test</quote> to not
608
collide with any other official Mandos server on this host:
445
the <filename>~/mandos</filename> directory, and use the
446
Zeroconf service name <quote>Test</quote> to not collide with
447
any other official Mandos server on this host:
612
451
<!-- do not wrap this line -->
613
<userinput>&COMMANDNAME; --debug --configdir ~/mandos --servicename Test</userinput>
452
<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>
616
455
</informalexample>
663
502
For more details on client-side security, see
664
<citerefentry><refentrytitle>mandos-client</refentrytitle>
503
<citerefentry><refentrytitle>password-request</refentrytitle>
665
504
<manvolnum>8mandos</manvolnum></citerefentry>.
670
509
<refsect1 id="see_also">
671
510
<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>
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.
687
530
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
721
RFC 4291: <citetitle>IP Version 6 Addressing
722
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>
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
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
753
RFC 5246: <citetitle>The Transport Layer Security (TLS)
754
Protocol Version 1.2</citetitle>
580
<citation>RFC 4346: <citetitle>The Transport Layer Security
581
(TLS) Protocol Version 1.1</citetitle></citation>
758
TLS 1.2 is the protocol implemented by GnuTLS.
585
TLS 1.1 is the protocol implemented by GnuTLS.
764
RFC 4880: <citetitle>OpenPGP Message Format</citetitle>
591
<citation>RFC 4880: <citetitle>OpenPGP Message
592
Format</citetitle></citation>