/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
1
<?xml version="1.0" encoding="UTF-8"?>
24.1.23 by Björn Påhlsson
Added manual pages for:
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
24.1.23 by Björn Påhlsson
Added manual pages for:
4
<!ENTITY VERSION "1.0">
5
<!ENTITY COMMANDNAME "mandos">
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
6
<!ENTITY OVERVIEW SYSTEM "overview.xml">
24.1.23 by Björn Påhlsson
Added manual pages for:
7
]>
8
9
<refentry>
10
  <refentryinfo>
11
    <title>&COMMANDNAME;</title>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
12
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
24.1.23 by Björn Påhlsson
Added manual pages for:
13
    <productname>&COMMANDNAME;</productname>
14
    <productnumber>&VERSION;</productnumber>
15
    <authorgroup>
16
      <author>
17
	<firstname>Björn</firstname>
18
	<surname>Påhlsson</surname>
19
	<address>
20
	  <email>belorn@fukt.bsnet.se</email>
21
	</address>
22
      </author>
23
      <author>
24
	<firstname>Teddy</firstname>
25
	<surname>Hogeborn</surname>
26
	<address>
27
	  <email>teddy@fukt.bsnet.se</email>
28
	</address>
29
      </author>
30
    </authorgroup>
31
    <copyright>
32
      <year>2008</year>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
33
      <holder>Teddy Hogeborn</holder>
34
      <holder>Björn Påhlsson</holder>
24.1.23 by Björn Påhlsson
Added manual pages for:
35
    </copyright>
36
    <legalnotice>
37
      <para>
38
	This manual page is free software: you can redistribute it
39
	and/or modify it under the terms of the GNU General Public
40
	License as published by the Free Software Foundation,
41
	either version 3 of the License, or (at your option) any
42
	later version.
43
      </para>
44
45
      <para>
46
	This manual page is distributed in the hope that it will
47
	be useful, but WITHOUT ANY WARRANTY; without even the
48
	implied warranty of MERCHANTABILITY or FITNESS FOR A
49
	PARTICULAR PURPOSE.  See the GNU General Public License
50
	for more details.
51
      </para>
52
53
      <para>
54
	You should have received a copy of the GNU General Public
55
	License along with this program; If not, see
56
	<ulink url="http://www.gnu.org/licenses/"/>.
57
      </para>
58
    </legalnotice>
59
  </refentryinfo>
60
61
  <refmeta>
62
    <refentrytitle>&COMMANDNAME;</refentrytitle>
24.1.24 by Björn Påhlsson
minor edits
63
    <manvolnum>8</manvolnum>
24.1.23 by Björn Påhlsson
Added manual pages for:
64
  </refmeta>
65
  
66
  <refnamediv>
67
    <refname><command>&COMMANDNAME;</command></refname>
68
    <refpurpose>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
69
      Sends encrypted passwords to authenticated Mandos clients
24.1.23 by Björn Påhlsson
Added manual pages for:
70
    </refpurpose>
71
  </refnamediv>
72
73
  <refsynopsisdiv>
74
    <cmdsynopsis>
75
      <command>&COMMANDNAME;</command>
85 by Teddy Hogeborn
* mandos.xml (SYNOPSIS): Removed unnecessary 'choice="opt"' from <arg>
76
      <arg>--interface<arg choice="plain">IF</arg></arg>
77
      <arg>--address<arg choice="plain">ADDRESS</arg></arg>
78
      <arg>--port<arg choice="plain">PORT</arg></arg>
79
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
80
      <arg>--servicename<arg choice="plain">NAME</arg></arg>
81
      <arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
82
      <arg>--debug</arg>
83
    </cmdsynopsis>
84
    <cmdsynopsis>
85
      <command>&COMMANDNAME;</command>
86
      <arg>-i<arg choice="plain">IF</arg></arg>
87
      <arg>-a<arg choice="plain">ADDRESS</arg></arg>
88
      <arg>-p<arg choice="plain">PORT</arg></arg>
89
      <arg>--priority<arg choice="plain">PRIORITY</arg></arg>
