/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk

« back to all changes in this revision

Viewing changes to mandos.xml

  • Committer: Teddy Hogeborn
  • Date: 2008-08-17 06:01:58 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080817060158-o5xakkih6t3br9yq
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
            GPGME_CFLAGS, GPGME_LIBS): New; use libgnutls-config,
                                       pkg-config, and gpgme-config to
                                       get the correct compiler and
                                       linker flags.
  (MANPOST): New post-processing stage to man pages to fix a bug with
             having "\n" in the DocBook pages.
  (objects): Use $(addsuffix) instead of a for loop in a subshell.
  (plugin-runner, plugins.d/password-prompt): Removed; targets no
                                              longer necessary.
  (.PHONY): Added "doc".

* mandos.xml: Much improved.

* plugins.d/password-request.xml: Improved SEE ALSO section.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos.xml
103
103
    <cmdsynopsis>
104
104
      <command>&COMMANDNAME;</command>
105
105
      <arg choice='plain'>--check</arg>
106
 
    </cmdsynopsis>
 
106
    </cmdsynopsis>    
107
107
  </refsynopsisdiv>
108
108
 
109
109
  <refsect1 id="description">
115
115
      announce itself on the local network, and uses GnuTLS to
116
116
      communicate securely with and to authenticate the clients.
117
117
      Mandos uses IPv6 link-local addresses, since the clients are
118
 
      assumed to not have any other addresses configured.  Any
 
118
      assumed to not have any other addresses configured yet.  Any
119
119
      authenticated client is then given the pre-encrypted password
120
120
      for that specific client.
121
121
    </para>
122
122
 
123
 
  </refsect1>
 
123
  </refsect1>  
124
124
  
125
125
  <refsect1 id="purpose">
126
126
    <title>PURPOSE</title>
137
137
      normally.
138
138
    </para>
139
139
 
140
 
  </refsect1>
 
140
  </refsect1>  
141
141
  
142
142
  <refsect1 id="options">
143
143
    <title>OPTIONS</title>
162
162
            use all available interfaces.
163
163
          </para>
164
164
        </listitem>
165
 
      </varlistentry>
 
165
      </varlistentry>      
166
166
 
167
167
      <varlistentry>
168
168
        <term><literal>-a</literal>, <literal>--address <replaceable>
172
172
            If this option is used, the server will only listen to a
173
173
            specific address.  This must currently be an IPv6 address;
174
174
            an IPv4 address can be specified using the
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.
 
175
            "<literal>::FFFF:192.0.2.3</literal>" syntax.  Also, if a
 
176
            link-local address is specified, an interface should be
 
177
            set, since a link-local address is only valid on a single
 
178
            interface.  By default, the server will listen to all
 
179
            available addresses.
180
180
          </para>
181
181
        </listitem>
182
 
      </varlistentry>
 
182
      </varlistentry>          
183
183
 
184
184
      <varlistentry>
185
185
        <term><literal>-p</literal>, <literal>--port <replaceable>
191
191
            port given by the operating system.
192
192
          </para>
193
193
        </listitem>
194
 
      </varlistentry>
 
194
      </varlistentry>          
195
195
 
196
196
      <varlistentry>
197
197
        <term><literal>--check</literal></term>
201
201
            tests, etc.
202
202
          </para>
203
203
        </listitem>
204
 
      </varlistentry>
 
204
      </varlistentry>      
205
205
 
206
206
      <varlistentry>
207
207
        <term><literal>--debug</literal></term>
224
224
            <citerefentry><refentrytitle>gnutls_priority_init
225
225
            </refentrytitle><manvolnum>3</manvolnum></citerefentry>
226
226
            for the syntax.  The default is
227
 
            <quote><literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal></quote>.
 
227
            "<literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal>".
228
228
            <emphasis>Warning</emphasis>: changing this may make the
229
229
            TLS handshake fail, making communication with clients
230
230
            impossible.
231
231
          </para>
232
232
        </listitem>
233
 
      </varlistentry>
 
233
      </varlistentry>      
234
234
 
235
235
      <varlistentry>
