1
<?xml version="1.0" encoding="UTF-8"?>
1
<?xml version='1.0' encoding='UTF-8'?>
2
<?xml-stylesheet type="text/xsl"
3
href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
2
4
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
5
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
6
<!ENTITY VERSION "1.0">
4
7
<!ENTITY COMMANDNAME "mandos">
5
<!ENTITY TIMESTAMP "2015-01-25">
6
<!ENTITY % common SYSTEM "common.ent">
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
12
<title>Mandos Manual</title>
13
<!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
<productname>Mandos</productname>
15
<productnumber>&version;</productnumber>
16
<date>&TIMESTAMP;</date>
12
<title>&COMMANDNAME;</title>
13
<!-- NWalsh's docbook scripts use this to generate the footer: -->
14
<productname>&COMMANDNAME;</productname>
15
<productnumber>&VERSION;</productnumber>
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>
40
<holder>Teddy Hogeborn</holder>
41
<holder>Björn Påhlsson</holder>
34
<holder>Teddy Hogeborn & 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
<manvolnum>8</manvolnum>
63
<manvolnum>8mandos</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' rep='repeat'>OPTION</arg>
129
80
<refsect1 id="description">
130
81
<title>DESCRIPTION</title>
132
<command>&COMMANDNAME;</command> is a server daemon which
133
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.
147
<refsect1 id="purpose">
148
<title>PURPOSE</title>
150
The purpose of this is to enable <emphasis>remote and unattended
151
rebooting</emphasis> of client host computer with an
152
<emphasis>encrypted root file system</emphasis>. See <xref
153
linkend="overview"/> for details.
157
<refsect1 id="options">
158
<title>OPTIONS</title>
161
<term><option>--help</option></term>
162
<term><option>-h</option></term>
165
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>
204
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"
240
xpointer="priority_compat"/>
245
<term><option>--servicename
246
<replaceable>NAME</replaceable></option></term>
248
<xi:include href="mandos-options.xml"
249
xpointer="servicename"/>
254
<term><option>--configdir
255
<replaceable>DIRECTORY</replaceable></option></term>
258
Directory to search for configuration files. Default is
259
<quote><literal>/etc/mandos</literal></quote>. See
260
<citerefentry><refentrytitle>mandos.conf</refentrytitle>
261
<manvolnum>5</manvolnum></citerefentry> and <citerefentry>
262
<refentrytitle>mandos-clients.conf</refentrytitle>
263
<manvolnum>5</manvolnum></citerefentry>.
269
<term><option>--version</option></term>
272
Prints the program version and exit.
278
<term><option>--no-dbus</option></term>
280
<xi:include href="mandos-options.xml" xpointer="dbus"/>
282
See also <xref linkend="dbus_interface"/>.
288
<term><option>--no-ipv6</option></term>
290
<xi:include href="mandos-options.xml" xpointer="ipv6"/>
295
<term><option>--no-restore</option></term>
297
<xi:include href="mandos-options.xml" xpointer="restore"/>
299
See also <xref linkend="persistent_state"/>.
305
<term><option>--statedir
306
<replaceable>DIRECTORY</replaceable></option></term>
308
<xi:include href="mandos-options.xml" xpointer="statedir"/>
313
<term><option>--socket
314
<replaceable>FD</replaceable></option></term>
316
<xi:include href="mandos-options.xml" xpointer="socket"/>
321
<term><option>--foreground</option></term>
323
<xi:include href="mandos-options.xml"
324
xpointer="foreground"/>
329
<term><option>--no-zeroconf</option></term>
331
<xi:include href="mandos-options.xml" xpointer="zeroconf"/>
338
<refsect1 id="overview">
339
<title>OVERVIEW</title>
340
<xi:include href="overview.xml"/>
342
This program is the server part. It is a normal server program
343
and will run in a normal system environment, not in an initial
344
<acronym>RAM</acronym> disk environment.
348
<refsect1 id="protocol">
349
<title>NETWORK PROTOCOL</title>
351
The Mandos server announces itself as a Zeroconf service of type
352
<quote><literal>_mandos._tcp</literal></quote>. The Mandos
353
client connects to the announced address and port, and sends a
354
line of text where the first whitespace-separated field is the
355
protocol version, which currently is
356
<quote><literal>1</literal></quote>. The client and server then
357
start a TLS protocol handshake with a slight quirk: the Mandos
358
server program acts as a TLS <quote>client</quote> while the
359
connecting Mandos client acts as a TLS <quote>server</quote>.
360
The Mandos client must supply an OpenPGP certificate, and the
361
fingerprint of this certificate is used by the Mandos server to
362
look up (in a list read from <filename>clients.conf</filename>
363
at start time) which binary blob to give the client. No other
364
authentication or authorization is done by the server.
367
<title>Mandos Protocol (Version 1)</title><tgroup cols="3"><thead>
369
<entry>Mandos Client</entry>
370
<entry>Direction</entry>
371
<entry>Mandos Server</entry>
375
<entry>Connect</entry>
376
<entry>-><!-- → --></entry>
379
<entry><quote><literal>1\r\n</literal></quote></entry>
380
<entry>-><!-- → --></entry>
383
<entry>TLS handshake <emphasis>as TLS <quote>server</quote>
385
<entry><-><!-- ⟷ --></entry>
386
<entry>TLS handshake <emphasis>as TLS <quote>client</quote>
390
<entry>OpenPGP public key (part of TLS handshake)</entry>
391
<entry>-><!-- → --></entry>
395
<entry><-<!-- ← --></entry>
396
<entry>Binary blob (client will assume OpenPGP data)</entry>
400
<entry><-<!-- ← --></entry>
403
</tbody></tgroup></table>
406
<refsect1 id="checking">
407
<title>CHECKING</title>
409
The server will, by default, continually check that the clients
410
are still up. If a client has not been confirmed as being up
411
for some time, the client is assumed to be compromised and is no
412
longer eligible to receive the encrypted password. (Manual
413
intervention is required to re-enable a client.) The timeout,
414
extended timeout, checker program, and interval between checks
415
can be configured both globally and per client; see
416
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
417
<manvolnum>5</manvolnum></citerefentry>.
421
<refsect1 id="approval">
422
<title>APPROVAL</title>
424
The server can be configured to require manual approval for a
425
client before it is sent its secret. The delay to wait for such
426
approval and the default action (approve or deny) can be
427
configured both globally and per client; see <citerefentry>
428
<refentrytitle>mandos-clients.conf</refentrytitle>
429
<manvolnum>5</manvolnum></citerefentry>. By default all clients
430
will be approved immediately without delay.
433
This can be used to deny a client its secret if not manually
434
approved within a specified time. It can also be used to make
435
the server delay before giving a client its secret, allowing
436
optional manual denying of this specific client.
441
<refsect1 id="logging">
442
<title>LOGGING</title>
444
The server will send log message with various severity levels to
445
<filename class="devicefile">/dev/log</filename>. With the
446
<option>--debug</option> option, it will log even more messages,
447
and also show them on the console.
451
<refsect1 id="persistent_state">
452
<title>PERSISTENT STATE</title>
454
Client settings, initially read from
455
<filename>clients.conf</filename>, are persistent across
456
restarts, and run-time changes will override settings in
457
<filename>clients.conf</filename>. However, if a setting is
458
<emphasis>changed</emphasis> (or a client added, or removed) in
459
<filename>clients.conf</filename>, this will take precedence.
463
<refsect1 id="dbus_interface">
464
<title>D-BUS INTERFACE</title>
466
The server will by default provide a D-Bus system bus interface.
467
This interface will only be accessible by the root user or a
468
Mandos-specific user, if such a user exists. For documentation
469
of the D-Bus API, see the file <filename>DBUS-API</filename>.
473
<refsect1 id="exit_status">
474
<title>EXIT STATUS</title>
476
The server will exit with a non-zero exit status only when a
477
critical error is encountered.
481
<refsect1 id="environment">
482
<title>ENVIRONMENT</title>
485
<term><envar>PATH</envar></term>
488
To start the configured checker (see <xref
489
linkend="checking"/>), the server uses
490
<filename>/bin/sh</filename>, which in turn uses
491
<varname>PATH</varname> to search for matching commands if
492
an absolute path is not given. See <citerefentry>
493
<refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
501
<refsect1 id="files">
504
Use the <option>--configdir</option> option to change where
505
<command>&COMMANDNAME;</command> looks for its configurations
506
files. The default file names are listed here.
510
<term><filename>/etc/mandos/mandos.conf</filename></term>
513
Server-global settings. See
514
<citerefentry><refentrytitle>mandos.conf</refentrytitle>
515
<manvolnum>5</manvolnum></citerefentry> for details.
520
<term><filename>/etc/mandos/clients.conf</filename></term>
523
List of clients and client-specific settings. See
524
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
525
<manvolnum>5</manvolnum></citerefentry> for details.
530
<term><filename>/run/mandos.pid</filename></term>
533
The file containing the process id of the
534
<command>&COMMANDNAME;</command> process started last.
535
<emphasis >Note:</emphasis> If the <filename
536
class="directory">/run</filename> directory does not
537
exist, <filename>/var/run/mandos.pid</filename> will be
543
<term><filename class="devicefile">/dev/log</filename></term>
547
class="directory">/var/lib/mandos</filename></term>
550
Directory where persistent state will be saved. Change
551
this with the <option>--statedir</option> option. See
552
also the <option>--no-restore</option> option.
557
<term><filename>/dev/log</filename></term>
560
The Unix domain socket to where local syslog messages are
566
<term><filename>/bin/sh</filename></term>
569
This is used to start the configured checker command for
570
each client. See <citerefentry>
571
<refentrytitle>mandos-clients.conf</refentrytitle>
572
<manvolnum>5</manvolnum></citerefentry> for details.
582
This server might, on especially fatal errors, emit a Python
583
backtrace. This could be considered a feature.
586
There is no fine-grained control over logging and debug output.
589
This server does not check the expire time of clients’ OpenPGP
594
<refsect1 id="example">
595
<title>EXAMPLE</title>
598
Normal invocation needs no options:
601
<userinput>&COMMANDNAME;</userinput>
606
Run the server in debug mode, read configuration files from
607
the <filename class="directory">~/mandos</filename> directory,
608
and use the Zeroconf service name <quote>Test</quote> to not
609
collide with any other official Mandos server on this host:
613
<!-- do not wrap this line -->
614
<userinput>&COMMANDNAME; --debug --configdir ~/mandos --servicename Test</userinput>
620
Run the server normally, but only listen to one interface and
621
only on the link-local address on that interface:
625
<!-- do not wrap this line -->
626
<userinput>&COMMANDNAME; --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
632
<refsect1 id="security">
633
<title>SECURITY</title>
634
<refsect2 id="server">
635
<title>SERVER</title>
637
Running this <command>&COMMANDNAME;</command> server program
638
should not in itself present any security risk to the host
639
computer running it. The program switches to a non-root user
643
<refsect2 id="clients">
644
<title>CLIENTS</title>
646
The server only gives out its stored data to clients which
647
does have the OpenPGP key of the stored fingerprint. This is
648
guaranteed by the fact that the client sends its OpenPGP
649
public key in the TLS handshake; this ensures it to be
650
genuine. The server computes the fingerprint of the key
651
itself and looks up the fingerprint in its list of
652
clients. The <filename>clients.conf</filename> file (see
653
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
654
<manvolnum>5</manvolnum></citerefentry>)
655
<emphasis>must</emphasis> be made non-readable by anyone
656
except the user starting the server (usually root).
659
As detailed in <xref linkend="checking"/>, the status of all
660
client computers will continually be checked and be assumed
661
compromised if they are gone for too long.
664
For more details on client-side security, see
665
<citerefentry><refentrytitle>mandos-client</refentrytitle>
666
<manvolnum>8mandos</manvolnum></citerefentry>.
671
<refsect1 id="see_also">
672
<title>SEE ALSO</title>
674
<citerefentry><refentrytitle>intro</refentrytitle>
675
<manvolnum>8mandos</manvolnum></citerefentry>,
676
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
677
<manvolnum>5</manvolnum></citerefentry>,
678
<citerefentry><refentrytitle>mandos.conf</refentrytitle>
679
<manvolnum>5</manvolnum></citerefentry>,
680
<citerefentry><refentrytitle>mandos-client</refentrytitle>
681
<manvolnum>8mandos</manvolnum></citerefentry>,
682
<citerefentry><refentrytitle>sh</refentrytitle>
683
<manvolnum>1</manvolnum></citerefentry>
688
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
692
Zeroconf is the network protocol standard used by clients
693
for finding this Mandos server on the local network.
699
<ulink url="http://www.avahi.org/">Avahi</ulink>
703
Avahi is the library this server calls to implement
704
Zeroconf service announcements.
710
<ulink url="http://gnutls.org/">GnuTLS</ulink>
714
GnuTLS is the library this server uses to implement TLS for
715
communicating securely with the client, and at the same time
716
confidently get the client’s public OpenPGP key.
722
RFC 4291: <citetitle>IP Version 6 Addressing
723
Architecture</citetitle>
728
<term>Section 2.2: <citetitle>Text Representation of
729
Addresses</citetitle></term>
730
<listitem><para/></listitem>
733
<term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
734
Address</citetitle></term>
735
<listitem><para/></listitem>
738
<term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
739
Addresses</citetitle></term>
742
The clients use IPv6 link-local addresses, which are
743
immediately usable since a link-local addresses is
744
automatically assigned to a network interfaces when it
754
RFC 5246: <citetitle>The Transport Layer Security (TLS)
755
Protocol Version 1.2</citetitle>
759
TLS 1.2 is the protocol implemented by GnuTLS.
765
RFC 4880: <citetitle>OpenPGP Message Format</citetitle>
769
The data sent to clients is binary encrypted OpenPGP data.
775
RFC 6091: <citetitle>Using OpenPGP Keys for Transport Layer
776
Security (TLS) Authentication</citetitle>
780
This is implemented by GnuTLS and used by this server so
781
that OpenPGP keys can be used.
83
<command>&COMMANDNAME;</command> is a server daemon that handels
84
incomming passwords request for passwords. Mandos use avahi to
85
announce the service, and through gnutls authenticates
86
clients. Any authenticated client is then given its encrypted
92
<term><literal>-h</literal>, <literal>--help</literal></term>
95
show a help message and exit
101
<term><literal>-i</literal>, <literal>--interface <replaceable>
102
IF</replaceable></literal></term>
111
<term><literal>-a</literal>, <literal>--address <replaceable>
112
ADDRESS</replaceable></literal></term>
115
Address to listen for requests on
121
<term><literal>-p</literal>, <literal>--port <replaceable>
122
PORT</replaceable></literal></term>
125
Port number to receive requests on
131
<term><literal>--check</literal></term>
134
Run self-test on the server
140
<term><literal>--debug</literal></term>
149
<term><literal>--priority <replaceable>
150
PRIORITY</replaceable></literal></term>
153
GnuTLS priority string. See <citerefentry>
154
<refentrytitle>gnutls_priority_init</refentrytitle>
155
<manvolnum>3</manvolnum></citerefentry>
161
<term><literal>--servicename <replaceable>NAME</replaceable>
165
Zeroconf service name
171
<term><literal>--configdir <replaceable>DIR</replaceable>
175
Directory to search for configuration files
788
<!-- Local Variables: -->
789
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
790
<!-- time-stamp-end: "[\"']>" -->
791
<!-- time-stamp-format: "%:y-%02m-%02d" -->