90
      <arg>--servicename<arg choice="plain">NAME</arg></arg>
91
      <arg>--configdir<arg choice="plain">DIRECTORY</arg></arg>
92
      <arg>--debug</arg>
93
    </cmdsynopsis>
94
    <cmdsynopsis>
95
      <command>&COMMANDNAME;</command>
96
      <group choice="req">
97
	<arg choice="plain">-h</arg>
98
	<arg choice="plain">--help</arg>
99
      </group>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
100
    </cmdsynopsis>
101
    <cmdsynopsis>
102
      <command>&COMMANDNAME;</command>
103
      <arg choice="plain">--version</arg>
104
    </cmdsynopsis>
105
    <cmdsynopsis>
106
      <command>&COMMANDNAME;</command>
107
      <arg choice="plain">--check</arg>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
108
    </cmdsynopsis>
24.1.23 by Björn Påhlsson
Added manual pages for:
109
  </refsynopsisdiv>
110
111
  <refsect1 id="description">
112
    <title>DESCRIPTION</title>
113
    <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
114
      <command>&COMMANDNAME;</command> is a server daemon which
115
      handles incoming request for passwords for a pre-defined list of
116
      client host computers.  The Mandos server uses Zeroconf to
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
117
      announce itself on the local network, and uses TLS to
118
      communicate securely with and to authenticate the clients.  The
119
      Mandos server uses IPv6 to allow Mandos clients to use IPv6
120
      link-local addresses, since the clients will probably not have
121
      any other addresses configured (see <xref linkend="overview"/>).
122
      Any authenticated client is then given the stored pre-encrypted
123
      password for that specific client.
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
124
    </para>
125
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
126
  </refsect1>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
127
  
128
  <refsect1 id="purpose">
129
    <title>PURPOSE</title>
130
131
    <para>
132
      The purpose of this is to enable <emphasis>remote and unattended
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
133
      rebooting</emphasis> of client host computer with an
134
      <emphasis>encrypted root file system</emphasis>.  See <xref
135
      linkend="overview"/> for details.
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
136
    </para>
137
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
138
  </refsect1>
24.1.55 by Björn Påhlsson
updated some partial manual pages
139
  
140
  <refsect1 id="options">
141
    <title>OPTIONS</title>
24.1.23 by Björn Påhlsson
Added manual pages for:
142
143
    <variablelist>
144
      <varlistentry>
145
	<term><literal>-h</literal>, <literal>--help</literal></term>
146
	<listitem>
147
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
148
	    Show a help message and exit
24.1.23 by Björn Påhlsson
Added manual pages for:
149
	  </para>
150
	</listitem>
151
      </varlistentry>
152
153
      <varlistentry>
154
	<term><literal>-i</literal>, <literal>--interface <replaceable>
155
	IF</replaceable></literal></term>
156
	<listitem>
157
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
158
	    Only announce the server and listen to requests on network
159
	    interface <replaceable>IF</replaceable>.  Default is to
85 by Teddy Hogeborn
* mandos.xml (SYNOPSIS): Removed unnecessary 'choice="opt"' from <arg>
160
	    use all available interfaces.  <emphasis>Note:</emphasis>
161
	    a failure to bind to the specified interface is not
162
	    considered critical, and the server does not exit.
24.1.23 by Björn Påhlsson
Added manual pages for:
163
	  </para>
164
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
165
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
166
167
      <varlistentry>
168
	<term><literal>-a</literal>, <literal>--address <replaceable>
169
	ADDRESS</replaceable></literal></term>
170
	<listitem>
171
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
172
	    If this option is used, the server will only listen to a
173
	    specific address.  This must currently be an IPv6 address;
174
	    an IPv4 address can be specified using the
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
175
	    <quote><literal>::FFFF:192.0.2.3</literal></quote> syntax.
176
	    Also, if a link-local address is specified, an interface
177
	    should be set, since a link-local address is only valid on
178
	    a single interface.  By default, the server will listen to
179
	    all available addresses.
24.1.23 by Björn Påhlsson
Added manual pages for:
180
	  </para>
181
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
182
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
183
184
      <varlistentry>
185
	<term><literal>-p</literal>, <literal>--port <replaceable>
186
	PORT</replaceable></literal></term>
187
	<listitem>
188
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
189
	    If this option is used, the server to bind to that
190
	    port. By default, the server will listen to an arbitrary
191
	    port given by the operating system.
24.1.23 by Björn Påhlsson
Added manual pages for:
192
	  </para>
193
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
194
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
195
196
      <varlistentry>
197
	<term><literal>--check</literal></term>
198
	<listitem>
199
	  <para>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
200
	    Run the server’s self-tests.  This includes any unit
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
201
	    tests, etc.
24.1.23 by Björn Påhlsson
Added manual pages for:
202
	  </para>
203
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
204
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
205
206
      <varlistentry>
207
	<term><literal>--debug</literal></term>
208
	<listitem>
209
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
210
	    If the server is run in debug mode, it will run in the
211
	    foreground and print a lot of debugging information.  The
212
	    default is <emphasis>not</emphasis> to run in debug mode.
24.1.23 by Björn Påhlsson
Added manual pages for:
213
	  </para>
214
	</listitem>
215
      </varlistentry>
216
217
      <varlistentry>
218
	<term><literal>--priority <replaceable>
219
	PRIORITY</replaceable></literal></term>
220
	<listitem>
221
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
222
	    GnuTLS priority string for the TLS handshake with the
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
223
	    clients.  The default is
224
	    <quote><literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal></quote>.
225
	    See <citerefentry><refentrytitle>gnutls_priority_init
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
226
	    </refentrytitle><manvolnum>3</manvolnum></citerefentry>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
227
	    for the syntax.  <emphasis>Warning</emphasis>: changing
228
	    this may make the TLS handshake fail, making communication
229
	    with clients impossible.
24.1.23 by Björn Påhlsson
Added manual pages for:
230
	  </para>
231
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
232
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
233
234
      <varlistentry>
235
	<term><literal>--servicename <replaceable>NAME</replaceable>
236
	</literal></term>
237
	<listitem>
238
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
239
	    Zeroconf service name.  The default is
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
240
	    <quote><literal>Mandos</literal></quote>.  You only need
241
	    to change this if you for some reason want to run more
242
	    than one server on the same <emphasis>host</emphasis>,
243
	    which would not normally be useful.  If there are name
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
244
	    collisions on the same <emphasis>network</emphasis>, the
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
245
	    newer server will automatically rename itself to
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
246
	    <quote><literal>Mandos #2</literal></quote>, and so on;
247
	    therefore, this option is not needed in that case.
24.1.23 by Björn Påhlsson
Added manual pages for:
248
	  </para>
249
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
250
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
251
252
      <varlistentry>
253
	<term><literal>--configdir <replaceable>DIR</replaceable>
254
	</literal></term>
255
	<listitem>
256
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
257
	    Directory to search for configuration files.  Default is
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
258
	    <quote><literal>/etc/mandos</literal></quote>.  See
259
	    <citerefentry><refentrytitle>mandos.conf</refentrytitle>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
260
	    <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
261
	    <refentrytitle>mandos-clients.conf</refentrytitle>
262
	    <manvolnum>5</manvolnum></citerefentry>.
24.1.23 by Björn Påhlsson
Added manual pages for:
263
	  </para>
264
	</listitem>
265
      </varlistentry>
24.1.35 by Björn Påhlsson
version 1.0
266
267
      <varlistentry>
268
	<term><literal>--version</literal></term>
269
	<listitem>
270
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
271
	    Prints the program version and exit.
24.1.35 by Björn Påhlsson
version 1.0
272
	  </para>
273
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
274
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
275
    </variablelist>
276
  </refsect1>
24.1.55 by Björn Påhlsson
updated some partial manual pages
277
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
278
  <refsect1 id="overview">
279
    <title>OVERVIEW</title>
280
    &OVERVIEW;
281
    <para>
282
      This program is the server part.  It is a normal server program
283
      and will run in a normal system environment, not in an initial
284
      RAM disk environment.
285
    </para>
286
  </refsect1>
287
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
288
  <refsect1 id="protocol">
289
    <title>NETWORK PROTOCOL</title>
290
    <para>
291
      The Mandos server announces itself as a Zeroconf service of type
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
292
      <quote><literal>_mandos._tcp</literal></quote>.  The Mandos
293
      client connects to the announced address and port, and sends a
294
      line of text where the first whitespace-separated field is the
295
      protocol version, which currently is
296
      <quote><literal>1</literal></quote>.  The client and server then
297
      start a TLS protocol handshake with a slight quirk: the Mandos
298
      server program acts as a TLS <quote>client</quote> while the
299
      connecting Mandos client acts as a TLS <quote>server</quote>.
300
      The Mandos client must supply an OpenPGP certificate, and the
301
      fingerprint of this certificate is used by the Mandos server to
302
      look up (in a list read from <filename>clients.conf</filename>
303
      at start time) which binary blob to give the client.  No other
304
      authentication or authorization is done by the server.
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
305
    </para>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
306
    <table>
307
      <title>Mandos Protocol (Version 1)</title><tgroup cols="3"><thead>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
308
      <row>
309
	<entry>Mandos Client</entry>
310
	<entry>Direction</entry>
311
	<entry>Mandos Server</entry>
312
      </row>
313
      </thead><tbody>
314
      <row>
315
	<entry>Connect</entry>
316
	<entry>-><!-- &rarr; --></entry>
317
      </row>
318
      <row>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
319
	<entry><quote><literal>1\r\en</literal></quote></entry>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
320
	<entry>-><!-- &rarr; --></entry>
321
      </row>
322
      <row>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
323
	<entry>TLS handshake <emphasis>as TLS <quote>server</quote>
324
	</emphasis></entry>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
325
	<entry>&lt;-><!-- &xharr; --></entry>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
326
	<entry>TLS handshake <emphasis>as TLS <quote>client</quote>
327
	</emphasis></entry>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
328
      </row>
329
      <row>
330
	<entry>OpenPGP public key (part of TLS handshake)</entry>
331
	<entry>-><!-- &rarr; --></entry>
332
      </row>
333
      <row>
334
	<entry/>
335
	<entry>&lt;-<!-- &larr; --></entry>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
336
	<entry>Binary blob (client will assume OpenPGP data)</entry>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
337
      </row>
338
      <row>
339
	<entry/>
340
	<entry>&lt;-<!-- &larr; --></entry>
341
	<entry>Close</entry>
342
      </row>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
343
    </tbody></tgroup></table>
344
  </refsect1>
345
346
  <refsect1 id="checking">
347
    <title>CHECKING</title>
348
    <para>
349
      The server will, by default, continually check that the clients
350
      are still up.  If a client has not been confirmed as being up
351
      for some time, the client is assumed to be compromised and is no
352
      longer eligible to receive the encrypted password.  The timeout,
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
353
      checker program, and interval between checks can be configured
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
354
      both globally and per client; see <citerefentry>
355
      <refentrytitle>mandos.conf</refentrytitle>
356
      <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
357
      <refentrytitle>mandos-clients.conf</refentrytitle>
358
      <manvolnum>5</manvolnum></citerefentry>.
359
    </para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
360
  </refsect1>
361
362
  <refsect1 id="logging">
363
    <title>LOGGING</title>
364
    <para>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
365
      The server will send log messaged with various severity levels
366
      to <filename>/dev/log</filename>.  With the
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
367
      <option>--debug</option> option, it will log even more messages,
368
      and also show them on the console.
369
    </para>
370
  </refsect1>
371
24.1.55 by Björn Påhlsson
updated some partial manual pages
372
  <refsect1 id="exit_status">
373
    <title>EXIT STATUS</title>
374
    <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
375
      The server will exit with a non-zero exit status only when a
376
      critical error is encountered.
24.1.55 by Björn Påhlsson
updated some partial manual pages
377
    </para>
378
  </refsect1>
