'\" t
.\"     Title: mandos-clients.conf
.\"    Author: Bj\(:orn P\(oahlsson <belorn@recompile.se>
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 2014-06-22
.\"    Manual: Mandos Manual
.\"    Source: Mandos 1.6.9
.\"  Language: English
.\"
.TH "MANDOS\-CLIENTS\&.CO" "5" "2014\-06\-22" "Mandos 1.6.9" "Mandos Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
mandos-clients.conf \- Configuration file for the Mandos server
.SH "SYNOPSIS"
.sp
.nf
/etc/mandos/clients\&.conf
.fi
.SH "DESCRIPTION"
.PP
The file
/etc/mandos/clients\&.conf
is a configuration file for
\fBmandos\fR(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
\(lqPERSISTENT STATE\(rq
in
\fBmandos\fR(8)\&.) However, any
\fIchanges\fR
to this file (including adding and removing clients) will, at startup, override changes done during runtime\&.
.PP
The format starts with a
[\fIsection header\fR]
which is either
[DEFAULT]
or
[\fIclient name\fR]\&. The
\fIclient name\fR
can be anything, and is not tied to a host name\&. Following the section header is any number of
\(lq\fI\fIoption\fR\fR=\fIvalue\fR\(rq
entries, with continuations in the style of RFC 822\&.
\(lq\fI\fIoption\fR\fR: \fIvalue\fR\(rq
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
\(lqDEFAULT\(rq
section (see
the section called \(lqEXPANSION\(rq)\&. Lines beginning with
\(lq#\(rq
or
\(lq;\(rq
are ignored and may be used to provide comments\&.
.SH "OPTIONS"
.PP
\fINote:\fR
all option values are subject to start time expansion, see
the section called \(lqEXPANSION\(rq\&.
.PP
Unknown options are ignored\&. The used options are as follows:
.PP
\fBapproval_delay\fR\fB = \fR\fB\fITIME\fR\fR
.RS 4
This option is
\fIoptional\fR\&.
.sp
How long to wait for external approval before resorting to use the
\fBapproved_by_default\fR
value\&. The default is
\(lqPT0S\(rq, i\&.e\&. not to wait\&.
.sp
The format of
\fITIME\fR
is the same as for
\fItimeout\fR
below\&.
.RE
.PP
\fBapproval_duration\fR\fB = \fR\fB\fITIME\fR\fR
.RS 4
This option is
\fIoptional\fR\&.
.sp
How long an external approval lasts\&. The default is 1 second\&.
.sp
The format of
\fITIME\fR
is the same as for
\fItimeout\fR
below\&.
.RE
.PP
\fBapproved_by_default\fR\fB = \fR\fB{ \fR\fB1\fR\fB | \fR\fByes\fR\fB | \fR\fBtrue\fR\fB | \fR\fBon\fR\fB | \fR\fB0\fR\fB | \fR\fBno\fR\fB | \fR\fBfalse\fR\fB | \fR\fBoff\fR\fB }\fR
.RS 4
Whether to approve a client by default after the
\fBapproval_delay\fR\&. The default is
\(lqTrue\(rq\&.
.RE
.PP
\fBchecker\fR\fB = \fR\fB\fICOMMAND\fR\fR
.RS 4
This option is
\fIoptional\fR\&.
.sp
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
\(lq\fB/bin/sh\fR\fB \fR\fB\fB\-c\fR\fR\(rq, so
\fIPATH\fR
will be searched\&. The default value for the checker command is
\(lq\fBfping\fR \fB\-q\fR \fB\-\-\fR %%(host)s\(rq\&. Note that
\fBmandos\-keygen\fR, 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
\fBchecker\fR
option to check for the client\(cqs key fingerprint \(en this is more secure against spoofing\&.
.sp
In addition to normal start time expansion, this option will also be subject to runtime expansion; see
the section called \(lqEXPANSION\(rq\&.
.RE
.PP
\fBextended_timeout\fR\fB = \fR\fB\fITIME\fR\fR
.RS 4
This option is
\fIoptional\fR\&.
.sp
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\&.
.sp
The format of
\fITIME\fR
is the same as for
\fItimeout\fR
below\&.
.RE
.PP
\fBfingerprint\fR\fB = \fR\fB\fIHEXSTRING\fR\fR
.RS 4
This option is
\fIrequired\fR\&.
.sp
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\&.
.RE
.PP
\fBhost = \fR\fB\fISTRING\fR\fR
.RS 4
This option is
\fIoptional\fR, but highly
\fIrecommended\fR
unless the
\fBchecker\fR
option is modified to a non\-standard value without
\(lq%%(host)s\(rq
in it\&.
.sp
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
\fBchecker\fR
option\&.
.RE
.PP
\fBinterval\fR\fB = \fR\fB\fITIME\fR\fR
.RS 4
This option is
\fIoptional\fR\&.
.sp
How often to run the checker to confirm that a client is still up\&.
\fINote:\fR
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
\(lq\fItimeout\fR\(rq
occurs, at which time the client will be disabled, and any running checker killed\&. The default interval is 2 minutes\&.
.sp
The format of
\fITIME\fR
is the same as for
\fItimeout\fR
below\&.
.RE
.PP
\fBsecfile\fR\fB = \fR\fB\fIFILENAME\fR\fR
.RS 4
This option is only used if
\fBsecret\fR
is not specified, in which case this option is
\fIrequired\fR\&.
.sp
Similar to the
\fBsecret\fR, except the secret data is in an external file\&. The contents of the file should
\fInot\fR
be base64\-encoded, but will be sent to clients verbatim\&.
.sp
File names of the form
~user/foo/bar
and
$\fBENVVAR\fR/foo/bar
are supported\&.
.RE
.PP
\fBsecret\fR\fB = \fR\fB\fIBASE64_ENCODED_DATA\fR\fR
.RS 4
If this option is not specified, the
\fBsecfile\fR
option is
\fIrequired\fR
to be present\&.
.sp
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
\fBfingerprint\fR\&. This should, of course, be OpenPGP encrypted data, decryptable only by the client\&. The program
\fBmandos-keygen\fR(8)
can, using its
\fB\-\-password\fR
option, be used to generate this, if desired\&.
.sp
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\&.
.RE
.PP
\fBtimeout\fR\fB = \fR\fB\fITIME\fR\fR
.RS 4
This option is
\fIoptional\fR\&.
.sp
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
\fBextended_timeout\fR
option\&.
.sp
The
\fITIME\fR
is specified as an RFC 3339 duration; for example
\(lqP1Y2M3DT4H5M6S\(rq
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\&.
.RE
.PP
\fBenabled\fR\fB = \fR\fB{ \fR\fB1\fR\fB | \fR\fByes\fR\fB | \fR\fBtrue\fR\fB | \fR\fBon\fR\fB | \fR\fB0\fR\fB | \fR\fBno\fR\fB | \fR\fBfalse\fR\fB | \fR\fBoff\fR\fB }\fR
.RS 4
Whether this client should be enabled by default\&. The default is
\(lqtrue\(rq\&.
.RE
.SH "EXPANSION"
.PP
There are two forms of expansion: Start time expansion and runtime expansion\&.
.SS "START TIME EXPANSION"
.PP
Any string in an option value of the form
\(lq%(\fIfoo\fR)s\(rq
will be replaced by the value of the option
\fIfoo\fR
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\&.
.PP
Note that this means that, in order to include an actual percent character (\(lq%\(rq) in an option value, two percent characters in a row (\(lq%%\(rq) must be entered\&.
.SS "RUNTIME EXPANSION"
.PP
This is currently only done for the
\fIchecker\fR
option\&.
.PP
Any string in an option value of the form
\(lq%%(\fIfoo\fR)s\(rq
will be replaced by the value of the attribute
\fIfoo\fR
of the internal
\(lqClient\(rq
object in the Mandos server\&. The currently allowed values for
\fIfoo\fR
are:
\(lqapproval_delay\(rq,
\(lqapproval_duration\(rq,
\(lqcreated\(rq,
\(lqenabled\(rq,
\(lqexpires\(rq,
\(lqfingerprint\(rq,
\(lqhost\(rq,
\(lqinterval\(rq,
\(lqlast_approval_request\(rq,
\(lqlast_checked_ok\(rq,
\(lqlast_enabled\(rq,
\(lqname\(rq,
\(lqtimeout\(rq, and, if using D\-Bus,
\(lqdbus_object_path\(rq\&. See the source code for details\&.
\fBCurrently, \fR\fB\fInone\fR\fR\fB of these attributes except \fR\fB\(lqhost\(rq\fR\fB are guaranteed to be valid in future versions\&.\fR
Therefore, please let the authors know of any attributes that are useful so they may be preserved to any new versions of this software\&.
.PP
Note that this means that, in order to include an actual percent character (\(lq%\(rq) in a
\fIchecker\fR
option,
\fIfour\fR
percent characters in a row (\(lq%%%%\(rq) must be entered\&. Also, a bad format here will lead to an immediate but
\fIsilent\fR
run\-time fatal exit; debug mode is needed to expose an error of this kind\&.
.SH "FILES"
.PP
The file described here is
/etc/mandos/clients\&.conf
.SH "BUGS"
.PP
The format for specifying times for
\fItimeout\fR
and
\fIinterval\fR
is not very good\&.
.PP
The difference between
%%(\fIfoo\fR)s
and
%(\fIfoo\fR)s
is obscure\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
[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
      
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\fBintro\fR(8mandos),
\fBmandos-keygen\fR(8),
\fBmandos.conf\fR(5),
\fBmandos\fR(8),
\fBfping\fR(8)
.PP
RFC 3339: Date and Time on the Internet: Timestamps
.RS 4
The time intervals are in the "duration" format, as specified in ABNF in Appendix A of RFC 3339\&.
.RE
.SH "COPYRIGHT"
.br
Copyright \(co 2008-2012 Teddy Hogeborn, Bj\(:orn P\(oahlsson
.br
.PP
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\&.
.PP
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\&.
.PP
You should have received a copy of the
GNU
General Public License along with this program\&. If not, see
\m[blue]\fBhttp://www\&.gnu\&.org/licenses/\fR\m[]\&.
.sp