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 "2019-02-09">
6
<!ENTITY % common SYSTEM "common.ent">
6
<!ENTITY TIMESTAMP "2008-08-29">
10
9
<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>
13
<productname>&COMMANDNAME;</productname>
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>
45
34
<holder>Teddy Hogeborn</holder>
46
35
<holder>Björn Påhlsson</holder>
48
<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/"/>.
52
63
<refentrytitle>&COMMANDNAME;</refentrytitle>
53
64
<manvolnum>8</manvolnum>
57
68
<refname><command>&COMMANDNAME;</command></refname>
59
Gives encrypted passwords to authenticated Mandos clients
70
Sends encrypted passwords to authenticated Mandos clients
65
76
<command>&COMMANDNAME;</command>
67
<arg choice="plain"><option>--interface
68
<replaceable>NAME</replaceable></option></arg>
69
<arg choice="plain"><option>-i
70
<replaceable>NAME</replaceable></option></arg>
74
<arg choice="plain"><option>--address
75
<replaceable>ADDRESS</replaceable></option></arg>
76
<arg choice="plain"><option>-a
77
<replaceable>ADDRESS</replaceable></option></arg>
81
<arg choice="plain"><option>--port
82
<replaceable>PORT</replaceable></option></arg>
83
<arg choice="plain"><option>-p
84
<replaceable>PORT</replaceable></option></arg>
87
<arg><option>--priority
88
<replaceable>PRIORITY</replaceable></option></arg>
90
<arg><option>--servicename
91
<replaceable>NAME</replaceable></option></arg>
93
<arg><option>--configdir
94
<replaceable>DIRECTORY</replaceable></option></arg>
96
<arg><option>--debug</option></arg>
98
<arg><option>--debuglevel
99
<replaceable>LEVEL</replaceable></option></arg>
101
<arg><option>--no-dbus</option></arg>
103
<arg><option>--no-ipv6</option></arg>
105
<arg><option>--no-restore</option></arg>
107
<arg><option>--statedir
108
<replaceable>DIRECTORY</replaceable></option></arg>
110
<arg><option>--socket
111
<replaceable>FD</replaceable></option></arg>
113
<arg><option>--foreground</option></arg>
115
<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>
118
96
<command>&COMMANDNAME;</command>
119
97
<group choice="req">
120
<arg choice="plain"><option>--help</option></arg>
121
<arg choice="plain"><option>-h</option></arg>
98
<arg choice="plain">-h</arg>
99
<arg choice="plain">--help</arg>
125
103
<command>&COMMANDNAME;</command>
126
<arg choice="plain"><option>--version</option></arg>
104
<arg choice="plain">--version</arg>
129
107
<command>&COMMANDNAME;</command>
130
<arg choice="plain"><option>--check</option></arg>
108
<arg choice="plain">--check</arg>
132
110
</refsynopsisdiv>
134
112
<refsect1 id="description">
135
113
<title>DESCRIPTION</title>
137
115
<command>&COMMANDNAME;</command> is a server daemon which
138
116
handles incoming request for passwords for a pre-defined list of
139
client host computers. For an introduction, see
140
<citerefentry><refentrytitle>intro</refentrytitle>
141
<manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server
142
uses Zeroconf to announce itself on the local network, and uses
143
TLS to communicate securely with and to authenticate the
144
clients. The Mandos server uses IPv6 to allow Mandos clients to
145
use IPv6 link-local addresses, since the clients will probably
146
not have any other addresses configured (see <xref
147
linkend="overview"/>). Any authenticated client is then given
148
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.
152
129
<refsect1 id="purpose">
153
130
<title>PURPOSE</title>
155
133
The purpose of this is to enable <emphasis>remote and unattended
156
134
rebooting</emphasis> of client host computer with an
157
135
<emphasis>encrypted root file system</emphasis>. See <xref
158
136
linkend="overview"/> for details.
162
141
<refsect1 id="options">
163
142
<title>OPTIONS</title>
166
<term><option>--help</option></term>
167
<term><option>-h</option></term>
146
<term><literal>-h</literal>, <literal>--help</literal></term>
170
149
Show a help message and exit
176
<term><option>--interface</option>
177
<replaceable>NAME</replaceable></term>
178
<term><option>-i</option>
179
<replaceable>NAME</replaceable></term>
155
<term><literal>-i</literal>, <literal>--interface <replaceable
156
>NAME</replaceable></literal></term>
181
158
<xi:include href="mandos-options.xml" xpointer="interface"/>
186
<term><option>--address
187
<replaceable>ADDRESS</replaceable></option></term>
189
<replaceable>ADDRESS</replaceable></option></term>
163
<term><literal>-a</literal>, <literal>--address <replaceable>
164
ADDRESS</replaceable></literal></term>
191
166
<xi:include href="mandos-options.xml" xpointer="address"/>
197
<replaceable>PORT</replaceable></option></term>
199
<replaceable>PORT</replaceable></option></term>
171
<term><literal>-p</literal>, <literal>--port <replaceable>
172
PORT</replaceable></literal></term>
201
174
<xi:include href="mandos-options.xml" xpointer="port"/>
206
<term><option>--check</option></term>
179
<term><literal>--check</literal></term>
209
182
Run the server’s self-tests. This includes any unit
216
<term><option>--debug</option></term>
189
<term><literal>--debug</literal></term>
218
191
<xi:include href="mandos-options.xml" xpointer="debug"/>
223
<term><option>--debuglevel
224
<replaceable>LEVEL</replaceable></option></term>
227
Set the debugging log level.
228
<replaceable>LEVEL</replaceable> is a string, one of
229
<quote><literal>CRITICAL</literal></quote>,
230
<quote><literal>ERROR</literal></quote>,
231
<quote><literal>WARNING</literal></quote>,
232
<quote><literal>INFO</literal></quote>, or
233
<quote><literal>DEBUG</literal></quote>, in order of
234
increasing verbosity. The default level is
235
<quote><literal>WARNING</literal></quote>.
241
<term><option>--priority <replaceable>
242
PRIORITY</replaceable></option></term>
196
<term><literal>--priority <replaceable>
197
PRIORITY</replaceable></literal></term>
244
199
<xi:include href="mandos-options.xml" xpointer="priority"/>
249
<term><option>--servicename
250
<replaceable>NAME</replaceable></option></term>
204
<term><literal>--servicename <replaceable>NAME</replaceable>
252
207
<xi:include href="mandos-options.xml"
253
208
xpointer="servicename"/>
258
<term><option>--configdir
259
<replaceable>DIRECTORY</replaceable></option></term>
213
<term><literal>--configdir <replaceable>DIR</replaceable>
262
217
Directory to search for configuration files. Default is
273
<term><option>--version</option></term>
228
<term><literal>--version</literal></term>
276
231
Prints the program version and exit.
282
<term><option>--no-dbus</option></term>
284
<xi:include href="mandos-options.xml" xpointer="dbus"/>
286
See also <xref linkend="dbus_interface"/>.
292
<term><option>--no-ipv6</option></term>
294
<xi:include href="mandos-options.xml" xpointer="ipv6"/>
299
<term><option>--no-restore</option></term>
301
<xi:include href="mandos-options.xml" xpointer="restore"/>
303
See also <xref linkend="persistent_state"/>.
309
<term><option>--statedir
310
<replaceable>DIRECTORY</replaceable></option></term>
312
<xi:include href="mandos-options.xml" xpointer="statedir"/>
317
<term><option>--socket
318
<replaceable>FD</replaceable></option></term>
320
<xi:include href="mandos-options.xml" xpointer="socket"/>
325
<term><option>--foreground</option></term>
327
<xi:include href="mandos-options.xml"
328
xpointer="foreground"/>
333
<term><option>--no-zeroconf</option></term>
335
<xi:include href="mandos-options.xml" xpointer="zeroconf"/>
342
238
<refsect1 id="overview">
343
239
<title>OVERVIEW</title>
344
240
<xi:include href="overview.xml"/>
346
242
This program is the server part. It is a normal server program
347
243
and will run in a normal system environment, not in an initial
348
<acronym>RAM</acronym> disk environment.
244
RAM disk environment.
352
248
<refsect1 id="protocol">
353
249
<title>NETWORK PROTOCOL</title>
407
303
</tbody></tgroup></table>
410
306
<refsect1 id="checking">
411
307
<title>CHECKING</title>
413
309
The server will, by default, continually check that the clients
414
310
are still up. If a client has not been confirmed as being up
415
311
for some time, the client is assumed to be compromised and is no
416
longer eligible to receive the encrypted password. (Manual
417
intervention is required to re-enable a client.) The timeout,
418
extended timeout, checker program, and interval between checks
419
can be configured both globally and per client; see
420
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
312
longer eligible to receive the encrypted password. The timeout,
313
checker program, and interval between checks can be configured
314
both globally and per client; see <citerefentry>
315
<refentrytitle>mandos-clients.conf</refentrytitle>
421
316
<manvolnum>5</manvolnum></citerefentry>.
425
<refsect1 id="approval">
426
<title>APPROVAL</title>
428
The server can be configured to require manual approval for a
429
client before it is sent its secret. The delay to wait for such
430
approval and the default action (approve or deny) can be
431
configured both globally and per client; see <citerefentry>
432
<refentrytitle>mandos-clients.conf</refentrytitle>
433
<manvolnum>5</manvolnum></citerefentry>. By default all clients
434
will be approved immediately without delay.
437
This can be used to deny a client its secret if not manually
438
approved within a specified time. It can also be used to make
439
the server delay before giving a client its secret, allowing
440
optional manual denying of this specific client.
445
320
<refsect1 id="logging">
446
321
<title>LOGGING</title>
448
323
The server will send log message with various severity levels to
449
<filename class="devicefile">/dev/log</filename>. With the
324
<filename>/dev/log</filename>. With the
450
325
<option>--debug</option> option, it will log even more messages,
451
326
and also show them on the console.
455
<refsect1 id="persistent_state">
456
<title>PERSISTENT STATE</title>
458
Client settings, initially read from
459
<filename>clients.conf</filename>, are persistent across
460
restarts, and run-time changes will override settings in
461
<filename>clients.conf</filename>. However, if a setting is
462
<emphasis>changed</emphasis> (or a client added, or removed) in
463
<filename>clients.conf</filename>, this will take precedence.
467
<refsect1 id="dbus_interface">
468
<title>D-BUS INTERFACE</title>
470
The server will by default provide a D-Bus system bus interface.
471
This interface will only be accessible by the root user or a
472
Mandos-specific user, if such a user exists. For documentation
473
of the D-Bus API, see the file <filename>DBUS-API</filename>.
477
330
<refsect1 id="exit_status">
478
331
<title>EXIT STATUS</title>
627
481
</informalexample>
630
484
<refsect1 id="security">
631
485
<title>SECURITY</title>
632
<refsect2 id="server">
486
<refsect2 id="SERVER">
633
487
<title>SERVER</title>
635
489
Running this <command>&COMMANDNAME;</command> server program
636
490
should not in itself present any security risk to the host
637
computer running it. The program switches to a non-root user
491
computer running it. The program does not need any special
492
privileges to run, and is designed to run as a non-root user.
641
<refsect2 id="clients">
495
<refsect2 id="CLIENTS">
642
496
<title>CLIENTS</title>
644
498
The server only gives out its stored data to clients which
645
does have the correct key ID of the stored key ID. This is
646
guaranteed by the fact that the client sends its public key in
647
the TLS handshake; this ensures it to be genuine. The server
648
computes the key ID of the key itself and looks up the key ID
649
in its list of clients. The <filename>clients.conf</filename>
499
does have the OpenPGP key of the stored fingerprint. This is
500
guaranteed by the fact that the client sends its OpenPGP
501
public key in the TLS handshake; this ensures it to be
502
genuine. The server computes the fingerprint of the key
503
itself and looks up the fingerprint in its list of
504
clients. The <filename>clients.conf</filename> file (see
651
505
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
652
506
<manvolnum>5</manvolnum></citerefentry>)
653
507
<emphasis>must</emphasis> be made non-readable by anyone
654
except the user starting the server (usually root).
508
except the user running the server.
657
511
As detailed in <xref linkend="checking"/>, the status of all
659
513
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
662
532
For more details on client-side security, see
663
<citerefentry><refentrytitle>mandos-client</refentrytitle>
533
<citerefentry><refentrytitle>password-request</refentrytitle>
664
534
<manvolnum>8mandos</manvolnum></citerefentry>.
669
539
<refsect1 id="see_also">
670
540
<title>SEE ALSO</title>
672
<citerefentry><refentrytitle>intro</refentrytitle>
673
<manvolnum>8mandos</manvolnum></citerefentry>,
674
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
675
<manvolnum>5</manvolnum></citerefentry>,
676
<citerefentry><refentrytitle>mandos.conf</refentrytitle>
677
<manvolnum>5</manvolnum></citerefentry>,
678
<citerefentry><refentrytitle>mandos-client</refentrytitle>
679
<manvolnum>8mandos</manvolnum></citerefentry>,
680
<citerefentry><refentrytitle>sh</refentrytitle>
681
<manvolnum>1</manvolnum></citerefentry>
543
<refentrytitle>mandos.conf</refentrytitle>
544
<manvolnum>5</manvolnum></citerefentry>, <citerefentry>
545
<refentrytitle>mandos-clients.conf</refentrytitle>
546
<manvolnum>5</manvolnum></citerefentry>, <citerefentry>
547
<refentrytitle>password-request</refentrytitle>
548
<manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
549
<refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>