379
85 by Teddy Hogeborn
* mandos.xml (SYNOPSIS): Removed unnecessary 'choice="opt"' from <arg>
380
  <refsect1 id="environment">
381
    <title>ENVIRONMENT</title>
382
    <variablelist>
383
      <varlistentry>
384
	<term><varname>PATH</varname></term>
385
	<listitem>
386
	  <para>
387
	    To start the configured checker (see <xref
388
	    linkend="checking"/>), the server uses
389
	    <filename>/bin/sh</filename>, which in turn uses
390
	    <varname>PATH</varname> to search for matching commands if
391
	    an absolute path is not given.  See <citerefentry>
392
	    <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
393
	  </citerefentry>
394
	  </para>
395
	</listitem>
396
      </varlistentry>
397
    </variablelist>
398
  </refsect1>
399
24.1.55 by Björn Påhlsson
updated some partial manual pages
400
  <refsect1 id="file">
401
    <title>FILES</title>
402
    <para>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
403
      Use the <option>--configdir</option> option to change where
404
      <command>&COMMANDNAME;</command> looks for its configurations
405
      files.  The default file names are listed here.
24.1.55 by Björn Påhlsson
updated some partial manual pages
406
    </para>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
407
    <variablelist>
408
      <varlistentry>
409
	<term><filename>/etc/mandos/mandos.conf</filename></term>
410
	<listitem>
411
	  <para>
412
	    Server-global settings.  See
413
	    <citerefentry><refentrytitle>mandos.conf</refentrytitle>
414
	    <manvolnum>5</manvolnum></citerefentry> for details.
415
	  </para>
416
	</listitem>
417
      </varlistentry>
418
      <varlistentry>
419
	<term><filename>/etc/mandos/clients.conf</filename></term>
420
	<listitem>
421
	  <para>
422
	    List of clients and client-specific settings.  See
423
	    <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
424
	    <manvolnum>5</manvolnum></citerefentry> for details.
425
	  </para>
426
	</listitem>
427
      </varlistentry>
428
      <varlistentry>
429
	<term><filename>/var/run/mandos/mandos.pid</filename></term>
430
	<listitem>
431
	  <para>
432
	    The file containing the process id of
433
	    <command>&COMMANDNAME;</command>.
434
	  </para>
435
	</listitem>
436
      </varlistentry>
437
      <varlistentry>
438
	<term><filename>/dev/log</filename></term>
439
	<listitem>
440
	  <para>
441
	    The Unix domain socket to where local syslog messages are
442
	    sent.
443
	  </para>
444
	</listitem>
445
      </varlistentry>
85 by Teddy Hogeborn
* mandos.xml (SYNOPSIS): Removed unnecessary 'choice="opt"' from <arg>
446
      <varlistentry>
447
	<term><filename>/bin/sh</filename></term>
448
	<listitem>
449
	  <para>
450
	    This is used to start the configured checker command for
451
	    each client.  See <citerefentry>
452
	    <refentrytitle>mandos-clients.conf</refentrytitle>
453
	    <manvolnum>5</manvolnum></citerefentry> for details.
454
	  </para>
455
	</listitem>
456
      </varlistentry>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
457
    </variablelist>
458
  </refsect1>
85 by Teddy Hogeborn
* mandos.xml (SYNOPSIS): Removed unnecessary 'choice="opt"' from <arg>
459
  
24.1.55 by Björn Påhlsson
updated some partial manual pages
460
  <refsect1 id="bugs">
461
    <title>BUGS</title>
462
    <para>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
463
      This server might, on especially fatal errors, emit a Python
464
      backtrace.  This could be considered a feature.
24.1.55 by Björn Påhlsson
updated some partial manual pages
465
    </para>
85 by Teddy Hogeborn
* mandos.xml (SYNOPSIS): Removed unnecessary 'choice="opt"' from <arg>
466
    <para>
467
      Currently, if a client is declared <quote>invalid</quote> due to
468
      having timed out, the server does not record this fact onto
469
      permanent storage.  This has some security implications, see
470
      <xref linkend="CLIENTS"/>.
471
    </para>
472
    <para>
473
      There is currently no way of querying the server of the current
474
      status of clients, other than analyzing its <systemitem
475
      class="service">syslog</systemitem> output.
476
    </para>
477
    <para>
478
      There is no fine-grained control over logging and debug output.
479
    </para>
480
    <para>
481
      Debug mode is conflated with running in the foreground.
482
    </para>
483
    <para>
484
      The console log messages does not show a timestamp.
485
    </para>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
486
  </refsect1>
85 by Teddy Hogeborn
* mandos.xml (SYNOPSIS): Removed unnecessary 'choice="opt"' from <arg>
487
  
488
  <refsect1 id="example">
489
    <title>EXAMPLE</title>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
490
    <informalexample>
491
      <para>
492
	Normal invocation needs no options:
493
      </para>
494
      <para>
495
	<userinput>mandos</userinput>
496
      </para>
497
    </informalexample>
498
    <informalexample>
499
      <para>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
500
	Run the server in debug mode, read configuration files from
501
	the <filename>~/mandos</filename> directory, and use the
502
	Zeroconf service name <quote>Test</quote> to not collide with
503
	any other official Mandos server on this host:
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
504
      </para>
505
      <para>
506
507
<!-- do not wrap this line -->
508
<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>
509
510
      </para>
511
    </informalexample>
512
    <informalexample>
513
      <para>
514
	Run the server normally, but only listen to one interface and
515
	only on the link-local address on that interface:
516
      </para>
517
      <para>
518
519
<!-- do not wrap this line -->
520
<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
521
522
      </para>
523
    </informalexample>
24.1.55 by Björn Påhlsson
updated some partial manual pages
524
  </refsect1>
525
526
  <refsect1 id="security">
527
    <title>SECURITY</title>
85 by Teddy Hogeborn
* mandos.xml (SYNOPSIS): Removed unnecessary 'choice="opt"' from <arg>
528
    <refsect2 id="SERVER">
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
529
      <title>SERVER</title>
530
      <para>
85 by Teddy Hogeborn
* mandos.xml (SYNOPSIS): Removed unnecessary 'choice="opt"' from <arg>
531
	Running this <command>&COMMANDNAME;</command> server program
532
	should not in itself present any security risk to the host
533
	computer running it.  The program does not need any special
534
	privileges to run, and is designed to run as a non-root user.
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
535
      </para>
536
    </refsect2>
85 by Teddy Hogeborn
* mandos.xml (SYNOPSIS): Removed unnecessary 'choice="opt"' from <arg>
537
    <refsect2 id="CLIENTS">
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
538
      <title>CLIENTS</title>
539
      <para>
540
	The server only gives out its stored data to clients which
541
	does have the OpenPGP key of the stored fingerprint.  This is
542
	guaranteed by the fact that the client sends its OpenPGP
543
	public key in the TLS handshake; this ensures it to be
544
	genuine.  The server computes the fingerprint of the key
545
	itself and looks up the fingerprint in its list of
546
	clients. The <filename>clients.conf</filename> file (see
547
	<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
548
	<manvolnum>5</manvolnum></citerefentry>)
549
	<emphasis>must</emphasis> be made non-readable by anyone
550
	except the user running the server.
551
      </para>
552
      <para>
553
	As detailed in <xref linkend="checking"/>, the status of all
554
	client computers will continually be checked and be assumed
555
	compromised if they are gone for too long.
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
556
      </para>
557
      <para>
85 by Teddy Hogeborn
* mandos.xml (SYNOPSIS): Removed unnecessary 'choice="opt"' from <arg>
558
	If a client is compromised, its downtime should be duly noted
559
	by the server which would therefore declare the client
560
	invalid.  But if the server was ever restarted, it would
561
	re-read its client list from its configuration file and again
562
	regard all clients therein as valid, and hence eligible to
563
	receive their passwords.  Therefore, be careful when
564
	restarting servers if you suspect that a client has, in fact,
565
	been compromised by parties who may now be running a fake
566
	Mandos client with the keys from the non-encrypted initial RAM
567
	image of the client host.  What should be done in that case
568
	(if restarting the server program really is necessary) is to
569
	stop the server program, edit the configuration file to omit
570
	any suspect clients, and restart the server program.
571
      </para>
572
      <para>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
573
	For more details on client-side security, see
574
	<citerefentry><refentrytitle>password-request</refentrytitle>
575
	<manvolnum>8mandos</manvolnum></citerefentry>.
576
      </para>
577
    </refsect2>
24.1.55 by Björn Påhlsson
updated some partial manual pages
578
  </refsect1>
579
580
  <refsect1 id="see_also">
581
    <title>SEE ALSO</title>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
582
    <variablelist>
583
      <varlistentry>
584
	<term>
585
	  <citerefentry>
586
	    <refentrytitle>password-request</refentrytitle>
587
	    <manvolnum>8mandos</manvolnum>
588
	  </citerefentry>
589
	</term>
590
	<listitem>
591
	  <para>
592
	    This is the actual program which talks to this server.
593
	    Note that it is normally not invoked directly, and is only
594
	    run in the initial RAM disk environment, and not on a
595
	    fully started system.
596
	  </para>
597
	</listitem>
598
      </varlistentry>
599
      <varlistentry>
600
	<term>
601
	  <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
602
	</term>
603
	<listitem>
604
	  <para>
605
	    Zeroconf is the network protocol standard used by clients
606
	    for finding this Mandos server on the local network.
607
	  </para>
608
	</listitem>
609
      </varlistentry>
610
      <varlistentry>
611
	<term>
612
	  <ulink url="http://www.avahi.org/">Avahi</ulink>
613
	</term>
614
      <listitem>
615
	<para>
616
	  Avahi is the library this server calls to implement
617
	  Zeroconf service announcements.
618
	</para>
619
      </listitem>
620
      </varlistentry>
621
      <varlistentry>
622
	<term>
623
	  <ulink
624
	      url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
625
	</term>
626
      <listitem>
627
	<para>
628
	  GnuTLS is the library this server uses to implement TLS for
629
	  communicating securely with the client, and at the same time
630
	  confidently get the client’s public OpenPGP key.
631
	</para>
632
      </listitem>
633
      </varlistentry>
634
      <varlistentry>
635
	<term>
636
	  <citation>RFC 4291: <citetitle>IP Version 6 Addressing
637
	  Architecture</citetitle>, section 2.5.6, Link-Local IPv6
638
	  Unicast Addresses</citation>
639
	</term>
640
	<listitem>
641
	  <para>
642
	    The clients use IPv6 link-local addresses, which are
643
	    immediately usable since a link-local addresses is
644
	    automatically assigned to a network interfaces when it is
645
	    brought up.
646
	  </para>
647
	</listitem>
648
      </varlistentry>
649
      <varlistentry>
650
	<term>
651
	  <citation>RFC 4346: <citetitle>The Transport Layer Security
652
	  (TLS) Protocol Version 1.1</citetitle></citation>
653
	</term>
654
      <listitem>
655
	<para>
656
	  TLS 1.1 is the protocol implemented by GnuTLS.
657
	</para>
658
      </listitem>
659
      </varlistentry>
660
      <varlistentry>
661
	<term>
662
	  <citation>RFC 4880: <citetitle>OpenPGP Message
663
	  Format</citetitle></citation>
664
	</term>
665
      <listitem>
666
	<para>
667
	  The data sent to clients is binary encrypted OpenPGP data.
668
	</para>
669
      </listitem>
670
      </varlistentry>
671
      <varlistentry>
672
	<term>
673
	  <citation>RFC 5081: <citetitle>Using OpenPGP Keys for
674
	  Transport Layer Security</citetitle></citation>
675
	</term>
676
      <listitem>
677
	<para>
678
	  This is implemented by GnuTLS and used by this server so
679
	  that OpenPGP keys can be used.
680
	</para>
681
      </listitem>
682
      </varlistentry>
683
    </variablelist>
24.1.55 by Björn Påhlsson
updated some partial manual pages
684
  </refsect1>
24.1.23 by Björn Påhlsson
Added manual pages for:
685
</refentry>