MANDOS-CLIENTS.CO(5)

📦

version 1.8.19 · 3 versions

1.8.19 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
1.8.14 · ubuntu jammy
1.8.16 · debian bookworm, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 MANDOS-CLIENTS.CO(5) 💖

Mandos Manual — mandos-clients.conf

ok bestie sit DOWN because we're about to read the config file that makes the whole Mandos server actually do its thing, and honestly? it's giving "important but also kinda cozy". let's go ✨

🌸 NAME 🌸

mandos-clients.conf — the configuration file for the Mandos server, periodt.

🎀 SYNOPSIS 🎀

/etc/mandos/clients.conf

🦋 DESCRIPTION 🦋

so. the file /etc/mandos/clients.conf is a config file for mandos(8), and the server reads it at startup, no cap. this file needs to list every single client that should be able to use the service — like, all of them, you can't just vibe and skip some. 💅

here's the tea tho: the settings in this file can be overridden by runtime changes to the server, and the server saves those across restarts (peep the section called “PERSISTENT STATE” in mandos(8) for the full lore). BUT — and this is the important part — any changes to this file (yes, including adding and removing clients) will, at startup, override whatever changes got done during runtime. the file wins. it always wins. main character energy honestly. 👑

the format starts with a [section header] which is either [DEFAULT] or [client name]. and get this: the client name can be anything — it is not tied to a host name. it's just a name, bestie, live your truth. 🌈

