/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 20:34:18 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080817203418-l691ahxyc7vmezad
* Makefile (MANPOST): Bug fix: do not replace *all* "een" with "en".

* mandos.xml: More improvements.  Replaced " with <quote>'s.
  (NETWORK PROTOCOL): Replaced <informaltable> with <table> with a
                      <title>.
  (CHECKING): New section describing the continual checking of
              clients.
  (LOGGING): We log to /dev/log, not syslog(3).
  (FILES): Changed to use a <variablelist> instead of an
           <itemizedlist>.  Added "/dev/log" and brief descriptions of
           all files.
  (BUGS): Added content.
  (EXAMPLES): - '' -
  (SECURITY): Added content to subsections "SERVER" and "CLIENTS".

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos.xml
31
31
    </authorgroup>
32
32
    <copyright>
33
33
      <year>2008</year>
34
 
      <holder>Teddy Hogeborn &amp; Björn Påhlsson</holder>
 
34
      <holder>Teddy Hogeborn</holder>
 
35
      <holder>Björn Påhlsson</holder>
35
36
    </copyright>
36
37
    <legalnotice>
37
38
      <para>
66
67
  <refnamediv>
67
68
    <refname><command>&COMMANDNAME;</command></refname>
68
69
    <refpurpose>
69
 
      Sends encrypted passwords to authenticated mandos clients
 
70
      Sends encrypted passwords to authenticated Mandos clients
70
71
    </refpurpose>
71
72
  </refnamediv>
72
73
 
73
74
  <refsynopsisdiv>
74
75
    <cmdsynopsis>
75
76
      <command>&COMMANDNAME;</command>
76
 
      <arg choice='opt' rep='repeat'>OPTION</arg>
 
77
      <arg choice='opt'>--interface<arg choice='plain'>IF</arg></arg>
 
78
      <arg choice='opt'>--address<arg choice='plain'>ADDRESS</arg></arg>
 
79
      <arg choice='opt'>--port<arg choice='plain'>PORT</arg></arg>
 
80
      <arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>
 
81
      <arg choice='opt'>--servicename<arg choice='plain'>NAME</arg></arg>
 
82
      <arg choice='opt'>--configdir<arg choice='plain'>DIRECTORY</arg></arg>
 
83
      <arg choice='opt'>--debug</arg>
 
84
    </cmdsynopsis>
 
85
    <cmdsynopsis>
 
86
      <command>&COMMANDNAME;</command>
 
87
      <arg choice='opt'>-i<arg choice='plain'>IF</arg></arg>
 
88
      <arg choice='opt'>-a<arg choice='plain'>ADDRESS</arg></arg>
 
89
      <arg choice='opt'>-p<arg choice='plain'>PORT</arg></arg>
 
90
      <arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>
 
91
      <arg choice='opt'>--servicename<arg choice='plain'>NAME</arg></arg>
 
92
      <arg choice='opt'>--configdir<arg choice='plain'>DIRECTORY</arg></arg>
 
93
      <arg choice='opt'>--debug</arg>
 
94
    </cmdsynopsis>
 
95
    <cmdsynopsis>
 
96
      <command>&COMMANDNAME;</command>
 
97
      <arg choice='plain'>--help</arg>
 
98
    </cmdsynopsis>
 
99
    <cmdsynopsis>
 
100
      <command>&COMMANDNAME;</command>
 
101
      <arg choice='plain'>--version</arg>
 
102
    </cmdsynopsis>
 
103
    <cmdsynopsis>
 
104
      <command>&COMMANDNAME;</command>
 
105
      <arg choice='plain'>--check</arg>
77
106
    </cmdsynopsis>
78
107
  </refsynopsisdiv>
79
108
 
80
109
  <refsect1 id="description">
81
110
    <title>DESCRIPTION</title>
82
111
    <para>
83
 
      <command>&COMMANDNAME;</command> is a server daemon that handels
84
 
      incomming passwords request for passwords. Mandos use avahi to
85
 
      announce the service, and through gnutls authenticates
86
 
      clients. Any authenticated client is then given its encrypted
87
 
      password.
88
 
    </para>
 
112
      <command>&COMMANDNAME;</command> is a server daemon which
 
113
      handles incoming request for passwords for a pre-defined list of
 
114
      client host computers.  The Mandos server uses Zeroconf to
 
115
      announce itself on the local network, and uses GnuTLS to
 
116
      communicate securely with and to authenticate the clients.
 
117
      Mandos uses IPv6 link-local addresses, since the clients are
 
118
      assumed to not have any other addresses configured.  Any
 
119
      authenticated client is then given the pre-encrypted password
 
120
      for that specific client.
 
121
    </para>
 
122
 
 
123
  </refsect1>
 
124
  
 
125
  <refsect1 id="purpose">
 
126
    <title>PURPOSE</title>
 
127
 
 
128
    <para>
 
129
      The purpose of this is to enable <emphasis>remote and unattended
 
130
      rebooting</emphasis> of any client host computer with an
 
131
      <emphasis>encrypted root file system</emphasis>.  The client
 
132
      host computer should start a Mandos client in the initial RAM
 
133
      disk environment, the Mandos client program communicates with
 
134
      this server program to get an encrypted password, which is then
 
135
      decrypted and used to unlock the encrypted root file system.
 
136
      The client host computer can then continue its boot sequence
 
137
      normally.
 
138
    </para>
 
139
 
 
140
  </refsect1>
 
141
  
 
142
  <refsect1 id="options">
 
143
    <title>OPTIONS</title>
89
144
 
90
145
    <variablelist>
91
146
      <varlistentry>
92
147
        <term><literal>-h</literal>, <literal>--help</literal></term>
93
148
        <listitem>
94
149
          <para>
95
 
            show a help message and exit
 
150
            Show a help message and exit
96
151
          </para>
97
152
        </listitem>
98
153
      </varlistentry>
102
157
        IF</replaceable></literal></term>
103
158
        <listitem>
104
159
          <para>
105
 
            Bind to interface IF
 
160
            Only announce the server and listen to requests on network
 
161
            interface <replaceable>IF</replaceable>.  Default is to
 
162
            use all available interfaces.
106
163
          </para>
107
164
        </listitem>
108
 
      </varlistentry>      
 
165
      </varlistentry>
109
166
 
110
167
      <varlistentry>
111
168
        <term><literal>-a</literal>, <literal>--address <replaceable>
112
169
        ADDRESS</replaceable></literal></term>
113
170
        <listitem>
114
171
          <para>
115
 
            Address to listen for requests on
 
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
 
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.
116
180
          </para>
117
181
        </listitem>
118
 
      </varlistentry>          
 
182
      </varlistentry>
119
183
 
120
184
      <varlistentry>
121
185
        <term><literal>-p</literal>, <literal>--port <replaceable>
122
186
        PORT</replaceable></literal></term>
123
187
        <listitem>
124
188
          <para>
125
 
            Port number to receive requests on
 
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.
126
192
          </para>
127
193
        </listitem>
128
 
      </varlistentry>          
 
194
      </varlistentry>
129
195
 
130
196
      <varlistentry>
131
197
        <term><literal>--check</literal></term>
132
198
        <listitem>
133
199
          <para>
134
 
            Run self-test on the server
 
200
            Run the server's self-tests.  This includes any unit
 
201
            tests, etc.
135
202
          </para>
136
203
        </listitem>
137
 
      </varlistentry>      
 
204
      </varlistentry>
138
205
 
139
206
      <varlistentry>
140
207
        <term><literal>--debug</literal></term>
141
208
        <listitem>
142
209
          <para>
143
 
            Debug mode
 
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.
144
213
          </para>
145
214
        </listitem>
146
215
      </varlistentry>
150
219
        PRIORITY</replaceable></literal></term>
151
220
        <listitem>
152
221
          <para>
153
 
            GnuTLS priority string. See <citerefentry>
154
 
            <refentrytitle>gnutls_priority_init</refentrytitle>
155
 
            <manvolnum>3</manvolnum></citerefentry>
 
222
            GnuTLS priority string for the TLS handshake with the
 
223
            clients.  See
 
224
            <citerefentry><refentrytitle>gnutls_priority_init
 
225
            </refentrytitle><manvolnum>3</manvolnum></citerefentry>
 
226
            for the syntax.  The default is
 
227
            <quote><literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal></quote>.
 
228
            <emphasis>Warning</emphasis>: changing this may make the
 
229
            TLS handshake fail, making communication with clients
 
230
            impossible.
156
231
          </para>
157
232
        </listitem>
158
 
      </varlistentry>      
 
233
      </varlistentry>
159
234
 
160
235
      <varlistentry>
161
236
        <term><literal>--servicename <replaceable>NAME</replaceable>
162
237
        </literal></term>
163
238
        <listitem>
164
239
          <para>
165
 
            Zeroconf service name
 
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
 
245
            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.
166
249
          </para>
167
250
        </listitem>
168
 
      </varlistentry>     
 
251
      </varlistentry>
169
252
 
170
253
      <varlistentry>
171
254
        <term><literal>--configdir <replaceable>DIR</replaceable>
172
255
        </literal></term>
173
256
        <listitem>
174
257
          <para>
175
 
            Directory to search for configuration files
176
 
          </para>
177
 
        </listitem>
178
 
      </varlistentry>
179
 
      
180
 
    </variablelist>
 
258
            Directory to search for configuration files.  Default is
 
259
            <quote><literal>/etc/mandos</literal></quote>.  See
 
260
            <citerefentry><refentrytitle>mandos.conf</refentrytitle>
 
261
            <manvolnum>5</manvolnum></citerefentry> and <citerefentry>
 
262
            <refentrytitle>mandos-clients.conf</refentrytitle>
 
263
            <manvolnum>5</manvolnum></citerefentry>.
 
264
          </para>
 
265
        </listitem>
 
266
      </varlistentry>
 
267
 
 
268
      <varlistentry>
 
269
        <term><literal>--version</literal></term>
 
270
        <listitem>
 
271
          <para>
 
272
            Prints the program version and exit.
 