236
236
        <term><literal>--servicename <replaceable>NAME</replaceable>
238
238
        <listitem>
239
239
          <para>
240
240
            Zeroconf service name.  The default is
241
 
            <quote><literal>Mandos</literal></quote>.  You only need
242
 
            to change this if you for some reason want to run more
243
 
            than one server on the same <emphasis>host</emphasis>,
244
 
            which would not normally be useful.  If there are name
 
241
            "<literal>Mandos</literal>".  You only need to change this
 
242
            if you for some reason want to run more than one server on
 
243
            the same <emphasis>host</emphasis>.  If there are name
245
244
            collisions on the same <emphasis>network</emphasis>, the
246
 
            newer server will automatically rename itself to
247
 
            <quote><literal>Mandos #2</literal></quote>, and so on,
248
 
            therefore this option is not needed in that case.
 
245
            new server will automatically rename itself to "Mandos
 
246
            #2", etc.
249
247
          </para>
250
248
        </listitem>
251
 
      </varlistentry>
 
249
      </varlistentry>     
252
250
 
253
251
      <varlistentry>
254
252
        <term><literal>--configdir <replaceable>DIR</replaceable>
256
254
        <listitem>
257
255
          <para>
258
256
            Directory to search for configuration files.  Default is
259
 
            <quote><literal>/etc/mandos</literal></quote>.  See
260
 
            <citerefentry><refentrytitle>mandos.conf</refentrytitle>
 
257
            "<literal>/etc/mandos</literal>".  See <citerefentry>
 
258
            <refentrytitle>mandos.conf</refentrytitle>
261
259
            <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
262
260
            <refentrytitle>mandos-clients.conf</refentrytitle>
263
261
            <manvolnum>5</manvolnum></citerefentry>.
272
270
            Prints the program version and exit.
273
271
          </para>
274
272
        </listitem>
275
 
      </varlistentry>
 
273
      </varlistentry>      
276
274
    </variablelist>
277
275
  </refsect1>
278
276
 
280
278
    <title>NETWORK PROTOCOL</title>
281
279
    <para>
282
280
      The Mandos server announces itself as a Zeroconf service of type
283
 
      <quote><literal>_mandos._tcp</literal></quote>.  The Mandos
284
 
      client connects to the announced address and port, and sends a
285
 
      line of text where the first whitespace-separated field is the
286
 
      protocol version, which currently is
287
 
      <quote><literal>1</literal></quote>.  The client and server then
288
 
      start a TLS protocol handshake with a slight quirk: the Mandos
289
 
      server program acts as a TLS <quote>client</quote> while the
290
 
      connecting Mandos client acts as a TLS <quote>server</quote>.
291
 
      The Mandos client must supply an OpenPGP certificate, and the
292
 
      fingerprint of this certificate is used by the Mandos server to
293
 
      look up (in a list read from <filename>clients.conf</filename>
294
 
      at start time) which binary blob to give the client.  No other
295
 
      authentication or authorization is done by the server.
 
281
      "<literal>_mandos._tcp</literal>".  The Mandos client connects
 
282
      to the announced address and port, and sends a line of text
 
283
      where the first whitespace-separated field is the protocol
 
284
      version, which currently is "<literal>1</literal>".  The client
 
285
      and server then start a TLS protocol handshake with a slight
 
286
      quirk: the Mandos server program acts as a TLS "client" while
 
287
      the connecting Mandos client acts as a TLS "server".  The Mandos
 
288
      client must supply an OpenPGP certificate, and the fingerprint
 
289
      of this certificate is used by the Mandos server to look up (in
 
290
      a list read from a file at start time) which binary blob to give
 
291
      the client.  No other authentication or authorization is done by
 
292
      the server.
296
293
    </para>
297
 
    <table>
298
 
      <title>Mandos Protocol (Version 1)</title><tgroup cols="3"><thead>
 
294
    <informaltable><tgroup cols="3"><thead>
299
295
      <row>
300
296
        <entry>Mandos Client</entry>
301
297
        <entry>Direction</entry>
307
303
        <entry>-><!-- &rarr; --></entry>
308
304
      </row>
309
305
      <row>