after the section header comes any number of option=value entries, with continuations in the style of RFC 822. option: value is also accepted (both are fine, we don't gatekeep). quick note: leading whitespace is removed from values. values can contain format strings which refer to other values in the same section, or values in the DEFAULT section (go look at the section called “EXPANSION” for that whole situation).

and finally: lines beginning with # or ; are ignored and may be used to provide comments. so go off, annotate your config, it's your journal now 📝

✨ OPTIONS ✨

Note: all option values are subject to start time expansion, see the section called “EXPANSION”.

unknown options are ignored (the server simply does not perceive them 💀). the used options are as follows:

approval_delay = TIME — this option is optional. it's how long to wait for external approval before resorting to using the approved_by_default value. the default is PT0S, i.e. not to wait at all, zero patience, iconic. the format of TIME is the same as for timeout below.
approval_duration = TIME — this option is optional. it's how long an external approval lasts. the default is 1 second. the format of TIME is the same as for timeout below.
approved_by_default = { 1 | yes | true | on | 0 | no | false | off } — whether to approve a client by default after the approval_delay. the default is True.
checker = COMMAND — this option is optional. it overrides the default shell command that the server will use to check if the client is still up. any output of the command will be ignored — only the exit code is checked: if the exit code of the command is zero, the client is considered up. the command will be run using /bin/sh -c, so PATH will be searched. the default value for the checker command is fping -q -- %%(host)s.

quick lore drop: mandos-keygen, when generating output to be inserted into this file, normally looks for an SSH server on the Mandos client, and, if it finds one, outputs a checker option to check for the client's SSH key fingerprint — this is more secure against spoofing. 🛡️

in addition to normal start time expansion, this option will also be subject to runtime expansion; see the section called “EXPANSION”.

extended_timeout = TIME — this option is optional. extended timeout is an added timeout that is given once after a password has been sent successfully to a client. the timeout is by default longer than the normal timeout, and is used for handling the extra long downtime while a machine is booting up. the things to take into consideration when changing this value are file system checks and quota checks. the default value is 15 minutes. the format of TIME is the same as for timeout below.
fingerprint = HEXSTRING — this option is required if the key_id is not set, and optional otherwise. it sets the OpenPGP fingerprint that (before GnuTLS 3.6.0) identified the public key that clients authenticate themselves with through TLS. the string needs to be in hexadecimal form, but spaces or upper/lower case are not significant. 🔑
key_id = HEXSTRING — this option is required if the fingerprint is not set, and optional otherwise. it sets the certificate key ID that (with GnuTLS 3.6.6 or later) identifies the public key that clients authenticate themselves with through TLS. the string needs to be in hexadecimal form, but spaces or upper/lower case are not significant.
host = STRING — this option is optional, but highly recommended unless the checker option is modified to a non-standard value without %%(host)s in it. it's the host name for this client. this is not used by the server directly, but can be, and is by default, used by the checker. see the checker option. 🏠
interval = TIME — this option is optional. how often to run the checker to confirm that a client is still up.

Note: a new checker will not be started if an old one is still running. the server will wait for a checker to complete until the below “timeout” occurs, at which time the client will be disabled, and any running checker killed. 💀

the default interval is 2 minutes. the format of TIME is the same as for timeout below.

secfile = FILENAME — this option is only used if secret is not specified, in which case this option is required. it's similar to the secret, except the secret data is in an external file. the contents of the file should not be base64-encoded, but will be sent to clients verbatim. file names of the form ~user/foo/bar and $ENVVAR/foo/bar are supported. 📁
secret = BASE64_ENCODED_DATA — if this option is not specified, the secfile option is required to be present. if present, this option must be set to a string of base64-encoded binary data. it will be decoded and sent to the client matching the above key_id or fingerprint. this should, of course, be OpenPGP encrypted data, decryptable only by the client. the program mandos-keygen(8) can, using its --password option, be used to generate this, if desired.

Note: this value of this option will probably be very long. a useful feature to avoid having unreadably-long lines is that a line beginning with white space adds to the value of the previous line, RFC 822-style. 🫶

timeout = TIME — this option is optional. the timeout is how long the server will wait, after a successful checker run, until a client is disabled and not allowed to get the data this server holds. by default Mandos will use 5 minutes. see also the extended_timeout option. the TIME is specified as an RFC 3339 duration; for example P1Y2M3DT4H5M6S meaning one year, two months, three days, four hours, five minutes, and six seconds. some values can be omitted, see RFC 3339 Appendix A for details. ⏰
enabled = { 1 | yes | true | on | 0 | no | false | off } — whether this client should be enabled by default. the default is true.

🌈 EXPANSION 🌈

there are two forms of expansion: Start time expansion and runtime expansion. two flavors, both slay, let's meet them 💅

⭐ START TIME EXPANSION ⭐

any string in an option value of the form %(foo)s will be replaced by the value of the option foo either in the same section, or, if it does not exist there, the [DEFAULT] section. this is done at start time, when the configuration file is read.

Note: this means that, in order to include an actual percent character (%) in an option value, two percent characters in a row (%%) must be entered. don't forget, or the config will simply Not Do The Thing. 🙈

🧚 RUNTIME EXPANSION 🧚

this is currently only done for the checker option.

any string in an option value of the form %%(foo)s will be replaced by the value of the attribute foo of the internal “Client” object in the Mandos server. the currently allowed values for foo are: approval_delay, approval_duration, created, enabled, expires, key_id, fingerprint, host, interval, last_approval_request, last_checked_ok, last_enabled, name, timeout, and, if using D-Bus, dbus_object_path. see the source code for details.

currently, none of these attributes except host are guaranteed to be valid in future versions. therefore, please let the authors know of any attributes that are useful so they may be preserved to any new versions of this software. (be the change you want to see in the changelog, bestie 🫶)

Note: this means that, in order to include an actual percent character (%) in a checker option, four percent characters in a row (%%%%) must be entered. also, a bad format here will lead to an immediate but silent run-time fatal exit; debug mode is needed to expose an error of this kind. yes, silent. it will simply perish and not tell you why. 😭

🍓 FILES 🍓

the file described here is /etc/mandos/clients.conf

💀 BUGS 💀

the format for specifying times for timeout and interval is not very good.
the difference between %%(foo)s and %(foo)s is obscure.

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 🌟

[DEFAULT]
timeout = PT5M
interval = PT2M
checker = fping -q -- %%(host)s

# Client "foo"
[foo]
key_id = 788cd77115cd0bb7b2d5e0ae8496f6b48149d5e712c652076b1fd2d957ef7c1f
fingerprint =  7788 2722 5BA7 DE53 9C5A  7CFA 59CF F7CD BD9A 5920
secret =
        hQIOA6QdEjBs2L/HEAf/TCyrDe5Xnm9esa+Pb/vWF9CUqfn4srzVgSu234
        REJMVv7lBSrPE2132Lmd2gqF1HeLKDJRSVxJpt6xoWOChGHg+TMyXDxK+N
        Xl89vGvdU1XfhKkVm9MDLOgT5ECDPysDGHFPDhqHOSu3Kaw2DWMV/iH9vz
        3Z20erVNbdcvyBnuojcoWO/6yfB5EQO0BXp7kcyy00USA3CjD5FGZdoQGI
        Tb8A/ar0tVA5crSQmaSotm6KmNLhrFnZ5BxX+TiE+eTUTqSloWRY6VAvqW
        QHC7OASxK5E6RXPBuFH5IohUA2Qbk5AHt99pYvsIPX88j2rWauOokoiKZo
        t/9leJ8VxO5l3wf/U64IH8bkPIoWmWZfd/nqh4uwGNbCgKMyT+AnvH7kMJ
        3i7DivfWl2mKLV0PyPHUNva0VQxX6yYjcOhj1R6fCr/at8/NSLe2OhLchz
        dC+Ls9h+kvJXgF8Sisv+Wk/1RadPLFmraRlqvJwt6Ww21LpiXqXHV2mIgq
        WnR98YgSvUi3TJHrUQiNc9YyBzuRo0AjgG2C9qiE3FM+Y28+iQ/sR3+bFs
        zYuZKVTObqiIslwXu7imO0cvvFRgJF/6u3HNFQ4LUTGhiM3FQmC6NNlF3/
        vJM2hwRDMcJqDd54Twx90Wh+tYz0z7QMsK4ANXWHHWHR0JchnLWmenzbtW
        5MHdW9AYsNJZAQSOpirE4Xi31CSlWAi9KV+cUCmWF5zOFy1x23P6PjdaRm
        4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O
        QlnHIvPzEArRQLo=
host = foo.example.org
interval = PT1M

# Client "bar"
[bar]
key_id = F90C7A81D72D1EA69A51031A91FF8885F36C8B46D155C8C58709A4C99AE9E361
fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
secfile = /etc/mandos/bar-secret
timeout = PT15M
approved_by_default = False
approval_delay = PT30S

and that's part 1, bestie!! more coming, don't go anywhere 💜

💖 SEE ALSO 💖

okay so if you wanna go down the rabbit hole (and bestie, you know you do 🕳️✨), here's the whole friend group:

intro(8mandos) — the lil intro page for the mandos section of the manual 🫶
mandos-keygen(8) — the key generator, go make yourself some keys, slay 🔑
mandos.conf(5) — the main config file, iykyk 📝
mandos(8) — the big one, the main character 👑
fping(8) — ping but make it ✨multicast✨, the icon it is 🏓

RFC 3339: Date and Time on the Internet: Timestamps

so like, the time intervals in this whole thing? they're in the "duration" format, which is specified in ABNF in Appendix A of RFC 3339. that's the receipt, that's the source, no cap 📜✨

🎀 COPYRIGHT 🎀

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

okay so this manual page? it's part of Mandos. it's in the family 💖

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. so like, either/or, your call bestie 💅

Mandos is distributed in the hope that it will be useful, but — and listen, this part is IMPORTANT, don't skip it 🙈 — WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. like, it's giving "we hope this slays but we're not promising anything." see the GNU General Public License for more details, fr fr 😭

You should have received a copy of the GNU General Public License along with Mandos. If not, see http://www.gnu.org/licenses/ — go get your copy, don't be that person 🫶

okay bestie that's the whole page, we did it 🎉 and for the lil sign-off: this is Mandos 1.8.19, dated 2025-06-27, and it lives at section MANDOS-CLIENTS.CO(5). literally iconic, no notes 💅✨🌸🦋

📦 where this page comes from

debian trixie: mandos 1.8.19-1 · GPL-3.0-or-later
ubuntu questing: mandos 1.8.19-1
ubuntu resolute: mandos 1.8.19-1build1 · GPL-3.0-or-later
ubuntu stonking: mandos 1.8.19-1.1 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms