/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>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
76
      <arg choice="opt">--interface<arg choice="plain">IF</arg></arg>
77
      <arg choice="opt">--address<arg choice="plain">ADDRESS</arg></arg>
78
      <arg choice="opt">--port<arg choice="plain">PORT</arg></arg>
79
      <arg choice="opt">--priority<arg choice="plain">PRIORITY</arg></arg>
80
      <arg choice="opt">--servicename<arg choice="plain">NAME</arg></arg>
81
      <arg choice="opt">--configdir<arg choice="plain">DIRECTORY</arg></arg>
82
      <arg choice="opt">--debug</arg>
83
    </cmdsynopsis>
84
    <cmdsynopsis>
85
      <command>&COMMANDNAME;</command>
86
      <arg choice="opt">-i<arg choice="plain">IF</arg></arg>
87
      <arg choice="opt">-a<arg choice="plain">ADDRESS</arg></arg>
88
      <arg choice="opt">-p<arg choice="plain">PORT</arg></arg>
89
      <arg choice="opt">--priority<arg choice="plain">PRIORITY</arg></arg>
90
      <arg choice="opt">--servicename<arg choice="plain">NAME</arg></arg>
91
      <arg choice="opt">--configdir<arg choice="plain">DIRECTORY</arg></arg>
92
      <arg choice="opt">--debug</arg>
93
    </cmdsynopsis>
94
    <cmdsynopsis>
95
      <command>&COMMANDNAME;</command>
96
      <arg choice="plain">--help</arg>
97
    </cmdsynopsis>
98
    <cmdsynopsis>
99
      <command>&COMMANDNAME;</command>
100
      <arg choice="plain">--version</arg>
101
    </cmdsynopsis>
102
    <cmdsynopsis>
103
      <command>&COMMANDNAME;</command>
104
      <arg choice="plain">--check</arg>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
105
    </cmdsynopsis>
24.1.23 by Björn Påhlsson
Added manual pages for:
106
  </refsynopsisdiv>
107
108
  <refsect1 id="description">
109
    <title>DESCRIPTION</title>
110
    <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
111
      <command>&COMMANDNAME;</command> is a server daemon which
112
      handles incoming request for passwords for a pre-defined list of
113
      client host computers.  The Mandos server uses Zeroconf to
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
114
      announce itself on the local network, and uses TLS to
115
      communicate securely with and to authenticate the clients.  The
116
      Mandos server uses IPv6 to allow Mandos clients to use IPv6
117
      link-local addresses, since the clients will probably not have
118
      any other addresses configured (see <xref linkend="overview"/>).
119
      Any authenticated client is then given the stored pre-encrypted
120
      password for that specific client.
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
121
    </para>
122
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
123
  </refsect1>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
124
  
125
  <refsect1 id="purpose">
126
    <title>PURPOSE</title>
127
128
    <para>
129
      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
130
      rebooting</emphasis> of client host computer with an
131
      <emphasis>encrypted root file system</emphasis>.  See <xref
132
      linkend="overview"/> for details.
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
133
    </para>
134
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
135
  </refsect1>
24.1.55 by Björn Påhlsson
updated some partial manual pages
136
  
137
  <refsect1 id="options">
138
    <title>OPTIONS</title>
24.1.23 by Björn Påhlsson
Added manual pages for:
139
140
    <variablelist>
141
      <varlistentry>
142
	<term><literal>-h</literal>, <literal>--help</literal></term>
143
	<listitem>
144
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
145
	    Show a help message and exit
24.1.23 by Björn Påhlsson
Added manual pages for:
146
	  </para>
147
	</listitem>
148
      </varlistentry>
149
150
      <varlistentry>
151
	<term><literal>-i</literal>, <literal>--interface <replaceable>
152
	IF</replaceable></literal></term>
153
	<listitem>
154
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
155
	    Only announce the server and listen to requests on network
156
	    interface <replaceable>IF</replaceable>.  Default is to
157
	    use all available interfaces.
24.1.23 by Björn Påhlsson
Added manual pages for:
158
	  </para>
159
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
160
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
161
162
      <varlistentry>
163
	<term><literal>-a</literal>, <literal>--address <replaceable>
164
	ADDRESS</replaceable></literal></term>
165
	<listitem>
166
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
167
	    If this option is used, the server will only listen to a
