MANDOS(8)

📦
version 1.8.19 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 mandos(8) — the Mandos Manual 💖

okay bestie, buckle up, we're reading the mandos manpage together and honestly? it's giving main character energy. this is part one, so don't go anywhere.

✨ NAME ✨

mandos — gives encrypted passwords to authenticated Mandos clients 🫶

✨ SYNOPSIS ✨

lowkey the whole vibe in one code block, no cap:

mandos [--interface NAME | -i NAME]
       [--address ADDRESS | -a ADDRESS]
       [--port PORT | -p PORT]
       [--priority PRIORITY]
       [--servicename NAME]
       [--configdir DIRECTORY]
       [--debug]
       [--debuglevel LEVEL]
       [--no-dbus]
       [--no-ipv6]
       [--no-restore]
       [--statedir DIRECTORY]
       [--socket FD]
       [--foreground]
       [--no-zeroconf]

mandos {--help | -h}

mandos --version

mandos --check

✨ DESCRIPTION ✨

so mandos is a server daemon 🖥️ and its whole job is handling incoming requests for passwords, for a pre-defined list of client host computers. if you want the whole intro story, go read intro(8mandos). 📖

the Mandos server uses Zeroconf to announce itself on the local network, and it uses TLS to communicate securely with the clients and to authenticate them. it uses IPv6 so that Mandos clients can use IPv6 link-local addresses — because bestie, those clients probably don't have any other addresses configured (peep the section called "OVERVIEW" for that). 🔍

and then? any authenticated client gets handed the stored pre-encrypted password for that specific client. that's it. that's the whole serve. 💅

✨ PURPOSE ✨

the purpose of all this is to make remote and unattended rebooting possible for a client host computer that has an encrypted root file system. 😤 see the section called "OVERVIEW" for the details, bestie.

✨ OPTIONS ✨

one bullet per flag, no skips, we're thorough in this house:

  • --help, -h — shows a help message and dips out. ✌️
  • --interface NAME, -i NAME — if you set this, the server will only announce the service and listen to requests on the network interface you named. default is to use all available interfaces. Note: if it fails to bind to the interface you specified, that is not considered critical — the server will not exit, it'll just carry on like nothing happened. 💀
  • --address ADDRESS, -a ADDRESS — if you use this, the server will only listen to the IPv6 address you gave. if you specify a link-local address, you should also set an interface, because a link-local address is only valid on a single interface, periodt. by default the server listens 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: "::FFFF:192.0.2.3". (only if IPv6 usage is disabled — see below — must this be an IPv4 address.)
  • --port PORT, -p PORT — if you use this, the server binds to that port. by default the server will listen to an arbitrary port given by the operating system. 🎲
  • --check — runs the server's self-tests. this includes any unit tests, etc. 🧪
  • --debug — if the server runs in debug mode it'll run in the foreground and print a lot of debugging info. default is to not run in debug mode.
  • --debuglevel LEVEL — sets the debugging log level. LEVEL is a string, one of "CRITICAL", "ERROR", "WARNING", "INFO", or "DEBUG", in order of increasing verbosity. the default level is "WARNING". 📝
  • --priority PRIORITY — GnuTLS priority string for the TLS handshake. the default is

"SECURE128:!CTYPE-X.509:+CTYPE-RAWPK:!RSA:!VERS-ALL:+VERS-TLS1.3:%PROFILE_ULTRA" when using raw public keys in TLS, and "SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP:!RSA:+SIGN-DSA-SHA256" when using OpenPGP keys in TLS,. see gnutls_priority_init(3) for the syntax.