310
 
        <entry><quote><literal>1\r\en</literal></quote></entry>
 
306
        <entry>"<literal>1\r\en</literal>"</entry>
311
307
        <entry>-><!-- &rarr; --></entry>
312
308
      </row>
313
309
      <row>
314
 
        <entry>TLS handshake <emphasis>as TLS <quote>server</quote>
315
 
        </emphasis></entry>
 
310
        <entry>TLS handshake</entry>
316
311
        <entry>&lt;-><!-- &xharr; --></entry>
317
 
        <entry>TLS handshake <emphasis>as TLS <quote>client</quote>
318
 
        </emphasis></entry>
 
312
        <entry>TLS handshake</entry>
319
313
      </row>
320
314
      <row>
321
315
        <entry>OpenPGP public key (part of TLS handshake)</entry>
324
318
      <row>
325
319
        <entry/>
326
320
        <entry>&lt;-<!-- &larr; --></entry>
327
 
        <entry>Binary blob (client will assume OpenPGP data)</entry>
 
321
        <entry>Binary blob</entry>
328
322
      </row>
329
323
      <row>
330
324
        <entry/>
331
325
        <entry>&lt;-<!-- &larr; --></entry>
332
326
        <entry>Close</entry>
333
327
      </row>
334
 
    </tbody></tgroup></table>
335
 
  </refsect1>
336
 
 
337
 
  <refsect1 id="checking">
338
 
    <title>CHECKING</title>
339
 
    <para>
340
 
      The server will, by default, continually check that the clients
341
 
      are still up.  If a client has not been confirmed as being up
342
 
      for some time, the client is assumed to be compromised and is no
343
 
      longer eligible to receive the encrypted password.  The timeout,
344
 
      checker program and interval between checks can be configured
345
 
      both globally and per client; see <citerefentry>
346
 
      <refentrytitle>mandos.conf</refentrytitle>
347
 
      <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
348
 
      <refentrytitle>mandos-clients.conf</refentrytitle>
349
 
      <manvolnum>5</manvolnum></citerefentry>.
350
 
    </para>
 
328
    </tbody></tgroup></informaltable>
351
329
  </refsect1>
352
330
 
353
331
  <refsect1 id="logging">
354
332
    <title>LOGGING</title>
355
333
    <para>
356
 
      The server will send log messaged with various severity levels
357
 
      to <filename>/dev/log</filename>.  With the
 
334
      The server will log a lot of information with various severity
 
335
      levels to
 
336
      <citerefentry><refentrytitle>syslog</refentrytitle>
 
337
      <manvolnum>8</manvolnum></citerefentry>.  With the
358
338
      <option>--debug</option> option, it will log even more messages,
359
339
      and also show them on the console.
360
340
    </para>
371
351
  <refsect1 id="file">
372
352
    <title>FILES</title>
373
353
    <para>
374
 
      Use the <option>--configdir</option> option to change where
375
 
      <command>&COMMANDNAME;</command> looks for its configurations
376
 
      files.  The default file names are listed here.
 
354
      <itemizedlist>
 
355
        <listitem><para>
 
356
          <filename>/etc/mandos/mandos.conf</filename>  See <citerefentry>
 
357
            <refentrytitle>mandos.conf</refentrytitle>
 
358
            <manvolnum>5</manvolnum></citerefentry>.
 
359
        </para></listitem>
 
360
        <listitem><para>
 
361
          <filename>/etc/mandos/clients.conf</filename> See <citerefentry>
 
362
            <refentrytitle>mandos-clients.conf</refentrytitle>
 
363
            <manvolnum>5</manvolnum></citerefentry>.
 
364
        </para></listitem>
 
365
        <listitem><para>
 
366
          <filename>/var/run/mandos/mandos.pid</filename>
 
367
        </para></listitem>
 
368
      </itemizedlist>
377
369
    </para>
378
 
    <variablelist>
379
 
      <varlistentry>
380
 
        <term><filename>/etc/mandos/mandos.conf</filename></term>
381
 
        <listitem>
382
 
          <para>
383
 
            Server-global settings.  See