168
	    specific address.  This must currently be an IPv6 address;
169
	    an IPv4 address can be specified using the
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
170
	    <quote><literal>::FFFF:192.0.2.3</literal></quote> syntax.
171
	    Also, if a link-local address is specified, an interface
172
	    should be set, since a link-local address is only valid on
173
	    a single interface.  By default, the server will listen to
174
	    all available addresses.
24.1.23 by Björn Påhlsson
Added manual pages for:
175
	  </para>
176
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
177
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
178
179
      <varlistentry>
180
	<term><literal>-p</literal>, <literal>--port <replaceable>
181
	PORT</replaceable></literal></term>
182
	<listitem>
183
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
184
	    If this option is used, the server to bind to that
185
	    port. By default, the server will listen to an arbitrary
186
	    port given by the operating system.
24.1.23 by Björn Påhlsson
Added manual pages for:
187
	  </para>
188
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
189
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
190
191
      <varlistentry>
192
	<term><literal>--check</literal></term>
193
	<listitem>
194
	  <para>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
195
	    Run the server’s self-tests.  This includes any unit
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
196
	    tests, etc.
24.1.23 by Björn Påhlsson
Added manual pages for:
197
	  </para>
198
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
199
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
200
201
      <varlistentry>
202
	<term><literal>--debug</literal></term>
203
	<listitem>
204
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
205
	    If the server is run in debug mode, it will run in the
206
	    foreground and print a lot of debugging information.  The
207
	    default is <emphasis>not</emphasis> to run in debug mode.
24.1.23 by Björn Påhlsson
Added manual pages for:
208
	  </para>
209
	</listitem>
210
      </varlistentry>
211
212
      <varlistentry>
213
	<term><literal>--priority <replaceable>
214
	PRIORITY</replaceable></literal></term>
215
	<listitem>
216
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
217
	    GnuTLS priority string for the TLS handshake with the
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
218
	    clients.  The default is
219
	    <quote><literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal></quote>.
220
	    See <citerefentry><refentrytitle>gnutls_priority_init
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
221
	    </refentrytitle><manvolnum>3</manvolnum></citerefentry>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
222
	    for the syntax.  <emphasis>Warning</emphasis>: changing
223
	    this may make the TLS handshake fail, making communication
224
	    with clients impossible.
24.1.23 by Björn Påhlsson
Added manual pages for:
225
	  </para>
226
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
227
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
228
229
      <varlistentry>
230
	<term><literal>--servicename <replaceable>NAME</replaceable>
231
	</literal></term>
232
	<listitem>
233
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
234
	    Zeroconf service name.  The default is
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
235
	    <quote><literal>Mandos</literal></quote>.  You only need
236
	    to change this if you for some reason want to run more
237
	    than one server on the same <emphasis>host</emphasis>,
238
	    which would not normally be useful.  If there are name
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
239
	    collisions on the same <emphasis>network</emphasis>, the
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
240
	    newer server will automatically rename itself to
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
241
	    <quote><literal>Mandos #2</literal></quote>, and so on;
242
	    therefore, this option is not needed in that case.
24.1.23 by Björn Påhlsson
Added manual pages for:
243
	  </para>
244
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
245
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
246
247
      <varlistentry>
248
	<term><literal>--configdir <replaceable>DIR</replaceable>
249
	</literal></term>
250
	<listitem>
251
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
252
	    Directory to search for configuration files.  Default is
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
253
	    <quote><literal>/etc/mandos</literal></quote>.  See
254
	    <citerefentry><refentrytitle>mandos.conf</refentrytitle>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
255
	    <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
256
	    <refentrytitle>mandos-clients.conf</refentrytitle>
257
	    <manvolnum>5</manvolnum></citerefentry>.
24.1.23 by Björn Påhlsson
Added manual pages for:
258
	  </para>
259
	</listitem>
260
      </varlistentry>
24.1.35 by Björn Påhlsson
version 1.0
261
262
      <varlistentry>
263
	<term><literal>--version</literal></term>
264
	<listitem>
265
	  <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
266
	    Prints the program version and exit.
24.1.35 by Björn Påhlsson
version 1.0
267
	  </para>
268
	</listitem>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
269
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
270
    </variablelist>
271
  </refsect1>
24.1.55 by Björn Påhlsson
updated some partial manual pages
272
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
273
  <refsect1 id="overview">
274
    <title>OVERVIEW</title>
275
    &OVERVIEW;
276
    <para>
277
      This program is the server part.  It is a normal server program
278
      and will run in a normal system environment, not in an initial
279
      RAM disk environment.
280
    </para>
281
  </refsect1>
282
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
283
  <refsect1 id="protocol">
284
    <title>NETWORK PROTOCOL</title>
285
    <para>
286
      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".
287
      <quote><literal>_mandos._tcp</literal></quote>.  The Mandos
288
      client connects to the announced address and port, and sends a
289
      line of text where the first whitespace-separated field is the
290
      protocol version, which currently is
291
      <quote><literal>1</literal></quote>.  The client and server then
292
      start a TLS protocol handshake with a slight quirk: the Mandos
293
      server program acts as a TLS <quote>client</quote> while the
294
      connecting Mandos client acts as a TLS <quote>server</quote>.
295
      The Mandos client must supply an OpenPGP certificate, and the
296
      fingerprint of this certificate is used by the Mandos server to
297
      look up (in a list read from <filename>clients.conf</filename>
298
      at start time) which binary blob to give the client.  No other
299
      authentication or authorization is done by the server.
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
300
    </para>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
301
    <table>
302
      <title>Mandos Protocol (Version 1)</title><tgroup cols="3"><thead>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
303
      <row>
304
	<entry>Mandos Client</entry>
305
	<entry>Direction</entry>
306
	<entry>Mandos Server</entry>
307
      </row>
308
      </thead><tbody>
309
      <row>
310
	<entry>Connect</entry>
311
	<entry>-><!-- &rarr; --></entry>
312
      </row>
313
      <row>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
314
	<entry><quote><literal>1\r\en</literal></quote></entry>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
315
	<entry>-><!-- &rarr; --></entry>
316
      </row>
317
      <row>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
318
	<entry>TLS handshake <emphasis>as TLS <quote>server</quote>
319
	</emphasis></entry>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
320
	<entry>&lt;-><!-- &xharr; --></entry>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
321
	<entry>TLS handshake <emphasis>as TLS <quote>client</quote>
322
	</emphasis></entry>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
323
      </row>
324
      <row>
325
	<entry>OpenPGP public key (part of TLS handshake)</entry>
326
	<entry>-><!-- &rarr; --></entry>
327
      </row>
328
      <row>
329
	<entry/>
330
	<entry>&lt;-<!-- &larr; --></entry>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
331
	<entry>Binary blob (client will assume OpenPGP data)</entry>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
332
      </row>
333
      <row>
334
	<entry/>
335
	<entry>&lt;-<!-- &larr; --></entry>
336
	<entry>Close</entry>
337
      </row>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
338
    </tbody></tgroup></table>
339
  </refsect1>
340
341
  <refsect1 id="checking">
342
    <title>CHECKING</title>
343
    <para>
344
      The server will, by default, continually check that the clients
345
      are still up.  If a client has not been confirmed as being up
346
      for some time, the client is assumed to be compromised and is no
347
      longer eligible to receive the encrypted password.  The timeout,
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
348
      checker program, and interval between checks can be configured
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
349
      both globally and per client; see <citerefentry>
350
      <refentrytitle>mandos.conf</refentrytitle>
351
      <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
352
      <refentrytitle>mandos-clients.conf</refentrytitle>
353
      <manvolnum>5</manvolnum></citerefentry>.
354
    </para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
355
  </refsect1>
356
357
  <refsect1 id="logging">
358
    <title>LOGGING</title>
359
    <para>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
360
      The server will send log messaged with various severity levels
361
      to <filename>/dev/log</filename>.  With the
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
362
      <option>--debug</option> option, it will log even more messages,
363
      and also show them on the console.
364
    </para>
365
  </refsect1>
366
24.1.55 by Björn Påhlsson
updated some partial manual pages
367
  <refsect1 id="exit_status">
368
    <title>EXIT STATUS</title>
369
    <para>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
370
      The server will exit with a non-zero exit status only when a
371
      critical error is encountered.
24.1.55 by Björn Påhlsson
updated some partial manual pages
372
    </para>
373
  </refsect1>
374
375
  <refsect1 id="file">
376
    <title>FILES</title>
