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">
5
4
<!ENTITY COMMANDNAME "mandos">
5
<!ENTITY TIMESTAMP "2010-09-26">
6
<!ENTITY % common SYSTEM "common.ent">
8
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
<title>&COMMANDNAME;</title>
12
<title>Mandos Manual</title>
11
13
<!-- NWalsh’s docbook scripts use this to generate the footer: -->
12
<productname>&COMMANDNAME;</productname>
13
<productnumber>&VERSION;</productnumber>
14
<productname>Mandos</productname>
15
<productnumber>&version;</productnumber>
16
<date>&TIMESTAMP;</date>
16
19
<firstname>Björn</firstname>
32
37
<holder>Teddy Hogeborn</holder>
33
38
<holder>Björn Påhlsson</holder>
37
This manual page is free software: you can redistribute it
38
and/or modify it under the terms of the GNU General Public
39
License as published by the Free Software Foundation,
40
either version 3 of the License, or (at your option) any
45
This manual page is distributed in the hope that it will
46
be useful, but WITHOUT ANY WARRANTY; without even the
47
implied warranty of MERCHANTABILITY or FITNESS FOR A
48
PARTICULAR PURPOSE. See the GNU General Public License
53
You should have received a copy of the GNU General Public
54
License along with this program; If not, see
55
<ulink url="http://www.gnu.org/licenses/"/>.
40
<xi:include href="legalnotice.xml"/>
61
44
<refentrytitle>&COMMANDNAME;</refentrytitle>
62
45
<manvolnum>8</manvolnum>
66
49
<refname><command>&COMMANDNAME;</command></refname>
68
Sends encrypted passwords to authenticated Mandos clients
51
Gives encrypted passwords to authenticated Mandos clients
74
57
<command>&COMMANDNAME;</command>
75
<arg>--interface<arg choice="plain">IF</arg></arg>
76
<arg>--address<arg choice="plain">ADDRESS</arg></arg>
77
<arg>--port<arg choice="plain">PORT</arg></arg>
78
<arg>--priority<arg choice="plain">PRIORITY</arg></arg>
79
<arg>--servicename<arg choice="plain">NAME</arg></arg>
80
<arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
84
<command>&COMMANDNAME;</command>
85
<arg>-i<arg choice="plain">IF</arg></arg>
86
<arg>-a<arg choice="plain">ADDRESS</arg></arg>
87
<arg>-p<arg choice="plain">PORT</arg></arg>
88
<arg>--priority<arg choice="plain">PRIORITY</arg></arg>
89
<arg>--servicename<arg choice="plain">NAME</arg></arg>
90
<arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
59
<arg choice="plain"><option>--interface
60
<replaceable>NAME</replaceable></option></arg>
61
<arg choice="plain"><option>-i
62
<replaceable>NAME</replaceable></option></arg>
66
<arg choice="plain"><option>--address
67
<replaceable>ADDRESS</replaceable></option></arg>
68
<arg choice="plain"><option>-a
69
<replaceable>ADDRESS</replaceable></option></arg>
73
<arg choice="plain"><option>--port
74
<replaceable>PORT</replaceable></option></arg>
75
<arg choice="plain"><option>-p
76
<replaceable>PORT</replaceable></option></arg>
79
<arg><option>--priority
80
<replaceable>PRIORITY</replaceable></option></arg>
82
<arg><option>--servicename
83
<replaceable>NAME</replaceable></option></arg>
85
<arg><option>--configdir
86
<replaceable>DIRECTORY</replaceable></option></arg>
88
<arg><option>--debug</option></arg>
90
<arg><option>--no-dbus</option></arg>
92
<arg><option>--no-ipv6</option></arg>
94
95
<command>&COMMANDNAME;</command>
95
96
<group choice="req">
96
<arg choice="plain">-h</arg>
97
<arg choice="plain">--help</arg>
97
<arg choice="plain"><option>--help</option></arg>
98
<arg choice="plain"><option>-h</option></arg>
101
102
<command>&COMMANDNAME;</command>
102
<arg choice="plain">--version</arg>
103
<arg choice="plain"><option>--version</option></arg>
105
106
<command>&COMMANDNAME;</command>
106
<arg choice="plain">--check</arg>
107
<arg choice="plain"><option>--check</option></arg>
108
109
</refsynopsisdiv>
110
111
<refsect1 id="description">
111
112
<title>DESCRIPTION</title>
121
122
Any authenticated client is then given the stored pre-encrypted
122
123
password for that specific client.
127
127
<refsect1 id="purpose">
128
128
<title>PURPOSE</title>
131
130
The purpose of this is to enable <emphasis>remote and unattended
132
131
rebooting</emphasis> of client host computer with an
133
132
<emphasis>encrypted root file system</emphasis>. See <xref
134
133
linkend="overview"/> for details.
139
137
<refsect1 id="options">
140
138
<title>OPTIONS</title>
144
<term><literal>-h</literal>, <literal>--help</literal></term>
141
<term><option>--help</option></term>
142
<term><option>-h</option></term>
147
145
Show a help message and exit
153
<term><literal>-i</literal>, <literal>--interface <replaceable>
154
IF</replaceable></literal></term>
151
<term><option>--interface</option>
152
<replaceable>NAME</replaceable></term>
153
<term><option>-i</option>
154
<replaceable>NAME</replaceable></term>
156
156
<xi:include href="mandos-options.xml" xpointer="interface"/>
161
<term><literal>-a</literal>, <literal>--address <replaceable>
162
ADDRESS</replaceable></literal></term>
161
<term><option>--address
162
<replaceable>ADDRESS</replaceable></option></term>
164
<replaceable>ADDRESS</replaceable></option></term>
164
166
<xi:include href="mandos-options.xml" xpointer="address"/>
169
<term><literal>-p</literal>, <literal>--port <replaceable>
170
PORT</replaceable></literal></term>
172
<replaceable>PORT</replaceable></option></term>
174
<replaceable>PORT</replaceable></option></term>
172
176
<xi:include href="mandos-options.xml" xpointer="port"/>
177
<term><literal>--check</literal></term>
181
<term><option>--check</option></term>
180
184
Run the server’s self-tests. This includes any unit
187
<term><literal>--debug</literal></term>
191
<term><option>--debug</option></term>
189
193
<xi:include href="mandos-options.xml" xpointer="debug"/>
194
<term><literal>--priority <replaceable>
195
PRIORITY</replaceable></literal></term>
198
<term><option>--priority <replaceable>
199
PRIORITY</replaceable></option></term>
197
201
<xi:include href="mandos-options.xml" xpointer="priority"/>
202
<term><literal>--servicename <replaceable>NAME</replaceable>
206
<term><option>--servicename
207
<replaceable>NAME</replaceable></option></term>
205
209
<xi:include href="mandos-options.xml"
206
210
xpointer="servicename"/>
211
<term><literal>--configdir <replaceable>DIR</replaceable>
215
<term><option>--configdir
216
<replaceable>DIRECTORY</replaceable></option></term>
215
219
Directory to search for configuration files. Default is
226
<term><literal>--version</literal></term>
230
<term><option>--version</option></term>
229
233
Prints the program version and exit.
239
<term><option>--no-dbus</option></term>
241
<xi:include href="mandos-options.xml" xpointer="dbus"/>
243
See also <xref linkend="dbus_interface"/>.
249
<term><option>--no-ipv6</option></term>
251
<xi:include href="mandos-options.xml" xpointer="ipv6"/>
236
257
<refsect1 id="overview">
237
258
<title>OVERVIEW</title>
238
259
<xi:include href="overview.xml"/>
240
261
This program is the server part. It is a normal server program
241
262
and will run in a normal system environment, not in an initial
242
RAM disk environment.
263
<acronym>RAM</acronym> disk environment.
246
267
<refsect1 id="protocol">
247
268
<title>NETWORK PROTOCOL</title>
301
322
</tbody></tgroup></table>
304
325
<refsect1 id="checking">
305
326
<title>CHECKING</title>
307
328
The server will, by default, continually check that the clients
308
329
are still up. If a client has not been confirmed as being up
309
330
for some time, the client is assumed to be compromised and is no
310
longer eligible to receive the encrypted password. The timeout,
331
longer eligible to receive the encrypted password. (Manual
332
intervention is required to re-enable a client.) The timeout,
311
333
checker program, and interval between checks can be configured
312
334
both globally and per client; see <citerefentry>
313
<refentrytitle>mandos.conf</refentrytitle>
314
<manvolnum>5</manvolnum></citerefentry> and <citerefentry>
315
<refentrytitle>mandos-clients.conf</refentrytitle>
316
<manvolnum>5</manvolnum></citerefentry>.
335
<refentrytitle>mandos-clients.conf</refentrytitle>
336
<manvolnum>5</manvolnum></citerefentry>. A client successfully
337
receiving its password will also be treated as a successful
342
<refsect1 id="approval">
343
<title>APPROVAL</title>
345
The server can be configured to require manual approval for a
346
client before it is sent its secret. The delay to wait for such
347
approval and the default action (approve or deny) can be
348
configured both globally and per client; see <citerefentry>
349
<refentrytitle>mandos-clients.conf</refentrytitle>
350
<manvolnum>5</manvolnum></citerefentry>. By default all clients
351
will be approved immediately without delay.
354
This can be used to deny a client its secret if not manually
355
approved within a specified time. It can also be used to make
356
the server delay before giving a client its secret, allowing
357
optional manual denying of this specific client.
320
362
<refsect1 id="logging">
321
363
<title>LOGGING</title>
323
The server will send log messaged with various severity levels
324
to <filename>/dev/log</filename>. With the
365
The server will send log message with various severity levels to
366
<filename>/dev/log</filename>. With the
325
367
<option>--debug</option> option, it will log even more messages,
326
368
and also show them on the console.
372
<refsect1 id="dbus_interface">
373
<title>D-BUS INTERFACE</title>
375
The server will by default provide a D-Bus system bus interface.
376
This interface will only be accessible by the root user or a
377
Mandos-specific user, if such a user exists. For documentation
378
of the D-Bus API, see the file <filename>DBUS-API</filename>.
330
382
<refsect1 id="exit_status">
331
383
<title>EXIT STATUS</title>
422
474
backtrace. This could be considered a feature.
425
Currently, if a client is declared <quote>invalid</quote> due to
426
having timed out, the server does not record this fact onto
427
permanent storage. This has some security implications, see
428
<xref linkend="CLIENTS"/>.
431
There is currently no way of querying the server of the current
432
status of clients, other than analyzing its <systemitem
433
class="service">syslog</systemitem> output.
477
Currently, if a client is disabled due to having timed out, the
478
server does not record this fact onto permanent storage. This
479
has some security implications, see <xref linkend="clients"/>.
436
482
There is no fine-grained control over logging and debug output.
477
527
<!-- do not wrap this line -->
478
<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
528
<userinput>&COMMANDNAME; --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
481
531
</informalexample>
484
534
<refsect1 id="security">
485
535
<title>SECURITY</title>
486
<refsect2 id="SERVER">
536
<refsect2 id="server">
487
537
<title>SERVER</title>
489
539
Running this <command>&COMMANDNAME;</command> server program
490
540
should not in itself present any security risk to the host
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.
541
computer running it. The program switches to a non-root user
495
<refsect2 id="CLIENTS">
545
<refsect2 id="clients">
496
546
<title>CLIENTS</title>
498
548
The server only gives out its stored data to clients which
516
566
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
567
by the server which would therefore disable the client. But
568
if the server was ever restarted, it would re-read its client
569
list from its configuration file and again regard all clients
570
therein as enabled, and hence eligible to receive their
571
passwords. Therefore, be careful when restarting servers if
572
it is suspected that a client has, in fact, been compromised
573
by parties who may now be running a fake Mandos client with
574
the keys from the non-encrypted initial <acronym>RAM</acronym>
575
image of the client host. What should be done in that case
576
(if restarting the server program really is necessary) is to
577
stop the server program, edit the configuration file to omit
578
any suspect clients, and restart the server program.
532
581
For more details on client-side security, see
533
<citerefentry><refentrytitle>password-request</refentrytitle>
582
<citerefentry><refentrytitle>mandos-client</refentrytitle>
534
583
<manvolnum>8mandos</manvolnum></citerefentry>.
539
588
<refsect1 id="see_also">
540
589
<title>SEE ALSO</title>
592
<refentrytitle>mandos-clients.conf</refentrytitle>
593
<manvolnum>5</manvolnum></citerefentry>, <citerefentry>
594
<refentrytitle>mandos.conf</refentrytitle>
595
<manvolnum>5</manvolnum></citerefentry>, <citerefentry>
596
<refentrytitle>mandos-client</refentrytitle>
597
<manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
598
<refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
545
<refentrytitle>password-request</refentrytitle>
546
<manvolnum>8mandos</manvolnum>
551
This is the actual program which talks to this server.
552
Note that it is normally not invoked directly, and is only
553
run in the initial RAM disk environment, and not on a
554
fully started system.
560
604
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
595
<citation>RFC 4291: <citetitle>IP Version 6 Addressing
596
Architecture</citetitle>, section 2.5.6, Link-Local IPv6
597
Unicast Addresses</citation>
639
RFC 4291: <citetitle>IP Version 6 Addressing
640
Architecture</citetitle>
601
The clients use IPv6 link-local addresses, which are
602
immediately usable since a link-local addresses is
603
automatically assigned to a network interfaces when it is
645
<term>Section 2.2: <citetitle>Text Representation of
646
Addresses</citetitle></term>
647
<listitem><para/></listitem>
650
<term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
651
Address</citetitle></term>
652
<listitem><para/></listitem>
655
<term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
656
Addresses</citetitle></term>
659
The clients use IPv6 link-local addresses, which are
660
immediately usable since a link-local addresses is
661
automatically assigned to a network interfaces when it
610
<citation>RFC 4346: <citetitle>The Transport Layer Security
611
(TLS) Protocol Version 1.1</citetitle></citation>
671
RFC 4346: <citetitle>The Transport Layer Security (TLS)
672
Protocol Version 1.1</citetitle>