1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY CONFNAME "mandos-clients.conf">
<!ENTITY CONFPATH "<filename>/etc/mandos/clients.conf</filename>">
<!ENTITY TIMESTAMP "2019-02-10">
<!ENTITY % common SYSTEM "common.ent">
%common;
]>
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>Mandos Manual</title>
<!-- NWalsh’s docbook scripts use this to generate the footer: -->
<productname>Mandos</productname>
<productnumber>&version;</productnumber>
<date>&TIMESTAMP;</date>
<authorgroup>
<author>
<firstname>Björn</firstname>
<surname>Påhlsson</surname>
<address>
<email>belorn@recompile.se</email>
</address>
</author>
<author>
<firstname>Teddy</firstname>
<surname>Hogeborn</surname>
<address>
<email>teddy@recompile.se</email>
</address>
</author>
</authorgroup>
<copyright>
<year>2008</year>
<year>2009</year>
<year>2010</year>
<year>2011</year>
<year>2012</year>
<year>2013</year>
<year>2014</year>
<year>2015</year>
<year>2016</year>
<year>2017</year>
<year>2018</year>
<year>2019</year>
<holder>Teddy Hogeborn</holder>
<holder>Björn Påhlsson</holder>
</copyright>
<xi:include href="legalnotice.xml"/>
</refentryinfo>
<refmeta>
<refentrytitle>&CONFNAME;</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname><filename>&CONFNAME;</filename></refname>
<refpurpose>
Configuration file for the Mandos server
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>&CONFPATH;</synopsis>
</refsynopsisdiv>
<refsect1 id="description">
<title>DESCRIPTION</title>
<para>
The file &CONFPATH; is a configuration file for <citerefentry
><refentrytitle>mandos</refentrytitle>
<manvolnum>8</manvolnum></citerefentry>, 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 <quote>PERSISTENT STATE</quote> in
<citerefentry><refentrytitle>mandos</refentrytitle><manvolnum
>8</manvolnum></citerefentry>.) However, any <emphasis
>changes</emphasis> to this file (including adding and removing
clients) will, at startup, override changes done during runtime.
</para>
<para>
The format starts with a <literal>[<replaceable>section
header</replaceable>]</literal> which is either
<literal>[DEFAULT]</literal> or <literal>[<replaceable>client
name</replaceable>]</literal>. The <replaceable>client
name</replaceable> can be anything, and is not tied to a host
name. Following the section header is any number of
<quote><varname><replaceable>option</replaceable
></varname>=<replaceable>value</replaceable></quote> entries,
with continuations in the style of RFC 822. <quote><varname
><replaceable>option</replaceable></varname>: <replaceable
>value</replaceable></quote> 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 <quote>DEFAULT</quote> section (see <xref
linkend="expansion"/>). Lines beginning with <quote>#</quote>
or <quote>;</quote> are ignored and may be used to provide
comments.
</para>
</refsect1>
<refsect1 id="options">
<title>OPTIONS</title>
<para>
<emphasis>Note:</emphasis> all option values are subject to
start time expansion, see <xref linkend="expansion"/>.
</para>
<para>
Unknown options are ignored. The used options are as follows:
</para>
<variablelist>
<varlistentry>
<term><option>approval_delay<literal> = </literal><replaceable
>TIME</replaceable></option></term>
<listitem>
<para>
This option is <emphasis>optional</emphasis>.
</para>
<para>
How long to wait for external approval before resorting to
use the <option>approved_by_default</option> value. The
default is <quote>PT0S</quote>, i.e. not to wait.
</para>
<para>
The format of <replaceable>TIME</replaceable> is the same
as for <varname>timeout</varname> below.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>approval_duration<literal> = </literal
><replaceable>TIME</replaceable></option></term>
<listitem>
<para>
This option is <emphasis>optional</emphasis>.
</para>
<para>
How long an external approval lasts. The default is 1
second.
</para>
<para>
The format of <replaceable>TIME</replaceable> is the same
as for <varname>timeout</varname> below.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>approved_by_default<literal> = </literal
>{ <literal >1</literal> | <literal>yes</literal> | <literal
>true</literal> | <literal>on</literal> | <literal
>0</literal> | <literal>no</literal> | <literal
>false</literal> | <literal>off</literal> }</option></term>
<listitem>
<para>
Whether to approve a client by default after
the <option>approval_delay</option>. The default
is <quote>True</quote>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>checker<literal> = </literal><replaceable
>COMMAND</replaceable></option></term>
<listitem>
<para>
This option is <emphasis>optional</emphasis>.
</para>
<para>
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
<quote><command><filename>/bin/sh</filename>
<option>-c</option></command></quote>, so
<varname>PATH</varname> will be searched. The default
value for the checker command is <quote><literal
><command>fping</command> <option>-q</option> <option
>--</option> %%(host)s</literal></quote>. Note that
<command>mandos-keygen</command>, 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 <option>checker</option> option to check for the
client’s SSH key fingerprint – this is more secure against
spoofing.
</para>
<para>
In addition to normal start time expansion, this option
will also be subject to runtime expansion; see <xref
linkend="expansion"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>extended_timeout<literal> = </literal><replaceable
>TIME</replaceable></option></term>
<listitem>
<para>
This option is <emphasis>optional</emphasis>.
</para>
<para>
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.
</para>
<para>
The format of <replaceable>TIME</replaceable> is the same
as for <varname>timeout</varname> below.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>fingerprint<literal> = </literal
><replaceable>HEXSTRING</replaceable></option></term>
<listitem>
<para>
This option is <emphasis>required</emphasis>.
</para>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>key_id<literal> = </literal
><replaceable>HEXSTRING</replaceable></option></term>
<listitem>
<para>
This option is <emphasis>optional</emphasis>.
</para>
<para>
This option sets the certificate key ID 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option><literal>host = </literal><replaceable
>STRING</replaceable></option></term>
<listitem>
<para>
This option is <emphasis>optional</emphasis>, but highly
<emphasis>recommended</emphasis> unless the
<option>checker</option> option is modified to a
non-standard value without <quote>%%(host)s</quote> in it.
</para>
<para>
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 <option>checker</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>interval<literal> = </literal><replaceable
>TIME</replaceable></option></term>
<listitem>
<para>
This option is <emphasis>optional</emphasis>.
</para>
<para>
How often to run the checker to confirm that a client is
still up. <emphasis>Note:</emphasis> 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
<quote><varname>timeout</varname></quote> occurs, at which
time the client will be disabled, and any running checker
killed. The default interval is 2 minutes.
</para>
<para>
The format of <replaceable>TIME</replaceable> is the same
as for <varname>timeout</varname> below.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>secfile<literal> = </literal><replaceable
>FILENAME</replaceable></option></term>
<listitem>
<para>
This option is only used if <option>secret</option> is not
specified, in which case this option is
<emphasis>required</emphasis>.
</para>
<para>
Similar to the <option>secret</option>, except the secret
data is in an external file. The contents of the file
should <emphasis>not</emphasis> be base64-encoded, but
will be sent to clients verbatim.
</para>
<para>
File names of the form <filename>~user/foo/bar</filename>
and <filename>$<envar>ENVVAR</envar>/foo/bar</filename>
are supported.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>secret<literal> = </literal><replaceable
>BASE64_ENCODED_DATA</replaceable></option></term>
<listitem>
<para>
If this option is not specified, the <option
>secfile</option> option is <emphasis>required</emphasis>
to be present.
</para>
<para>
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 <option>key_id</option>
or <option>fingerprint</option>. This should, of course,
be OpenPGP encrypted data, decryptable only by the client.
The program <citerefentry><refentrytitle><command
>mandos-keygen</command></refentrytitle><manvolnum
>8</manvolnum></citerefentry> can, using its
<option>--password</option> option, be used to generate
this, if desired.
</para>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>timeout<literal> = </literal><replaceable
>TIME</replaceable></option></term>
<listitem>
<para>
This option is <emphasis>optional</emphasis>.
</para>
<para>
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
<option>extended_timeout</option> option.
</para>
<para>
The <replaceable>TIME</replaceable> is specified as an RFC
3339 duration; for example
<quote><literal>P1Y2M3DT4H5M6S</literal></quote> 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>enabled<literal> = </literal>{ <literal
>1</literal> | <literal>yes</literal> | <literal>true</literal
> | <literal >on</literal> | <literal>0</literal> | <literal
>no</literal> | <literal>false</literal> | <literal
>off</literal> }</option></term>
<listitem>
<para>
Whether this client should be enabled by default. The
default is <quote>true</quote>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="expansion">
<title>EXPANSION</title>
<para>
There are two forms of expansion: Start time expansion and
runtime expansion.
</para>
<refsect2 id="start_time_expansion">
<title>START TIME EXPANSION</title>
<para>
Any string in an option value of the form
<quote><literal>%(<replaceable>foo</replaceable>)s</literal
></quote> will be replaced by the value of the option
<varname>foo</varname> either in the same section, or, if it
does not exist there, the <literal>[DEFAULT]</literal>
section. This is done at start time, when the configuration
file is read.
</para>
<para>
Note that this means that, in order to include an actual
percent character (<quote>%</quote>) in an option value, two
percent characters in a row (<quote>%%</quote>) must be
entered.
</para>
</refsect2>
<refsect2 id="runtime_expansion">
<title>RUNTIME EXPANSION</title>
<para>
This is currently only done for the <varname>checker</varname>
option.
</para>
<para>
Any string in an option value of the form
<quote><literal>%%(<replaceable>foo</replaceable>)s</literal
></quote> will be replaced by the value of the attribute
<varname>foo</varname> of the internal
<quote><classname>Client</classname></quote> object in the
Mandos server. The currently allowed values for
<replaceable>foo</replaceable> are:
<quote><literal>approval_delay</literal></quote>,
<quote><literal>approval_duration</literal></quote>,
<quote><literal>created</literal></quote>,
<quote><literal>enabled</literal></quote>,
<quote><literal>expires</literal></quote>,
<quote><literal>key_id</literal></quote>,
<quote><literal>fingerprint</literal></quote>,
<quote><literal>host</literal></quote>,
<quote><literal>interval</literal></quote>,
<quote><literal>last_approval_request</literal></quote>,
<quote><literal>last_checked_ok</literal></quote>,
<quote><literal>last_enabled</literal></quote>,
<quote><literal>name</literal></quote>,
<quote><literal>timeout</literal></quote>, and, if using
D-Bus, <quote><literal>dbus_object_path</literal></quote>.
See the source code for details. <emphasis role="strong"
>Currently, <emphasis>none</emphasis> of these attributes
except <quote><literal>host</literal></quote> are guaranteed
to be valid in future versions.</emphasis> Therefore, please
let the authors know of any attributes that are useful so they
may be preserved to any new versions of this software.
</para>
<para>
Note that this means that, in order to include an actual
percent character (<quote>%</quote>) in a
<varname>checker</varname> option, <emphasis>four</emphasis>
percent characters in a row (<quote>%%%%</quote>) must be
entered. Also, a bad format here will lead to an immediate
but <emphasis>silent</emphasis> run-time fatal exit; debug
mode is needed to expose an error of this kind.
</para>
</refsect2>
</refsect1>
<refsect1 id="files">
<title>FILES</title>
<para>
The file described here is &CONFPATH;
</para>
</refsect1>
<refsect1 id="bugs">
<title>BUGS</title>
<para>
The format for specifying times for <varname>timeout</varname>
and <varname>interval</varname> is not very good.
</para>
<para>
The difference between
<literal>%%(<replaceable>foo</replaceable>)s</literal> and
<literal>%(<replaceable>foo</replaceable>)s</literal> is
obscure.
</para>
<xi:include href="bugs.xml"/>
</refsect1>
<refsect1 id="example">
<title>EXAMPLE</title>
<informalexample>
<programlisting>
[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
</programlisting>
</informalexample>
</refsect1>
<refsect1 id="see_also">
<title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>intro</refentrytitle>
<manvolnum>8mandos</manvolnum></citerefentry>,
<citerefentry><refentrytitle>mandos-keygen</refentrytitle>
<manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>mandos.conf</refentrytitle>
<manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>mandos</refentrytitle>
<manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>fping</refentrytitle>
<manvolnum>8</manvolnum></citerefentry>
</para>
<variablelist>
<varlistentry>
<term>
RFC 3339: <citetitle>Date and Time on the Internet:
Timestamps</citetitle>
</term>
<listitem>
<para>
The time intervals are in the "duration" format, as
specified in ABNF in Appendix A of RFC 3339.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!-- Local Variables: -->
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
<!-- time-stamp-end: "[\"']>" -->
<!-- time-stamp-format: "%:y-%02m-%02d" -->
<!-- End: -->
|