377
    <para>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
378
      Use the <option>--configdir</option> option to change where
379
      <command>&COMMANDNAME;</command> looks for its configurations
380
      files.  The default file names are listed here.
24.1.55 by Björn Påhlsson
updated some partial manual pages
381
    </para>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
382
    <variablelist>
383
      <varlistentry>
384
	<term><filename>/etc/mandos/mandos.conf</filename></term>
385
	<listitem>
386
	  <para>
387
	    Server-global settings.  See
388
	    <citerefentry><refentrytitle>mandos.conf</refentrytitle>
389
	    <manvolnum>5</manvolnum></citerefentry> for details.
390
	  </para>
391
	</listitem>
392
      </varlistentry>
393
      <varlistentry>
394
	<term><filename>/etc/mandos/clients.conf</filename></term>
395
	<listitem>
396
	  <para>
397
	    List of clients and client-specific settings.  See
398
	    <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
399
	    <manvolnum>5</manvolnum></citerefentry> for details.
400
	  </para>
401
	</listitem>
402
      </varlistentry>
403
      <varlistentry>
404
	<term><filename>/var/run/mandos/mandos.pid</filename></term>
405
	<listitem>
406
	  <para>
407
	    The file containing the process id of
408
	    <command>&COMMANDNAME;</command>.
409
	  </para>
410
	</listitem>
411
      </varlistentry>
412
      <varlistentry>
413
	<term><filename>/dev/log</filename></term>
414
	<listitem>
415
	  <para>
416
	    The Unix domain socket to where local syslog messages are
417
	    sent.
418
	  </para>
419
	</listitem>
420
      </varlistentry>
421
    </variablelist>
422
  </refsect1>
24.1.55 by Björn Påhlsson
updated some partial manual pages
423
424
  <refsect1 id="bugs">
425
    <title>BUGS</title>
426
    <para>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
427
      This server might, on especially fatal errors, emit a Python
428
      backtrace.  This could be considered a feature.
24.1.55 by Björn Påhlsson
updated some partial manual pages
429
    </para>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
430
  </refsect1>
24.1.55 by Björn Påhlsson
updated some partial manual pages
431
432
  <refsect1 id="examples">
433
    <title>EXAMPLES</title>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
434
    <informalexample>
435
      <para>
436
	Normal invocation needs no options:
437
      </para>
438
      <para>
439
	<userinput>mandos</userinput>
440
      </para>
441
    </informalexample>
442
    <informalexample>
443
      <para>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
444
	Run the server in debug mode, read configuration files from
445
	the <filename>~/mandos</filename> directory, and use the
446
	Zeroconf service name <quote>Test</quote> to not collide with
447
	any other official Mandos server on this host:
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
448
      </para>
449
      <para>
450
451
<!-- do not wrap this line -->
452
<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>
453
454
      </para>
455
    </informalexample>
456
    <informalexample>
457
      <para>
458
	Run the server normally, but only listen to one interface and
459
	only on the link-local address on that interface:
460
      </para>
461
      <para>
462
463
<!-- do not wrap this line -->
464
<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
465
466
      </para>
467
    </informalexample>
24.1.55 by Björn Påhlsson
updated some partial manual pages
468
  </refsect1>
469
470
  <refsect1 id="security">
471
    <title>SECURITY</title>
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
472
    <refsect2>
473
      <title>SERVER</title>
474
      <para>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
475
	Running this &COMMANDNAME; server program should not in itself
476
	present any security risk to the host computer running it.
477
	The program does not need any special privileges to run, and
478
	is designed to run as a non-root user.
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
479
      </para>
480
    </refsect2>
481
    <refsect2>
482
      <title>CLIENTS</title>
483
      <para>
484
	The server only gives out its stored data to clients which
485
	does have the OpenPGP key of the stored fingerprint.  This is
486
	guaranteed by the fact that the client sends its OpenPGP
487
	public key in the TLS handshake; this ensures it to be
488
	genuine.  The server computes the fingerprint of the key
489
	itself and looks up the fingerprint in its list of
490
	clients. The <filename>clients.conf</filename> file (see
491
	<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
492
	<manvolnum>5</manvolnum></citerefentry>)
493
	<emphasis>must</emphasis> be made non-readable by anyone
494
	except the user running the server.
495
      </para>
