NAME
mandos-clients.conf - Configuration file for the Mandos server
SYNOPSIS
/etc/mandos/clients.conf
DESCRIPTION
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. All clients listed will be
regarded as valid, even if a client was declared invalid in a previous
run of the server.
The format starts with a [section header] which is either [DEFAULT] or
[client name]. The 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.
OPTIONS
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:
timeout = TIME
This option is optional.
The timeout is how long the server will wait (for either a
successful checker run or a client receiving its secret) until a
client is considered invalid - that is, ineligible to get the data
this server holds. By default Mandos will use 1 hour.
The TIME is specified as a space-separated number of values, each
of which is a number and a one-character suffix. The suffix must be
one of "d", "s", "m", "h", and "w" for days, seconds, minutes,
hours, and weeks, respectively. The values are added together to
give the total time value, so all of "330s", "110s 110s 110s", and
"5m 30s" will give a value of five minutes and thirty seconds.
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
above "timeout" occurs, at which time the client will be marked
invalid, and any running checker killed. The default interval is 5
minutes.
The format of TIME is the same as for timeout above.
checker = COMMAND
This option is optional.
This option allows you to override 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".
In addition to normal start time expansion, this option will also
be subject to runtime expansion; see the section called
"EXPANSION".
fingerprint = HEXSTRING
This option is required.
This option sets the OpenPGP fingerprint that identifies the public
key that clients authenticate themselves with through TLS. The
string needs to be in hexidecimal form, but spaces or upper/lower
case are not significant.
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 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.
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 $ENVVAR/foo/bar are
supported.
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.
EXPANSION
There are two forms of expansion: Start time expansion and runtime
expansion.
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 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.
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. See
the source code for details, and 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.
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.
EXAMPLE
[DEFAULT]
timeout = 1h
interval = 5m
checker = fping -q -- %%(host)s
# Client "foo"
[foo]
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 = 1m
# Client "bar"
[bar]
fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
secfile = /etc/mandos/bar-secret
timeout = 15m
SEE ALSO
mandos-keygen(8), mandos.conf(5), mandos(8)
COPYRIGHT
Copyright (C) 2008-2009 Teddy Hogeborn, Bjorn Pahlsson
This manual page 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.
This manual page 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 this program. If not, see http://www.gnu.org/licenses/.