384
 
            <citerefentry><refentrytitle>mandos.conf</refentrytitle>
385
 
            <manvolnum>5</manvolnum></citerefentry> for details.
386
 
          </para>
387
 
        </listitem>
388
 
      </varlistentry>
389
 
      <varlistentry>
390
 
        <term><filename>/etc/mandos/clients.conf</filename></term>
391
 
        <listitem>
392
 
          <para>
393
 
            List of clients and client-specific settings.  See
394
 
            <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
395
 
            <manvolnum>5</manvolnum></citerefentry> for details.
396
 
          </para>
397
 
        </listitem>
398
 
      </varlistentry>
399
 
      <varlistentry>
400
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
401
 
        <listitem>
402
 
          <para>
403
 
            The file containing the process id of
404
 
            <command>&COMMANDNAME;</command>.
405
 
          </para>
406
 
        </listitem>
407
 
      </varlistentry>
408
 
      <varlistentry>
409
 
        <term><filename>/dev/log</filename></term>
410
 
        <listitem>
411
 
          <para>
412
 
            The Unix domain socket to where local syslog messages are
413
 
            sent.
414
 
          </para>
415
 
        </listitem>
416
 
      </varlistentry>
417
 
    </variablelist>
418
 
  </refsect1>
 
370
  </refsect1>  
419
371
 
420
372
  <refsect1 id="bugs">
421
373
    <title>BUGS</title>
422
374
    <para>
423
 
      This server might, on especially fatal errors, emit a Python
424
 
      backtrace.  This could be considered a feature.
425
375
    </para>
426
 
  </refsect1>
 
376
  </refsect1>  
427
377
 
428
378
  <refsect1 id="examples">
429
379
    <title>EXAMPLES</title>
430
 
    <informalexample>
431
 
      <para>
432
 
        Normal invocation needs no options:
433
 
      </para>
434
 
      <para>
435
 
        <userinput>mandos</userinput>
436
 
      </para>
437
 
    </informalexample>
438
 
    <informalexample>
439
 
      <para>
440
 
        Run the server in debug mode and read configuration files from
441
 
        the <filename>~/mandos</filename> directory:
442
 
      </para>
443
 
      <para>
444
 
 
445
 
<!-- do not wrap this line -->
446
 
<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>
447
 
 
448
 
      </para>
449
 
    </informalexample>
450
 
    <informalexample>
451
 
      <para>
452
 
        Run the server normally, but only listen to one interface and
453
 
        only on the link-local address on that interface:
454
 
      </para>
455
 
      <para>
456
 
 
457
 
<!-- do not wrap this line -->
458
 
<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>
459
 
 
460
 
      </para>
461
 
    </informalexample>
 
380
    <para>
 
381
    </para>
462
382
  </refsect1>
463
383
 
464
384
  <refsect1 id="security">
465
385
    <title>SECURITY</title>
466
 
    <refsect2>
467
 
      <title>SERVER</title>
468
 
      <para>
469
 
        Running the server should not in itself present any security
470
 
        risk to the host computer running it.
471
 
      </para>
472
 
    </refsect2>
473
 
    <refsect2>
474
 
      <title>CLIENTS</title>
475
 
      <para>
476
 
        The server only gives out its stored data to clients which
477
 
        does have the OpenPGP key of the stored fingerprint.  This is
478
 
        guaranteed by the fact that the client sends its OpenPGP
479
 
        public key in the TLS handshake; this ensures it to be
480
 
        genuine.  The server computes the fingerprint of the key
481
 
        itself and looks up the fingerprint in its list of
482
 
        clients. The <filename>clients.conf</filename> file (see
483
 
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
484
 
        <manvolnum>5</manvolnum></citerefentry>) must be non-readable
485
 
        by anyone except the user running the server.
486
 
      </para>
487
 
      <para>
488
 
        For more details on client-side security, see
489
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
490
 
        <manvolnum>8mandos</manvolnum></citerefentry>.
491
 
      </para>
492
 
    </refsect2>
 
386
    <para>
 
387
    </para>
493
388
  </refsect1>
494
389
 
495
390
  <refsect1 id="see_also">