'\" t .\" Title: mandos .\" Author: Bj\(:orn P\(oahlsson .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 2019-07-24 .\" Manual: Mandos Manual .\" Source: Mandos 1.8.14 .\" Language: English .\" .TH "MANDOS" "8" "2019\-07\-24" "Mandos 1.8.14" "Mandos Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" mandos \- Gives encrypted passwords to authenticated Mandos clients .SH "SYNOPSIS" .HP \w'\fBmandos\fR\ 'u \fBmandos\fR [\fB\-\-interface\ \fR\fB\fINAME\fR\fR | \fB\-i\ \fR\fB\fINAME\fR\fR] .br [\fB\-\-address\ \fR\fB\fIADDRESS\fR\fR | \fB\-a\ \fR\fB\fIADDRESS\fR\fR] .br [\fB\-\-port\ \fR\fB\fIPORT\fR\fR | \fB\-p\ \fR\fB\fIPORT\fR\fR] .br [\fB\-\-priority\ \fR\fB\fIPRIORITY\fR\fR] .br [\fB\-\-servicename\ \fR\fB\fINAME\fR\fR] .br [\fB\-\-configdir\ \fR\fB\fIDIRECTORY\fR\fR] .br [\fB\-\-debug\fR] .br [\fB\-\-debuglevel\ \fR\fB\fILEVEL\fR\fR] .br [\fB\-\-no\-dbus\fR] .br [\fB\-\-no\-ipv6\fR] .br [\fB\-\-no\-restore\fR] .br [\fB\-\-statedir\ \fR\fB\fIDIRECTORY\fR\fR] .br [\fB\-\-socket\ \fR\fB\fIFD\fR\fR] .br [\fB\-\-foreground\fR] .br [\fB\-\-no\-zeroconf\fR] .HP \w'\fBmandos\fR\ 'u \fBmandos\fR {\fB\-\-help\fR | \fB\-h\fR} .HP \w'\fBmandos\fR\ 'u \fBmandos\fR \fB\-\-version\fR .HP \w'\fBmandos\fR\ 'u \fBmandos\fR \fB\-\-check\fR .SH "DESCRIPTION" .PP \fBmandos\fR is a server daemon which handles incoming request for passwords for a pre\-defined list of client host computers\&. For an introduction, see \fBintro\fR(8mandos)\&. 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 the section called \(lqOVERVIEW\(rq)\&. Any authenticated client is then given the stored pre\-encrypted password for that specific client\&. .SH "PURPOSE" .PP The purpose of this is to enable \fIremote and unattended rebooting\fR of client host computer with an \fIencrypted root file system\fR\&. See the section called \(lqOVERVIEW\(rq for details\&. .SH "OPTIONS" .PP \fB\-\-help\fR, \fB\-h\fR .RS 4 Show a help message and exit .RE .PP \fB\-\-interface\fR \fINAME\fR, \fB\-i\fR \fINAME\fR .RS 4 If this is specified, the server will only announce the service and listen to requests on the specified network interface\&. Default is to use all available interfaces\&. \fINote:\fR a failure to bind to the specified interface is not considered critical, and the server will not exit, but instead continue normally\&. .RE .PP \fB\-\-address \fR\fB\fIADDRESS\fR\fR, \fB\-a \fR\fB\fIADDRESS\fR\fR .RS 4 If this option is used, the server will only listen to the specified IPv6 address\&. If a link\-local address is specified, an interface should be set, since a link\-local address is only valid on a single interface\&. By default, the server will listen to all available addresses\&. If set, this must normally be an IPv6 address; an IPv4 address can only be specified using IPv4\-mapped IPv6 address syntax: \(lq::FFFF:192\&.0\&.2\&.3\(rq\&. (Only if IPv6 usage is \fIdisabled\fR (see below) must this be an IPv4 address\&.) .RE .PP \fB\-\-port \fR\fB\fIPORT\fR\fR, \fB\-p \fR\fB\fIPORT\fR\fR .RS 4 If this option is used, the server will bind to that port\&. By default, the server will listen to an arbitrary port given by the operating system\&. .RE .PP \fB\-\-check\fR .RS 4 Run the server\(cqs self\-tests\&. This includes any unit tests, etc\&. .RE .PP \fB\-\-debug\fR .RS 4 If the server is run in debug mode, it will run in the foreground and print a lot of debugging information\&. The default is to \fInot\fR run in debug mode\&. .RE .PP \fB\-\-debuglevel \fR\fB\fILEVEL\fR\fR .RS 4 Set the debugging log level\&. \fILEVEL\fR is a string, one of \(lqCRITICAL\(rq, \(lqERROR\(rq, \(lqWARNING\(rq, \(lqINFO\(rq, or \(lqDEBUG\(rq, in order of increasing verbosity\&. The default level is \(lqWARNING\(rq\&. .RE .PP \fB\-\-priority \fR\fB\fI PRIORITY\fR\fR .RS 4 GnuTLS priority string for the TLS handshake\&. The default is \(lqSECURE128\::!CTYPE\-X\&.509\::+CTYPE\-RAWPK\::!RSA\::!VERS\-ALL\::+VERS\-TLS1\&.3\::%PROFILE_ULTRA\(rq when using raw public keys in TLS, and \(lqSECURE256\::!CTYPE\-X\&.509\::+CTYPE\-OPENPGP\::!RSA\::+SIGN\-DSA\-SHA256\(rq when using OpenPGP keys in TLS,\&. See \fBgnutls_priority_init\fR(3) for the syntax\&. \fIWarning\fR: changing this may make the TLS handshake fail, making server\-client communication impossible\&. Changing this option may also make the network traffic decryptable by an attacker\&. .RE .PP \fB\-\-servicename \fR\fB\fINAME\fR\fR .RS 4 Zeroconf service name\&. The default is \(lqMandos\(rq\&. This only needs to be changed if for some reason is would be necessary to run more than one server on the same \fIhost\fR\&. This would not normally be useful\&. If there are name collisions on the same \fInetwork\fR, the newer server will automatically rename itself to \(lqMandos #2\(rq, and so on; therefore, this option is not needed in that case\&. .RE .PP \fB\-\-configdir \fR\fB\fIDIRECTORY\fR\fR .RS 4 Directory to search for configuration files\&. Default is \(lq/etc/mandos\(rq\&. See \fBmandos.conf\fR(5) and \fBmandos-clients.conf\fR(5)\&. .RE .PP \fB\-\-version\fR .RS 4 Prints the program version and exit\&. .RE .PP \fB\-\-no\-dbus\fR .RS 4 This option controls whether the server will provide a D\-Bus system bus interface\&. The default is to provide such an interface\&. .sp See also the section called \(lqD\-BUS INTERFACE\(rq\&. .RE .PP \fB\-\-no\-ipv6\fR .RS 4 This option controls whether the server will use IPv6 sockets and addresses\&. The default is to use IPv6\&. This option should \fInever\fR normally be turned off, \fIeven in IPv4\-only environments\fR\&. This is because \fBmandos-client\fR(8mandos) will normally use IPv6 link\-local addresses, and will not be able to find or connect to the server if this option is turned off\&. \fIOnly advanced users should consider changing this option\fR\&. .RE .PP \fB\-\-no\-restore\fR .RS 4 This option controls whether the server will restore its state from the last time it ran\&. Default is to restore last state\&. .sp See also the section called \(lqPERSISTENT STATE\(rq\&. .RE .PP \fB\-\-statedir \fR\fB\fIDIRECTORY\fR\fR .RS 4 Directory to save (and restore) state in\&. Default is \(lq/var/lib/mandos\(rq\&. .RE .PP \fB\-\-socket \fR\fB\fIFD\fR\fR .RS 4 If this option is used, the server will not create a new network socket, but will instead use the supplied file descriptor\&. By default, the server will create a new network socket\&. .RE .PP \fB\-\-foreground\fR .RS 4 This option will make the server run in the foreground and not write a PID file\&. The default is to \fInot\fR run in the foreground, except in \fBdebug\fR mode, which implies this option\&. .RE .PP \fB\-\-no\-zeroconf\fR .RS 4 This option controls whether the server will announce its existence using Zeroconf\&. Default is to use Zeroconf\&. If Zeroconf is not used, a \fBport\fR number or a \fBsocket\fR is required\&. .RE .SH "OVERVIEW" .PP This is part of the Mandos system for allowing computers to have encrypted root file systems and at the same time be capable of remote and/or unattended reboots\&. The computers run a small client program in the initial RAM disk environment which will communicate with a server over a network\&. All network communication is encrypted using TLS\&. The clients are identified by the server using a TLS key; each client has one unique to it\&. The server sends the clients an encrypted password\&. The encrypted password is decrypted by the clients using a separate OpenPGP key, and the password is then used to unlock the root file system, whereupon the computers can continue booting normally\&. .PP This program is the server part\&. It is a normal server program and will run in a normal system environment, not in an initial RAM disk environment\&. .SH "NETWORK PROTOCOL" .PP The Mandos server announces itself as a Zeroconf service of type \(lq_mandos\&._tcp\(rq\&. 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 \(lq1\(rq\&. The client and server then start a TLS protocol handshake with a slight quirk: the Mandos server program acts as a TLS \(lqclient\(rq while the connecting Mandos client acts as a TLS \(lqserver\(rq\&. 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 clients\&.conf at start time) which binary blob to give the client\&. No other authentication or authorization is done by the server\&. .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .B Table\ \&1.\ \&Mandos Protocol (Version 1) .TS allbox tab(:); lB lB lB. T{ Mandos Client T}:T{ Direction T}:T{ Mandos Server T} .T& l l l l l l l l l l l l l l l l l l. T{ Connect T}:T{ \-> T}:T{ \ \& T} T{ \(lq1\er\en\(rq T}:T{ \-> T}:T{ \ \& T} T{ TLS handshake \fIas TLS \fR\fI\(lqserver\(rq\fR\fI \fR T}:T{ <\-> T}:T{ TLS handshake \fIas TLS \fR\fI\(lqclient\(rq\fR\fI \fR T} T{ Public key (part of TLS handshake) T}:T{ \-> T}:T{ \ \& T} T{ \ \& T}:T{ <\- T}:T{ Binary blob (client will assume OpenPGP data) T} T{ \ \& T}:T{ <\- T}:T{ Close T} .TE .sp 1 .SH "CHECKING" .PP 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 \fBmandos-clients.conf\fR(5)\&. .SH "APPROVAL" .PP 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 \fBmandos-clients.conf\fR(5)\&. By default all clients will be approved immediately without delay\&. .PP 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\&. .SH "LOGGING" .PP The server will send log message with various severity levels to /dev/log\&. With the \fB\-\-debug\fR option, it will log even more messages, and also show them on the console\&. .SH "PERSISTENT STATE" .PP Client settings, initially read from clients\&.conf, are persistent across restarts, and run\-time changes will override settings in clients\&.conf\&. However, if a setting is \fIchanged\fR (or a client added, or removed) in clients\&.conf, this will take precedence\&. .SH "D\-BUS INTERFACE" .PP 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 DBUS\-API\&. .SH "EXIT STATUS" .PP The server will exit with a non\-zero exit status only when a critical error is encountered\&. .SH "ENVIRONMENT" .PP \fBPATH\fR .RS 4 To start the configured checker (see the section called \(lqCHECKING\(rq), the server uses /bin/sh, which in turn uses \fIPATH\fR to search for matching commands if an absolute path is not given\&. See \fBsh\fR(1)\&. .RE .SH "FILES" .PP Use the \fB\-\-configdir\fR option to change where \fBmandos\fR looks for its configurations files\&. The default file names are listed here\&. .PP /etc/mandos/mandos\&.conf .RS 4 Server\-global settings\&. See \fBmandos.conf\fR(5) for details\&. .RE .PP /etc/mandos/clients\&.conf .RS 4 List of clients and client\-specific settings\&. See \fBmandos-clients.conf\fR(5) for details\&. .RE .PP /run/mandos\&.pid .RS 4 The file containing the process id of the \fBmandos\fR process started last\&. \fINote:\fR If the /run directory does not exist, /var/run/mandos\&.pid will be used instead\&. .RE .PP /var/lib/mandos .RS 4 Directory where persistent state will be saved\&. Change this with the \fB\-\-statedir\fR option\&. See also the \fB\-\-no\-restore\fR option\&. .RE .PP /dev/log .RS 4 The Unix domain socket to where local syslog messages are sent\&. .RE .PP /bin/sh .RS 4 This is used to start the configured checker command for each client\&. See \fBmandos-clients.conf\fR(5) for details\&. .RE .SH "BUGS" .PP This server might, on especially fatal errors, emit a Python backtrace\&. This could be considered a feature\&. .PP There is no fine\-grained control over logging and debug output\&. .PP Please report bugs to the Mandos development mailing list: (subscription required)\&. Note that this list is public\&. The developers can be reached privately at (OpenPGP key fingerprint 153A 37F1 0BBA 0435 987F 2C4A 7223 2973 CA34 C2C4 for encrypted mail)\&. .SH "EXAMPLE" .PP Normal invocation needs no options: .PP \fBmandos\fR .PP Run the server in debug mode, read configuration files from the ~/mandos directory, and use the Zeroconf service name \(lqTest\(rq to not collide with any other official Mandos server on this host: .PP \fBmandos \-\-debug \-\-configdir ~/mandos \-\-servicename Test\fR .PP Run the server normally, but only listen to one interface and only on the link\-local address on that interface: .PP \fBmandos \-\-interface eth7 \-\-address fe80::aede:48ff:fe71:f6f2\fR .SH "SECURITY" .SS "SERVER" .PP Running this \fBmandos\fR 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\&. .SS "CLIENTS" .PP 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 clients\&.conf file (see \fBmandos-clients.conf\fR(5)) \fImust\fR be made non\-readable by anyone except the user starting the server (usually root)\&. .PP As detailed in the section called \(lqCHECKING\(rq, the status of all client computers will continually be checked and be assumed compromised if they are gone for too long\&. .PP For more details on client\-side security, see \fBmandos-client\fR(8mandos)\&. .SH "SEE ALSO" .PP \fBintro\fR(8mandos), \fBmandos-clients.conf\fR(5), \fBmandos.conf\fR(5), \fBmandos-client\fR(8mandos), \fBsh\fR(1) .PP \m[blue]\fBZeroconf\fR\m[]\&\s-2\u[1]\d\s+2 .RS 4 Zeroconf is the network protocol standard used by clients for finding this Mandos server on the local network\&. .RE .PP \m[blue]\fBAvahi\fR\m[]\&\s-2\u[2]\d\s+2 .RS 4 Avahi is the library this server calls to implement Zeroconf service announcements\&. .RE .PP \m[blue]\fBGnuTLS\fR\m[]\&\s-2\u[3]\d\s+2 .RS 4 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\(cqs public key\&. .RE .PP RFC 4291: IP Version 6 Addressing Architecture .RS 4 .PP Section 2\&.2: Text Representation of Addresses .RS 4 .RE .PP Section 2\&.5\&.5\&.2: IPv4\-Mapped IPv6 Address .RS 4 .RE .PP Section 2\&.5\&.6, Link\-Local IPv6 Unicast Addresses .RS 4 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\&. .RE .RE .PP RFC 5246: The Transport Layer Security (TLS) Protocol Version 1\&.2 .RS 4 TLS 1\&.2 is the protocol implemented by GnuTLS\&. .RE .PP RFC 4880: OpenPGP Message Format .RS 4 The data sent to clients is binary encrypted OpenPGP data\&. .RE .PP RFC 7250: Using Raw Public Keys in Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) .RS 4 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\&. .RE .PP RFC 6091: Using OpenPGP Keys for Transport Layer Security (TLS) Authentication .RS 4 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\&. .RE .SH "COPYRIGHT" .br Copyright \(co 2008-2019 Teddy Hogeborn, Bj\(:orn P\(oahlsson .br .PP This manual page is part of Mandos\&. .PP Mandos is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version\&. .PP Mandos is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE\&. See the GNU General Public License for more details\&. .PP You should have received a copy of the GNU General Public License along with Mandos\&. If not, see \m[blue]\fBhttp://www\&.gnu\&.org/licenses/\fR\m[]\&. .sp .SH "NOTES" .IP " 1." 4 Zeroconf .RS 4 \%http://www.zeroconf.org/ .RE .IP " 2." 4 Avahi .RS 4 \%https://www.avahi.org/ .RE .IP " 3." 4 GnuTLS .RS 4 \%https://gnutls.org/ .RE