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 "2009-01-04">
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>
36
33
<holder>Teddy Hogeborn</holder>
37
34
<holder>Björn Påhlsson</holder>
39
<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/"/>.
43
62
<refentrytitle>&COMMANDNAME;</refentrytitle>
44
63
<manvolnum>8</manvolnum>
48
67
<refname><command>&COMMANDNAME;</command></refname>
50
Gives encrypted passwords to authenticated Mandos clients
69
Sends encrypted passwords to authenticated Mandos clients
56
75
<command>&COMMANDNAME;</command>
58
<arg choice="plain"><option>--interface
59
<replaceable>NAME</replaceable></option></arg>
60
<arg choice="plain"><option>-i
61
<replaceable>NAME</replaceable></option></arg>
65
<arg choice="plain"><option>--address
66
<replaceable>ADDRESS</replaceable></option></arg>
67
<arg choice="plain"><option>-a
68
<replaceable>ADDRESS</replaceable></option></arg>
72
<arg choice="plain"><option>--port
73
<replaceable>PORT</replaceable></option></arg>
74
<arg choice="plain"><option>-p
75
<replaceable>PORT</replaceable></option></arg>
78
<arg><option>--priority
79
<replaceable>PRIORITY</replaceable></option></arg>
81
<arg><option>--servicename
82
<replaceable>NAME</replaceable></option></arg>
84
<arg><option>--configdir
85
<replaceable>DIRECTORY</replaceable></option></arg>
87
<arg><option>--debug</option></arg>
89
<arg><option>--no-dbus</option></arg>
92
<command>&COMMANDNAME;</command>
94
<arg choice="plain"><option>--help</option></arg>
95
<arg choice="plain"><option>-h</option></arg>
99
<command>&COMMANDNAME;</command>
100
<arg choice="plain"><option>--version</option></arg>
103
<command>&COMMANDNAME;</command>
104
<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>
106
106
</refsynopsisdiv>
108
108
<refsect1 id="description">
109
109
<title>DESCRIPTION</title>
119
119
Any authenticated client is then given the stored pre-encrypted
120
120
password for that specific client.
124
125
<refsect1 id="purpose">
125
126
<title>PURPOSE</title>
127
129
The purpose of this is to enable <emphasis>remote and unattended
128
130
rebooting</emphasis> of client host computer with an
129
131
<emphasis>encrypted root file system</emphasis>. See <xref
130
132
linkend="overview"/> for details.
134
137
<refsect1 id="options">
135
138
<title>OPTIONS</title>
138
<term><option>--help</option></term>
139
<term><option>-h</option></term>
142
<term><literal>-h</literal>, <literal>--help</literal></term>
142
145
Show a help message and exit
148
<term><option>--interface</option>
149
<replaceable>NAME</replaceable></term>
150
<term><option>-i</option>
151
<replaceable>NAME</replaceable></term>
153
<xi:include href="mandos-options.xml" xpointer="interface"/>
158
<term><option>--address
159
<replaceable>ADDRESS</replaceable></option></term>
161
<replaceable>ADDRESS</replaceable></option></term>
163
<xi:include href="mandos-options.xml" xpointer="address"/>
169
<replaceable>PORT</replaceable></option></term>
171
<replaceable>PORT</replaceable></option></term>
173
<xi:include href="mandos-options.xml" xpointer="port"/>
178
<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>
181
195
Run the server’s self-tests. This includes any unit
188
<term><option>--debug</option></term>
190
<xi:include href="mandos-options.xml" xpointer="debug"/>
195
<term><option>--priority <replaceable>
196
PRIORITY</replaceable></option></term>
198
<xi:include href="mandos-options.xml" xpointer="priority"/>
203
<term><option>--servicename
204
<replaceable>NAME</replaceable></option></term>
206
<xi:include href="mandos-options.xml"
207
xpointer="servicename"/>
212
<term><option>--configdir
213
<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>
216
252
Directory to search for configuration files. Default is
227
<term><option>--version</option></term>
263
<term><literal>--version</literal></term>
230
266
Prints the program version and exit.
236
<term><option>--no-dbus</option></term>
238
<xi:include href="mandos-options.xml" xpointer="dbus"/>
240
See also <xref linkend="dbus_interface"/>.
247
273
<refsect1 id="overview">
248
274
<title>OVERVIEW</title>
249
<xi:include href="overview.xml"/>
251
277
This program is the server part. It is a normal server program
252
278
and will run in a normal system environment, not in an initial
253
<acronym>RAM</acronym> disk environment.
279
RAM disk environment.
257
283
<refsect1 id="protocol">
258
284
<title>NETWORK PROTOCOL</title>
321
347
longer eligible to receive the encrypted password. The timeout,
322
348
checker program, and interval between checks can be configured
323
349
both globally and per client; see <citerefentry>
350
<refentrytitle>mandos.conf</refentrytitle>
351
<manvolnum>5</manvolnum></citerefentry> and <citerefentry>
324
352
<refentrytitle>mandos-clients.conf</refentrytitle>
325
353
<manvolnum>5</manvolnum></citerefentry>.
329
357
<refsect1 id="logging">
330
358
<title>LOGGING</title>
332
The server will send log message with various severity levels to
333
<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
334
362
<option>--debug</option> option, it will log even more messages,
335
363
and also show them on the console.
339
<refsect1 id="dbus_interface">
340
<title>D-BUS INTERFACE</title>
342
The server will by default provide a D-Bus system bus interface.
343
This interface will only be accessible by the root user or a
344
Mandos-specific user, if such a user exists.
349
367
<refsect1 id="exit_status">
350
368
<title>EXIT STATUS</title>
353
371
critical error is encountered.
357
<refsect1 id="environment">
358
<title>ENVIRONMENT</title>
361
<term><envar>PATH</envar></term>
364
To start the configured checker (see <xref
365
linkend="checking"/>), the server uses
366
<filename>/bin/sh</filename>, which in turn uses
367
<varname>PATH</varname> to search for matching commands if
368
an absolute path is not given. See <citerefentry>
369
<refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
377
<refsect1 id="files">
378
376
<title>FILES</title>
380
378
Use the <option>--configdir</option> option to change where
424
<term><filename>/bin/sh</filename></term>
427
This is used to start the configured checker command for
428
each client. See <citerefentry>
429
<refentrytitle>mandos-clients.conf</refentrytitle>
430
<manvolnum>5</manvolnum></citerefentry> for details.
437
424
<refsect1 id="bugs">
438
425
<title>BUGS</title>
440
427
This server might, on especially fatal errors, emit a Python
441
428
backtrace. This could be considered a feature.
444
Currently, if a client is declared <quote>invalid</quote> due to
445
having timed out, the server does not record this fact onto
446
permanent storage. This has some security implications, see
447
<xref linkend="clients"/>.
450
There is currently no way of querying the server of the current
451
status of clients, other than analyzing its <systemitem
452
class="service">syslog</systemitem> output.
455
There is no fine-grained control over logging and debug output.
458
Debug mode is conflated with running in the foreground.
461
The console log messages does not show a time stamp.
464
This server does not check the expire time of clients’ OpenPGP
469
<refsect1 id="example">
470
<title>EXAMPLE</title>
432
<refsect1 id="examples">
433
<title>EXAMPLES</title>
471
434
<informalexample>
473
436
Normal invocation needs no options:
476
<userinput>&COMMANDNAME;</userinput>
439
<userinput>mandos</userinput>
478
441
</informalexample>
479
442
<informalexample>
500
463
<!-- do not wrap this line -->
501
<userinput>&COMMANDNAME; --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
464
<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
504
467
</informalexample>
507
470
<refsect1 id="security">
508
471
<title>SECURITY</title>
509
<refsect2 id="server">
510
473
<title>SERVER</title>
512
Running this <command>&COMMANDNAME;</command> server program
513
should not in itself present any security risk to the host
514
computer running it. The program switches to a non-root user
475
Running this &COMMANDNAME; server program should not in itself
476
present any security risk to the host computer running it.
477
The program does not need any special privileges to run, and
478
is designed to run as a non-root user.
518
<refsect2 id="clients">
519
482
<title>CLIENTS</title>
521
484
The server only gives out its stored data to clients which
536
499
compromised if they are gone for too long.
539
If a client is compromised, its downtime should be duly noted
540
by the server which would therefore declare the client
541
invalid. But if the server was ever restarted, it would
542
re-read its client list from its configuration file and again
543
regard all clients therein as valid, and hence eligible to
544
receive their passwords. Therefore, be careful when
545
restarting servers if it is suspected that a client has, in
546
fact, been compromised by parties who may now be running a
547
fake Mandos client with the keys from the non-encrypted
548
initial <acronym>RAM</acronym> image of the client host. What
549
should be done in that case (if restarting the server program
550
really is necessary) is to stop the server program, edit the
551
configuration file to omit any suspect clients, and restart
555
502
For more details on client-side security, see
556
<citerefentry><refentrytitle>mandos-client</refentrytitle>
503
<citerefentry><refentrytitle>password-request</refentrytitle>
557
504
<manvolnum>8mandos</manvolnum></citerefentry>.
562
509
<refsect1 id="see_also">
563
510
<title>SEE ALSO</title>
566
<refentrytitle>mandos-clients.conf</refentrytitle>
567
<manvolnum>5</manvolnum></citerefentry>, <citerefentry>
568
<refentrytitle>mandos.conf</refentrytitle>
569
<manvolnum>5</manvolnum></citerefentry>, <citerefentry>
570
<refentrytitle>mandos-client</refentrytitle>
571
<manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
572
<refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
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.
578
530
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
613
RFC 4291: <citetitle>IP Version 6 Addressing
614
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>
619
<term>Section 2.2: <citetitle>Text Representation of
620
Addresses</citetitle></term>
621
<listitem><para/></listitem>
624
<term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
625
Address</citetitle></term>
626
<listitem><para/></listitem>
629
<term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
630
Addresses</citetitle></term>
633
The clients use IPv6 link-local addresses, which are
634
immediately usable since a link-local addresses is
635
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
645
RFC 4346: <citetitle>The Transport Layer Security (TLS)
646
Protocol Version 1.1</citetitle>
580
<citation>RFC 4346: <citetitle>The Transport Layer Security
581
(TLS) Protocol Version 1.1</citetitle></citation>