Warning: 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. 🚨 so like, don't be cute with it.
  • --servicename NAME — Zeroconf service name. default is "Mandos". you only need to change this if for some reason it would be necessary to run more than one server on the same host — which would not normally be useful, ngl. if there are name collisions on the same network, the newer server will automatically rename itself to "Mandos #2", and so on; therefore this option is not needed in that case. 🏷️
  • --configdir DIRECTORY — directory to search for configuration files. default is "/etc/mandos". see mandos.conf(5) and mandos-clients.conf(5). 📂
  • --version — prints the program version and exits. 🎀
  • --no-dbus — this option controls whether the server will provide a D-Bus system bus interface. the default is to provide such an interface. see also the section called "D-BUS INTERFACE". 🚌
  • --no-ipv6 — this option controls whether the server will use IPv6 sockets and addresses. the default is to use IPv6. this option should never normally be turned off, even in IPv4-only environments. that's because mandos-client(8mandos) will normally use IPv6 link-local addresses, and won't be able to find or connect to the server if this option is turned off. only advanced users should consider changing this option. 👑
  • --no-restore — this option controls whether the server will restore its state from the last time it ran. default is to restore last state. see also the section called "PERSISTENT STATE". 💾
  • --statedir DIRECTORY — directory to save (and restore) state in. default is "/var/lib/mandos". 📁
  • --socket FD — if you use this, the server will not create a new network socket, and will instead use the supplied file descriptor. by default the server creates a new network socket. 🔌
  • --foreground — this option makes the server run in the foreground and not write a PID file. default is to not run in the foreground — except in debug mode, which implies this option. 🌅
  • --no-zeroconf — this option controls whether the server will announce its existence using Zeroconf. default is to use Zeroconf. if Zeroconf is not used, a port number or a socket is required. 📡

✨ OVERVIEW ✨

okay so this is part of the Mandos system, which lets computers have encrypted root file systems and still be capable of remote and/or unattended reboots. iconic, honestly. 🌈

the computers run a small client program inside the initial RAM disk environment, and that program talks to a server over a network. all network communication is encrypted using TLS. 🔐

the clients get identified by the server using a TLS key — and each client has one that's unique to it, no sharing. the server then sends the client an encrypted password. the client decrypts that encrypted password using a separate OpenPGP key, and then the password is used to unlock the root file system, whereupon the computer can continue booting normally. 🦋

this program is the server part. it's a normal server program and runs in a normal system environment — not in an initial RAM disk environment. ✨

✨ NETWORK PROTOCOL ✨

the Mandos server announces itself as a Zeroconf service of type "_mandos._tcp". 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 "1". 📨

then the client and server start a TLS protocol handshake with a slight quirk: the Mandos server program acts as a TLS "client" while the connecting Mandos client acts as a TLS "server". plot twist, i know. 😭

the Mandos client must supply a TLS public key, and the key ID of that 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. that's it, that's the whole security model, fr fr. 💀

Table 1. Mandos Protocol (Version 1) — repping it as a list because tables aren't the vibe here:

  • Mandos Client: Connect — Direction: -> — Mandos Server: (nothing)
  • Mandos Client: "1\r\n" — Direction: -> — Mandos Server: (nothing)
  • Mandos Client: TLS handshake as TLS "server" — Direction: <-> — Mandos Server: TLS handshake as TLS "client"
  • Mandos Client: Public key (part of TLS handshake) — Direction: -> — Mandos Server: (nothing)
  • Mandos Client: (nothing) — Direction: <- — Mandos Server: Binary blob (client will assume OpenPGP data)
  • Mandos Client: (nothing) — Direction: <- — Mandos Server: Close

✨ CHECKING ✨

by default, the server will 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. and bestie — manual intervention is required to re-enable a client. 😭

the timeout, extended timeout, checker program, and interval between checks can all be configured both globally and per client; see mandos-clients.conf(5). ⏰

✨ APPROVAL ✨

the server can be configured to require manual approval for a client before it gets 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 mandos-clients.conf(5). by default, all clients will be approved immediately without delay. 💅

this can be used to deny a client its secret if it's not manually approved within a specified time. 🚫

it can also be used to make the server delay before giving a client its secret, which allows optional manual denying of this specific client. ⏳

📝 LOGGING 📝

So the server is constantly yapping — it sends log messages with all different severity levels to /dev/log. And if you slap the --debug option on it? Bestie, it logs EVEN MORE, and it also shows them right there on your console. No hiding. 💅

💾 PERSISTENT STATE 💾

Okay so here's the tea: client settings get read from clients.conf at first, but they're persistent across restarts. That means run-time changes you make override whatever's sitting in clients.conf.

BUT — and this is the plot twist 🙈 — if a setting gets changed in clients.conf (or a client gets added, or removed), that takes precedence instead.

It's giving "last one to speak wins" energy, fr fr.

🚌 D-BUS INTERFACE 🚌

By default, the server provides a D-Bus system bus interface. ✨

This interface is only accessible by the root user — or by a Mandos-specific user, if one of those exists on your system. For the actual documentation of the D-Bus API, go peek at the file DBUS-API.

🚪 EXIT STATUS 🚪

The server will exit with a non-zero exit status only when a critical error is encountered. So if it bounces with a nonzero code, something is genuinely wrong, bestie. 😭