496
      <para>
497
	As detailed in <xref linkend="checking"/>, the status of all
498
	client computers will continually be checked and be assumed
499
	compromised if they are gone for too long.
83 by Teddy Hogeborn
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".
500
      </para>
501
      <para>
502
	For more details on client-side security, see
503
	<citerefentry><refentrytitle>password-request</refentrytitle>
504
	<manvolnum>8mandos</manvolnum></citerefentry>.
505
      </para>
506
    </refsect2>
24.1.55 by Björn Påhlsson
updated some partial manual pages
507
  </refsect1>
508
509
  <refsect1 id="see_also">
510
    <title>SEE ALSO</title>
84 by Teddy Hogeborn
* Makefile (DOCBOOKTOMAN): Use the local manpages/docbook.xsl file, do
511
    <variablelist>
512
      <varlistentry>
513
	<term>
514
	  <citerefentry>
515
	    <refentrytitle>password-request</refentrytitle>
516
	    <manvolnum>8mandos</manvolnum>
517
	  </citerefentry>
518
	</term>
519
	<listitem>
520
	  <para>
521
	    This is the actual program which talks to this server.
522
	    Note that it is normally not invoked directly, and is only
523
	    run in the initial RAM disk environment, and not on a
524
	    fully started system.
525
	  </para>
526
	</listitem>
527
      </varlistentry>
528
      <varlistentry>
529
	<term>
530
	  <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
531
	</term>
532
	<listitem>
533
	  <para>
534
	    Zeroconf is the network protocol standard used by clients
535
	    for finding this Mandos server on the local network.
536
	  </para>
537
	</listitem>
538
      </varlistentry>
539
      <varlistentry>
540
	<term>
541
	  <ulink url="http://www.avahi.org/">Avahi</ulink>
542
	</term>
543
      <listitem>
544
	<para>
545
	  Avahi is the library this server calls to implement
546
	  Zeroconf service announcements.
547
	</para>
548
      </listitem>
549
      </varlistentry>
550
      <varlistentry>
551
	<term>
552
	  <ulink
553
	      url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
554
	</term>
555
      <listitem>
556
	<para>
557
	  GnuTLS is the library this server uses to implement TLS for
558
	  communicating securely with the client, and at the same time
559
	  confidently get the client’s public OpenPGP key.
560
	</para>
561
      </listitem>
562
      </varlistentry>
563
      <varlistentry>
564
	<term>
565
	  <citation>RFC 4291: <citetitle>IP Version 6 Addressing
566
	  Architecture</citetitle>, section 2.5.6, Link-Local IPv6
567
	  Unicast Addresses</citation>
568
	</term>
569
	<listitem>
570
	  <para>
571
	    The clients use IPv6 link-local addresses, which are
572
	    immediately usable since a link-local addresses is
573
	    automatically assigned to a network interfaces when it is
574
	    brought up.
575
	  </para>
576
	</listitem>
577
      </varlistentry>
578
      <varlistentry>
579
	<term>
580
	  <citation>RFC 4346: <citetitle>The Transport Layer Security
581
	  (TLS) Protocol Version 1.1</citetitle></citation>
582
	</term>
583
      <listitem>
584
	<para>
585
	  TLS 1.1 is the protocol implemented by GnuTLS.
586
	</para>
587
      </listitem>
588
      </varlistentry>
589
      <varlistentry>
590
	<term>
591
	  <citation>RFC 4880: <citetitle>OpenPGP Message
592
	  Format</citetitle></citation>
593
	</term>
594
      <listitem>
595
	<para>
596
	  The data sent to clients is binary encrypted OpenPGP data.
597
	</para>
598
      </listitem>
599
      </varlistentry>
600
      <varlistentry>
601
	<term>
602
	  <citation>RFC 5081: <citetitle>Using OpenPGP Keys for
603
	  Transport Layer Security</citetitle></citation>
604
	</term>
605
      <listitem>
606
	<para>
607
	  This is implemented by GnuTLS and used by this server so
608
	  that OpenPGP keys can be used.
609
	</para>
610
      </listitem>
611
      </varlistentry>
612
    </variablelist>
24.1.55 by Björn Påhlsson
updated some partial manual pages
613
  </refsect1>
24.1.23 by Björn Påhlsson
Added manual pages for:
614
</refentry>