<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN""http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [<!ENTITY COMMANDNAME "mandos"><!ENTITY TIMESTAMP "2019-02-10"><!ENTITY % common SYSTEM "common.ent">
%common;
]>
<refentryxmlns:xi="http://www.w3.org/2001/XInclude"><refentryinfo><title>Mandos Manual</title><!-- NWalsh’s docbook scripts use this to generate the footer: --><productname>Mandos</productname><productnumber>&version;</productnumber><date>&TIMESTAMP;</date><authorgroup><author><firstname>Björn</firstname><surname>Påhlsson</surname><address><email>belorn@recompile.se</email></address></author><author><firstname>Teddy</firstname><surname>Hogeborn</surname><address><email>teddy@recompile.se</email></address></author></authorgroup><copyright><year>2008</year><year>2009</year><year>2010</year><year>2011</year><year>2012</year><year>2013</year><year>2014</year><year>2015</year><year>2016</year><year>2017</year><year>2018</year><year>2019</year><holder>Teddy Hogeborn</holder><holder>Björn Påhlsson</holder></copyright><xi:includehref="legalnotice.xml"/></refentryinfo><refmeta><refentrytitle>&COMMANDNAME;</refentrytitle><manvolnum>8</manvolnum></refmeta><refnamediv><refname><command>&COMMANDNAME;</command></refname><refpurpose>
Gives encrypted passwords to authenticated Mandos clients
</refpurpose></refnamediv><refsynopsisdiv><cmdsynopsis><command>&COMMANDNAME;</command><group><argchoice="plain"><option>--interface
<replaceable>NAME</replaceable></option></arg><argchoice="plain"><option>-i
<replaceable>NAME</replaceable></option></arg></group><sbr/><group><argchoice="plain"><option>--address
<replaceable>ADDRESS</replaceable></option></arg><argchoice="plain"><option>-a
<replaceable>ADDRESS</replaceable></option></arg></group><sbr/><group><argchoice="plain"><option>--port
<replaceable>PORT</replaceable></option></arg><argchoice="plain"><option>-p
<replaceable>PORT</replaceable></option></arg></group><sbr/><arg><option>--priority
<replaceable>PRIORITY</replaceable></option></arg><sbr/><arg><option>--servicename
<replaceable>NAME</replaceable></option></arg><sbr/><arg><option>--configdir
<replaceable>DIRECTORY</replaceable></option></arg><sbr/><arg><option>--debug</option></arg><sbr/><arg><option>--debuglevel
<replaceable>LEVEL</replaceable></option></arg><sbr/><arg><option>--no-dbus</option></arg><sbr/><arg><option>--no-ipv6</option></arg><sbr/><arg><option>--no-restore</option></arg><sbr/><arg><option>--statedir
<replaceable>DIRECTORY</replaceable></option></arg><sbr/><arg><option>--socket
<replaceable>FD</replaceable></option></arg><sbr/><arg><option>--foreground</option></arg><sbr/><arg><option>--no-zeroconf</option></arg></cmdsynopsis><cmdsynopsis><command>&COMMANDNAME;</command><groupchoice="req"><argchoice="plain"><option>--help</option></arg><argchoice="plain"><option>-h</option></arg></group></cmdsynopsis><cmdsynopsis><command>&COMMANDNAME;</command><argchoice="plain"><option>--version</option></arg></cmdsynopsis><cmdsynopsis><command>&COMMANDNAME;</command><argchoice="plain"><option>--check</option></arg></cmdsynopsis></refsynopsisdiv><refsect1id="description"><title>DESCRIPTION</title><para><command>&COMMANDNAME;</command> is a server daemon which
handles incoming request for passwords for a pre-defined list of
client host computers. For an introduction, see
<citerefentry><refentrytitle>intro</refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server
uses Zeroconf to announce itself on the local network, and uses
TLS to communicate securely with and to authenticate the
clients. The Mandos server uses IPv6 to allow Mandos clients to
use IPv6 link-local addresses, since the clients will probably
not have any other addresses configured (see <xreflinkend="overview"/>). Any authenticated client is then given
the stored pre-encrypted password for that specific client.
</para></refsect1><refsect1id="purpose"><title>PURPOSE</title><para>
The purpose of this is to enable <emphasis>remote and unattended
rebooting</emphasis> of client host computer with an
<emphasis>encrypted root file system</emphasis>. See <xreflinkend="overview"/> for details.
</para></refsect1><refsect1id="options"><title>OPTIONS</title><variablelist><varlistentry><term><option>--help</option></term><term><option>-h</option></term><listitem><para>
Show a help message and exit
</para></listitem></varlistentry><varlistentry><term><option>--interface</option><replaceable>NAME</replaceable></term><term><option>-i</option><replaceable>NAME</replaceable></term><listitem><xi:includehref="mandos-options.xml"xpointer="interface"/></listitem></varlistentry><varlistentry><term><option>--address
<replaceable>ADDRESS</replaceable></option></term><term><option>-a
<replaceable>ADDRESS</replaceable></option></term><listitem><xi:includehref="mandos-options.xml"xpointer="address"/></listitem></varlistentry><varlistentry><term><option>--port
<replaceable>PORT</replaceable></option></term><term><option>-p
<replaceable>PORT</replaceable></option></term><listitem><xi:includehref="mandos-options.xml"xpointer="port"/></listitem></varlistentry><varlistentry><term><option>--check</option></term><listitem><para>
Run the server’s self-tests. This includes any unit
tests, etc.
</para></listitem></varlistentry><varlistentry><term><option>--debug</option></term><listitem><xi:includehref="mandos-options.xml"xpointer="debug"/></listitem></varlistentry><varlistentry><term><option>--debuglevel
<replaceable>LEVEL</replaceable></option></term><listitem><para>
Set the debugging log level.
<replaceable>LEVEL</replaceable> is a string, one of
<quote><literal>CRITICAL</literal></quote>,
<quote><literal>ERROR</literal></quote>,
<quote><literal>WARNING</literal></quote>,
<quote><literal>INFO</literal></quote>, or
<quote><literal>DEBUG</literal></quote>, in order of
increasing verbosity. The default level is
<quote><literal>WARNING</literal></quote>.
</para></listitem></varlistentry><varlistentry><term><option>--priority <replaceable>
PRIORITY</replaceable></option></term><listitem><xi:includehref="mandos-options.xml"xpointer="priority"/></listitem></varlistentry><varlistentry><term><option>--servicename
<replaceable>NAME</replaceable></option></term><listitem><xi:includehref="mandos-options.xml"xpointer="servicename"/></listitem></varlistentry><varlistentry><term><option>--configdir
<replaceable>DIRECTORY</replaceable></option></term><listitem><para>
Directory to search for configuration files. Default is
<quote><literal>/etc/mandos</literal></quote>. See
<citerefentry><refentrytitle>mandos.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> and <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para></listitem></varlistentry><varlistentry><term><option>--version</option></term><listitem><para>
Prints the program version and exit.
</para></listitem></varlistentry><varlistentry><term><option>--no-dbus</option></term><listitem><xi:includehref="mandos-options.xml"xpointer="dbus"/><para>
See also <xreflinkend="dbus_interface"/>.
</para></listitem></varlistentry><varlistentry><term><option>--no-ipv6</option></term><listitem><xi:includehref="mandos-options.xml"xpointer="ipv6"/></listitem></varlistentry><varlistentry><term><option>--no-restore</option></term><listitem><xi:includehref="mandos-options.xml"xpointer="restore"/><para>
See also <xreflinkend="persistent_state"/>.
</para></listitem></varlistentry><varlistentry><term><option>--statedir
<replaceable>DIRECTORY</replaceable></option></term><listitem><xi:includehref="mandos-options.xml"xpointer="statedir"/></listitem></varlistentry><varlistentry><term><option>--socket
<replaceable>FD</replaceable></option></term><listitem><xi:includehref="mandos-options.xml"xpointer="socket"/></listitem></varlistentry><varlistentry><term><option>--foreground</option></term><listitem><xi:includehref="mandos-options.xml"xpointer="foreground"/></listitem></varlistentry><varlistentry><term><option>--no-zeroconf</option></term><listitem><xi:includehref="mandos-options.xml"xpointer="zeroconf"/></listitem></varlistentry></variablelist></refsect1><refsect1id="overview"><title>OVERVIEW</title><xi:includehref="overview.xml"/><para>
This program is the server part. It is a normal server program
and will run in a normal system environment, not in an initial
<acronym>RAM</acronym> disk environment.
</para></refsect1><refsect1id="protocol"><title>NETWORK PROTOCOL</title><para>
The Mandos server announces itself as a Zeroconf service of type
<quote><literal>_mandos._tcp</literal></quote>. The Mandos
client connects to the announced address and port, and sends a
line of text where the first whitespace-separated field is the
protocol version, which currently is
<quote><literal>1</literal></quote>. The client and server then
start a TLS protocol handshake with a slight quirk: the Mandos
server program acts as a TLS <quote>client</quote> while the
connecting Mandos client acts as a TLS <quote>server</quote>.
The Mandos client must supply a TLS public key, and the key ID
of this public key is used by the Mandos server to look up (in a
list read from <filename>clients.conf</filename> at start time)
which binary blob to give the client. No other authentication
or authorization is done by the server.
</para><table><title>Mandos Protocol (Version 1)</title><tgroupcols="3"><thead><row><entry>Mandos Client</entry><entry>Direction</entry><entry>Mandos Server</entry></row></thead><tbody><row><entry>Connect</entry><entry>-><!-- &rarr; --></entry></row><row><entry><quote><literal>1\r\n</literal></quote></entry><entry>-><!-- &rarr; --></entry></row><row><entry>TLS handshake <emphasis>as TLS <quote>server</quote></emphasis></entry><entry>&lt;-><!-- &xharr; --></entry><entry>TLS handshake <emphasis>as TLS <quote>client</quote></emphasis></entry></row><row><entry>Public key (part of TLS handshake)</entry><entry>-><!-- &rarr; --></entry></row><row><entry/><entry>&lt;-<!-- &larr; --></entry><entry>Binary blob (client will assume OpenPGP data)</entry></row><row><entry/><entry>&lt;-<!-- &larr; --></entry><entry>Close</entry></row></tbody></tgroup></table></refsect1><refsect1id="checking"><title>CHECKING</title><para>
The server will, by default, continually check that the clients
are still up. If a client has not been confirmed as being up
for some time, the client is assumed to be compromised and is no
longer eligible to receive the encrypted password. (Manual
intervention is required to re-enable a client.) The timeout,
extended timeout, checker program, and interval between checks
can be configured both globally and per client; see
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para></refsect1><refsect1id="approval"><title>APPROVAL</title><para>
The server can be configured to require manual approval for a
client before it is sent its secret. The delay to wait for such
approval and the default action (approve or deny) can be
configured both globally and per client; see <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. By default all clients
will be approved immediately without delay.
</para><para>
This can be used to deny a client its secret if not manually
approved within a specified time. It can also be used to make
the server delay before giving a client its secret, allowing
optional manual denying of this specific client.
</para></refsect1><refsect1id="logging"><title>LOGGING</title><para>
The server will send log message with various severity levels to
<filenameclass="devicefile">/dev/log</filename>. With the
<option>--debug</option> option, it will log even more messages,
and also show them on the console.
</para></refsect1><refsect1id="persistent_state"><title>PERSISTENT STATE</title><para>
Client settings, initially read from
<filename>clients.conf</filename>, are persistent across
restarts, and run-time changes will override settings in
<filename>clients.conf</filename>. However, if a setting is
<emphasis>changed</emphasis> (or a client added, or removed) in
<filename>clients.conf</filename>, this will take precedence.
</para></refsect1><refsect1id="dbus_interface"><title>D-BUS INTERFACE</title><para>
The server will by default provide a D-Bus system bus interface.
This interface will only be accessible by the root user or a
Mandos-specific user, if such a user exists. For documentation
of the D-Bus API, see the file <filename>DBUS-API</filename>.
</para></refsect1><refsect1id="exit_status"><title>EXIT STATUS</title><para>
The server will exit with a non-zero exit status only when a
critical error is encountered.
</para></refsect1><refsect1id="environment"><title>ENVIRONMENT</title><variablelist><varlistentry><term><envar>PATH</envar></term><listitem><para>
To start the configured checker (see <xreflinkend="checking"/>), the server uses
<filename>/bin/sh</filename>, which in turn uses
<varname>PATH</varname> to search for matching commands if
an absolute path is not given. See <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para></listitem></varlistentry></variablelist></refsect1><refsect1id="files"><title>FILES</title><para>
Use the <option>--configdir</option> option to change where
<command>&COMMANDNAME;</command> looks for its configurations
files. The default file names are listed here.
</para><variablelist><varlistentry><term><filename>/etc/mandos/mandos.conf</filename></term><listitem><para>
Server-global settings. See
<citerefentry><refentrytitle>mandos.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
</para></listitem></varlistentry><varlistentry><term><filename>/etc/mandos/clients.conf</filename></term><listitem><para>
List of clients and client-specific settings. See
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
</para></listitem></varlistentry><varlistentry><term><filename>/run/mandos.pid</filename></term><listitem><para>
The file containing the process id of the
<command>&COMMANDNAME;</command> process started last.
<emphasis>Note:</emphasis> If the <filenameclass="directory">/run</filename> directory does not
exist, <filename>/var/run/mandos.pid</filename> will be
used instead.
</para></listitem></varlistentry><varlistentry><term><filenameclass="directory">/var/lib/mandos</filename></term><listitem><para>
Directory where persistent state will be saved. Change
this with the <option>--statedir</option> option. See
also the <option>--no-restore</option> option.
</para></listitem></varlistentry><varlistentry><term><filenameclass="devicefile">/dev/log</filename></term><listitem><para>
The Unix domain socket to where local syslog messages are
sent.
</para></listitem></varlistentry><varlistentry><term><filename>/bin/sh</filename></term><listitem><para>
This is used to start the configured checker command for
each client. See <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.
</para></listitem></varlistentry></variablelist></refsect1><refsect1id="bugs"><title>BUGS</title><para>
This server might, on especially fatal errors, emit a Python
backtrace. This could be considered a feature.
</para><para>
There is no fine-grained control over logging and debug output.
</para><xi:includehref="bugs.xml"/></refsect1><refsect1id="example"><title>EXAMPLE</title><informalexample><para>
Normal invocation needs no options:
</para><para><userinput>&COMMANDNAME;</userinput></para></informalexample><informalexample><para>
Run the server in debug mode, read configuration files from
the <filenameclass="directory">~/mandos</filename> directory,
and use the Zeroconf service name <quote>Test</quote> to not
collide with any other official Mandos server on this host:
</para><para><!-- do not wrap this line --><userinput>&COMMANDNAME; --debug --configdir ~/mandos --servicename Test</userinput></para></informalexample><informalexample><para>
Run the server normally, but only listen to one interface and
only on the link-local address on that interface:
</para><para><!-- do not wrap this line --><userinput>&COMMANDNAME; --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput></para></informalexample></refsect1><refsect1id="security"><title>SECURITY</title><refsect2id="server"><title>SERVER</title><para>
Running this <command>&COMMANDNAME;</command> server program
should not in itself present any security risk to the host
computer running it. The program switches to a non-root user
soon after startup.
</para></refsect2><refsect2id="clients"><title>CLIENTS</title><para>
The server only gives out its stored data to clients which
does have the correct key ID of the stored key ID. This is
guaranteed by the fact that the client sends its public key in
the TLS handshake; this ensures it to be genuine. The server
computes the key ID of the key itself and looks up the key ID
in its list of clients. The <filename>clients.conf</filename>
file (see
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
<emphasis>must</emphasis> be made non-readable by anyone
except the user starting the server (usually root).
</para><para>
As detailed in <xreflinkend="checking"/>, the status of all
client computers will continually be checked and be assumed
compromised if they are gone for too long.
</para><para>
For more details on client-side security, see
<citerefentry><refentrytitle>mandos-client</refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>.
</para></refsect2></refsect1><refsect1id="see_also"><title>SEE ALSO</title><para><citerefentry><refentrytitle>intro</refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>,
<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>mandos.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>mandos-client</refentrytitle><manvolnum>8mandos</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry></para><variablelist><varlistentry><term><ulinkurl="http://www.zeroconf.org/">Zeroconf</ulink></term><listitem><para>
Zeroconf is the network protocol standard used by clients
for finding this Mandos server on the local network.
</para></listitem></varlistentry><varlistentry><term><ulinkurl="http://www.avahi.org/">Avahi</ulink></term><listitem><para>
Avahi is the library this server calls to implement
Zeroconf service announcements.
</para></listitem></varlistentry><varlistentry><term><ulinkurl="https://gnutls.org/">GnuTLS</ulink></term><listitem><para>
GnuTLS is the library this server uses to implement TLS for
communicating securely with the client, and at the same time
confidently get the client’s public key.
</para></listitem></varlistentry><varlistentry><term>
RFC 4291: <citetitle>IP Version 6 Addressing
Architecture</citetitle></term><listitem><variablelist><varlistentry><term>Section 2.2: <citetitle>Text Representation of
Addresses</citetitle></term><listitem><para/></listitem></varlistentry><varlistentry><term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
Address</citetitle></term><listitem><para/></listitem></varlistentry><varlistentry><term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
Addresses</citetitle></term><listitem><para>
The clients use IPv6 link-local addresses, which are
immediately usable since a link-local addresses is
automatically assigned to a network interfaces when it
is brought up.
</para></listitem></varlistentry></variablelist></listitem></varlistentry><varlistentry><term>
RFC 5246: <citetitle>The Transport Layer Security (TLS)
Protocol Version 1.2</citetitle></term><listitem><para>
TLS 1.2 is the protocol implemented by GnuTLS.
</para></listitem></varlistentry><varlistentry><term>
RFC 4880: <citetitle>OpenPGP Message Format</citetitle></term><listitem><para>
The data sent to clients is binary encrypted OpenPGP data.
</para></listitem></varlistentry><varlistentry><term>
RFC 7250: <citetitle>Using Raw Public Keys in Transport
Layer Security (TLS) and Datagram Transport Layer Security
(DTLS)</citetitle></term><listitem><para>
This is implemented by GnuTLS version 3.6.6 and is, if
present, used by this server so that raw public keys can be
used.
</para></listitem></varlistentry><varlistentry><term>
RFC 6091: <citetitle>Using OpenPGP Keys for Transport Layer
Security (TLS) Authentication</citetitle></term><listitem><para>
This is implemented by GnuTLS before version 3.6.0 and is,
if present, used by this server so that OpenPGP keys can be
used.
</para></listitem></varlistentry></variablelist></refsect1></refentry><!-- Local Variables: --><!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" --><!-- time-stamp-end: "[\"']>" --><!-- time-stamp-format: "%:y-%02m-%02d" --><!-- End: -->

Loggerhead is a web-based interface for Bazaar branches
Version: 1.18.2