🌍 ENVIRONMENT 🌍

  • PATH — To start the configured checker (peep the “CHECKING” section), the server uses /bin/sh, which then uses PATH to search for matching commands — but only if an absolute path wasn't given. See sh(1).

📁 FILES 📁

Wanna change where mandos looks for its config files? Use the --configdir option. The default file names are listed right here, bestie: 🎀

  • /etc/mandos/mandos.conf — Server-global settings. See mandos.conf(5) for details.
  • /etc/mandos/clients.conf — The list of clients and their client-specific settings. See mandos-clients.conf(5) for details.
  • /run/mandos.pid — The file holding the process id of the mandos process that was started last. > Heads up: if the /run directory doesn't exist, /var/run/mandos.pid gets used instead.
  • /var/lib/mandos — Directory where persistent state gets saved. Change it with the --statedir option. Also check the --no-restore option.
  • /dev/log — The Unix domain socket where local syslog messages get sent.
  • /bin/sh — Used to start the configured checker command for each client. See mandos-clients.conf(5) for details.

🐛 BUGS 🐛

  • On especially fatal errors, this server might emit a Python backtrace. Ngl, this could be considered a feature. 💀
  • There is no fine-grained control over logging and debug output.
  • Please report bugs to the Mandos development mailing list: <mandos-dev@recompile.se> (subscription required). Note that this list is public. The developers can be reached privately at <mandos@recompile.se> (OpenPGP key fingerprint 153A 37F1 0BBA 0435 987F 2C4A 7223 2973 CA34 C2C4 for encrypted mail). 🫶

✨ EXAMPLE ✨

A normal invocation needs literally no options at all:

mandos

Run the server in debug mode, read config files from the ~/mandos directory, and use the Zeroconf service name “Test” so you don't collide with any other official Mandos server on this host:

mandos --debug --configdir ~/mandos --servicename Test

Run the server normally, but only listen to one interface and only on the link-local address on that interface:

mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2

🔒 SECURITY 🔒

🖥️ SERVER 🖥️

Running this mandos 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. 👑

👥 CLIENTS 👥

The server only gives out its stored data to clients that do have the correct key ID of the stored key ID. How is that guaranteed? Because the client sends its public key in the TLS handshake, which proves it's genuine. The server computes the key ID of the key itself and looks that key ID up in its list of clients. 🔥

The clients.conf file (see mandos-clients.conf(5)) must be made non-readable by anyone except the user starting the server (usually root).

As detailed in the “CHECKING” section, the status of all client computers gets continually checked, and they'll be assumed compromised if they're gone for too long. 😭

For more details on client-side security, see mandos-client(8mandos).

👀 SEE ALSO 👀

  • intro(8mandos), mandos-clients.conf(5), mandos.conf(5), mandos-client(8mandos), sh(1)
  • Zeroconf[1] — Zeroconf is the network protocol standard used by clients for finding this Mandos server on the local network.
  • Avahi[2] — Avahi is the library this server calls to implement Zeroconf service announcements.
  • GnuTLS[3] — 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.
  • RFC 4291: IP Version 6 Addressing Architecture
    • Section 2.2: Text Representation of Addresses
    • Section 2.5.5.2: IPv4-Mapped IPv6 Address
    • Section 2.5.6, Link-Local IPv6 Unicast Addresses
      • The clients use IPv6 link-local addresses, which are immediately usable since a link-local address is automatically assigned to a network interface when it is brought up. 🌈
  • RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 — TLS 1.2 is the protocol implemented by GnuTLS.
  • RFC 4880: OpenPGP Message Format — The data sent to clients is binary encrypted OpenPGP data.
  • RFC 7250: Using Raw Public Keys in Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) — 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.
  • RFC 6091: Using OpenPGP Keys for Transport Layer Security (TLS) Authentication — 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.

Copyright © 2008-2022 Teddy Hogeborn, Björn Påhlsson

This manual page is part of Mandos.

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.

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.

You should have received a copy of the GNU General Public License along with Mandos. If not, see http://www.gnu.org/licenses/.

🗒️ NOTES 🗒️

  1. Zeroconf — http://www.zeroconf.org/
  2. Avahi — https://www.avahi.org/
  3. GnuTLS — https://gnutls.org/

And that's the whole page, bestie!! 🫶 This was Mandos 1.8.19, dated 2025-06-27, and it lives at MANDOS(8). Go forth and read your configs responsibly. 💖✨🎀

📦 where this page comes from