273
          </para>
 
274
        </listitem>
 
275
      </varlistentry>
 
276
    </variablelist>
 
277
  </refsect1>
 
278
 
 
279
  <refsect1 id="protocol">
 
280
    <title>NETWORK PROTOCOL</title>
 
281
    <para>
 
282
      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.
 
296
    </para>
 
297
    <table>
 
298
      <title>Mandos Protocol (Version 1)</title><tgroup cols="3"><thead>
 
299
      <row>
 
300
        <entry>Mandos Client</entry>
 
301
        <entry>Direction</entry>
 
302
        <entry>Mandos Server</entry>
 
303
      </row>
 
304
      </thead><tbody>
 
305
      <row>
 
306
        <entry>Connect</entry>
 
307
        <entry>-><!-- &rarr; --></entry>
 
308
      </row>
 
309
      <row>
 
310
        <entry><quote><literal>1\r\en</literal></quote></entry>
 
311
        <entry>-><!-- &rarr; --></entry>
 
312
      </row>
 
313
      <row>
 
314
        <entry>TLS handshake <emphasis>as TLS <quote>server</quote>
 
315
        </emphasis></entry>
 
316
        <entry>&lt;-><!-- &xharr; --></entry>
 
317
        <entry>TLS handshake <emphasis>as TLS <quote>client</quote>
 
318
        </emphasis></entry>
 
319
      </row>
 
320
      <row>
 
321
        <entry>OpenPGP public key (part of TLS handshake)</entry>
 
322
        <entry>-><!-- &rarr; --></entry>
 
323
      </row>
 
324
      <row>
 
325
        <entry/>
 
326
        <entry>&lt;-<!-- &larr; --></entry>
 
327
        <entry>Binary blob (client will assume OpenPGP data)</entry>
 
328
      </row>
 
329
      <row>
 
330
        <entry/>
 
331
        <entry>&lt;-<!-- &larr; --></entry>
 
332
        <entry>Close</entry>
 
333
      </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>
 
351
  </refsect1>
 
352
 
 
353
  <refsect1 id="logging">
 
354
    <title>LOGGING</title>
 
355
    <para>
 
356
      The server will send log messaged with various severity levels
 
357
      to <filename>/dev/log</filename>.  With the
 
358
      <option>--debug</option> option, it will log even more messages,
 
359
      and also show them on the console.
 
360
    </para>
 
361
  </refsect1>
 
362
 
 
363
  <refsect1 id="exit_status">
 
364
    <title>EXIT STATUS</title>
 
365
    <para>
 
366
      The server will exit with a non-zero exit status only when a
 
367
      critical error is encountered.
 
368
    </para>
 
369
  </refsect1>
 
370
 
 
371
  <refsect1 id="file">
 
372
    <title>FILES</title>
 
373
    <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.
 
377
    </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>
 
419
 
 
420
  <refsect1 id="bugs">
 
421
    <title>BUGS</title>
 
422
    <para>
 
423
      This server might, on especially fatal errors, emit a Python
 
424
      backtrace.  This could be considered a feature.
 
425
    </para>
 
426
  </refsect1>
 
427
 
 
428
  <refsect1 id="examples">
 
429
    <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>
 
462
  </refsect1>
 
463
 
 
464
  <refsect1 id="security">
 
465
    <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>
 
493
  </refsect1>
 
494
 
 
495
  <refsect1 id="see_also">
 
496
    <title>SEE ALSO</title>
 
497
    <itemizedlist spacing="compact">
 
498
      <listitem><para>
 
499
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
500
        <manvolnum>8mandos</manvolnum></citerefentry>
 
501
      </para></listitem>
 
502
      
 
503
      <listitem><para>
 
504
        <citerefentry><refentrytitle>plugin-runner</refentrytitle>
 
505
        <manvolnum>8mandos</manvolnum></citerefentry>
 
506
      </para></listitem>
 
507
      
 
508
      <listitem><para>
 
509
        <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
 
510
      </para></listitem>
 
511
      
 
512
      <listitem><para>
 
513
        <ulink url="http://www.avahi.org/">Avahi</ulink>
 
514
      </para></listitem>
 
515
      
 
516
      <listitem><para>
 
517
        <ulink
 
518
            url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
 
519
      </para></listitem>
 
520
      
 
521
      <listitem><para>
 
522
        <citation>RFC 4880: <citetitle>OpenPGP Message
 
523
        Format</citetitle></citation>
 
524
      </para></listitem>
 
525
      
 
526
      <listitem><para>
 
527
        <citation>RFC 5081: <citetitle>Using OpenPGP Keys for
 
528
        Transport Layer Security</citetitle></citation>
 
529
      </para></listitem>
 
530
      
 
531
      <listitem><para>
 
532
        <citation>RFC 4291: <citetitle>IP Version 6 Addressing
 
533
        Architecture</citetitle>, section 2.5.6, Link-Local IPv6
 
534
        Unicast Addresses</citation>
 
535
      </para></listitem>
 
536
    </itemizedlist>
181
537
  </refsect1>
182
538
</refentry>