mandos-clients.conf
—
Configuration file for the Mandos server
/etc/mandos/clients.conf
The file /etc/mandos/clients.conf
is a configuration file for mandos(8), read by it at startup.
The file needs to list all clients that should be able to use
the service. The settings in this file can be overridden by
runtime changes to the server, which it saves across restarts.
(See the section called “PERSISTENT STATE” in
mandos(8).) However, any changes to this file (including adding and removing
clients) will, at startup, override changes done during runtime.
The format starts with a [
which is either
section
header
][DEFAULT]
or [
. The client
name
]client
name
can be anything, and is not tied to a host
name. Following the section header is any number of
“
=option
value
” entries,
with continuations in the style of RFC 822. “
: option
value
” is also accepted. Note that
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 (see the section called “EXPANSION”). Lines beginning with “#”
or “;” are ignored and may be used to provide
comments.
Note: all option values are subject to start time expansion, see the section called “EXPANSION”.
Unknown options are ignored. The used options are as follows:
approval_delay =
TIME
This option is optional.
How long to wait for external approval before resorting to
use the approved_by_default
value. The
default is “PT0S”, i.e. not to wait.
The format of TIME
is the same
as for timeout
below.
approval_duration =
TIME
This option is optional.
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.
This option 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
”. Note that
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 -q
--
%%(host)schecker
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. Time to take into consideration when changing this value is 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.
This option 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.
This option 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.
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.
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 $
are supported.
ENVVAR
/foo/bar
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”.
There are two forms of expansion: Start time expansion and runtime expansion.
Any string in an option value of the form
“%(
” will be replaced by the value of the option
foo
)sfoo
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 that this means that, in order to include an actual percent character (“%”) in an option value, two percent characters in a row (“%%”) must be entered.
This is currently only done for the checker
option.
Any string in an option value of the form
“%%(
” will be replaced by the value of the attribute
foo
)sfoo
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.
Note that 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.
The format for specifying times for timeout
and interval
is not very good.
The difference between
%%(
and
foo
)s%(
is
obscure.
foo
)s
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).
[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
intro(8mandos), mandos-keygen(8), mandos.conf(5), mandos(8), fping(8)
The time intervals are in the "duration" format, as specified in ABNF in Appendix A of RFC 3339.