bionic (5) mandos-clients.conf.5.gz

Provided by: mandos_1.7.19-1_all bug

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. 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 [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:

       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 -q -- %%(host)s”. 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 find one, outputs a checker option to check for the client’s
           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.

           This option sets the OpenPGP fingerprint that 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 $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 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.

   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 in the Mandos server. The currently allowed values for foo are:
       “approval_delay”, “approval_duration”, “created”, “enabled”, “expires”, “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.

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]
           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]
           fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27
           secfile = /etc/mandos/bar-secret
           timeout = PT15M
           approved_by_default = False
           approval_delay = PT30S

SEE ALSO

       intro(8mandos), mandos-keygen(8), mandos.conf(5), mandos(8), fping(8)

       RFC 3339: Date and Time on the Internet: Timestamps
           The time intervals are in the "duration" format, as specified in ABNF in Appendix A of RFC 3339.

       Copyright © 2008-2018 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/.