/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: 2009-02-09 02:01:13 UTC
  • Revision ID: teddy@fukt.bsnet.se-20090209020113-726hq380zvp8zt97
Four new interrelated features:

1. Support using a different network interface via both initramfs.conf
   (the DEVICE setting) and the kernel command line (sixth field of
   the "ip=" option as in Linux' Documentation/nfsroot.txt).

2. Support connecting to a specified Mandos server directly using a
   kernel command line option ("mandos=connect:<ADDRESS>:<PORT>").

3. Support connecting directly to an IPv4 address (and port) using the
   "--connect" option of mandos-client.

4. Support an empty string to the --interface option to mandos-client.

* Makefile (WARN): Increase strictness by changing to
                   "-Wstrict-aliasing=1".

* debian/mandos-client.README.Debian (Use the Correct Network
  Interface): Changed to refer to initramfs.conf and nfsroot.txt.
  (Test the Server): Improve wording.
  (Non-local Connection): New section.
* initramfs-tools-script: Obey DEVICE environment variable and setting
                          from "/conf/initramfs.conf".  Also let any
                          "ip=" kernel command line option override
                          it.  Support new "mandos=connect" option.
                          Call "configure_networking" to set up IP
                          address on interface if necessary.
* plugin-runner.conf: Change example.
* plugins.d/mandos-client.c: Some whitespace and comment changes.
  (start_mandos_communication): Take an additional argument for
                                address family, all callers changed.
                                Connect to an IPv4 address if address
                                family is AF_INET.  Only set IPv6
                                scope_id for link-local addresses.
  (main): Accept empty interface name; this will not bring up any
         interface and leave the interface as unspecified.  Also do
         not restore kernel log level if lowering it failed.
* plugins.d/mandos-client.xml (OPTIONS): Document that the
                                         "--interface" option accepts
                                         an empty string.
  (EXAMPLE): Change example IPv6 address to a link-local address.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mandos.xml
1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
 
<!ENTITY VERSION "1.0">
5
4
<!ENTITY COMMANDNAME "mandos">
6
 
<!ENTITY TIMESTAMP "2008-09-02">
 
5
<!ENTITY TIMESTAMP "2009-01-04">
 
6
<!ENTITY % common SYSTEM "common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
 
  <refentryinfo>
 
11
   <refentryinfo>
11
12
    <title>Mandos Manual</title>
12
13
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
13
14
    <productname>Mandos</productname>
14
 
    <productnumber>&VERSION;</productnumber>
 
15
    <productnumber>&version;</productnumber>
15
16
    <date>&TIMESTAMP;</date>
16
17
    <authorgroup>
17
18
      <author>
31
32
    </authorgroup>
32
33
    <copyright>
33
34
      <year>2008</year>
 
35
      <year>2009</year>
34
36
      <holder>Teddy Hogeborn</holder>
35
37
      <holder>Björn Påhlsson</holder>
36
38
    </copyright>
37
39
    <xi:include href="legalnotice.xml"/>
38
40
  </refentryinfo>
39
 
 
 
41
  
40
42
  <refmeta>
41
43
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
44
    <manvolnum>8</manvolnum>
48
50
      Gives encrypted passwords to authenticated Mandos clients
49
51
    </refpurpose>
50
52
  </refnamediv>
51
 
 
 
53
  
52
54
  <refsynopsisdiv>
53
55
    <cmdsynopsis>
54
56
      <command>&COMMANDNAME;</command>
83
85
      <replaceable>DIRECTORY</replaceable></option></arg>
84
86
      <sbr/>
85
87
      <arg><option>--debug</option></arg>
 
88
      <sbr/>
 
89
      <arg><option>--no-dbus</option></arg>
86
90
    </cmdsynopsis>
87
91
    <cmdsynopsis>
88
92
      <command>&COMMANDNAME;</command>
100
104
      <arg choice="plain"><option>--check</option></arg>
101
105
    </cmdsynopsis>
102
106
  </refsynopsisdiv>
103
 
 
 
107
  
104
108
  <refsect1 id="description">
105
109
    <title>DESCRIPTION</title>
106
110
    <para>
186
190
          <xi:include href="mandos-options.xml" xpointer="debug"/>
187
191
        </listitem>
188
192
      </varlistentry>
189
 
 
 
193
      
190
194
      <varlistentry>
191
195
        <term><option>--priority <replaceable>
192
196
        PRIORITY</replaceable></option></term>
194
198
          <xi:include href="mandos-options.xml" xpointer="priority"/>
195
199
        </listitem>
196
200
      </varlistentry>
197
 
 
 
201
      
198
202
      <varlistentry>
199
203
        <term><option>--servicename
200
204
        <replaceable>NAME</replaceable></option></term>
203
207
                      xpointer="servicename"/>
204
208
        </listitem>
205
209
      </varlistentry>
206
 
 
 
210
      
207
211
      <varlistentry>
208
212
        <term><option>--configdir
209
213
        <replaceable>DIRECTORY</replaceable></option></term>
218
222
          </para>
219
223
        </listitem>
220
224
      </varlistentry>
221
 
 
 
225
      
222
226
      <varlistentry>
223
227
        <term><option>--version</option></term>
224
228
        <listitem>
227
231
          </para>
228
232
        </listitem>
229
233
      </varlistentry>
 
234
      
 
235
      <varlistentry>
 
236
        <term><option>--no-dbus</option></term>
 
237
        <listitem>
 
238
          <xi:include href="mandos-options.xml" xpointer="dbus"/>
 
239
          <para>
 
240
            See also <xref linkend="dbus_interface"/>.
 
241
          </para>
 
242
        </listitem>
 
243
      </varlistentry>
230
244
    </variablelist>
231
245
  </refsect1>
232
 
 
 
246
  
233
247
  <refsect1 id="overview">
234
248
    <title>OVERVIEW</title>
235
249
    <xi:include href="overview.xml"/>
239
253
      <acronym>RAM</acronym> disk environment.
240
254
    </para>
241
255
  </refsect1>
242
 
 
 
256
  
243
257
  <refsect1 id="protocol">
244
258
    <title>NETWORK PROTOCOL</title>
245
259
    <para>
297
311
      </row>
298
312
    </tbody></tgroup></table>
299
313
  </refsect1>
300
 
 
 
314
  
301
315
  <refsect1 id="checking">
302
316
    <title>CHECKING</title>
303
317
    <para>
311
325
      <manvolnum>5</manvolnum></citerefentry>.
312
326
    </para>
313
327
  </refsect1>
314
 
 
 
328
  
315
329
  <refsect1 id="logging">
316
330
    <title>LOGGING</title>
317
331
    <para>
321
335
      and also show them on the console.
322
336
    </para>
323
337
  </refsect1>
 
338
  
 
339
  <refsect1 id="dbus_interface">
 
340
    <title>D-BUS INTERFACE</title>
 
341
    <para>
 
342
      The server will by default provide a D-Bus system bus interface.
 
343
      This interface will only be accessible by the root user or a
 
344
      Mandos-specific user, if such a user exists.
 
345
      <!-- XXX -->
 
346
    </para>
 
347
  </refsect1>
324
348
 
325
349
  <refsect1 id="exit_status">
326
350
    <title>EXIT STATUS</title>
329
353
      critical error is encountered.
330
354
    </para>
331
355
  </refsect1>
332
 
 
 
356
  
333
357
  <refsect1 id="environment">
334
358
    <title>ENVIRONMENT</title>
335
359
    <variablelist>
349
373
      </varlistentry>
350
374
    </variablelist>
351
375
  </refsect1>
352
 
 
353
 
  <refsect1 id="file">
 
376
  
 
377
  <refsect1 id="files">
354
378
    <title>FILES</title>
355
379
    <para>
356
380
      Use the <option>--configdir</option> option to change where
379
403
        </listitem>
380
404
      </varlistentry>
381
405
      <varlistentry>
382
 
        <term><filename>/var/run/mandos/mandos.pid</filename></term>
 
406
        <term><filename>/var/run/mandos.pid</filename></term>
383
407
        <listitem>
384
408
          <para>
385
409
            The file containing the process id of
420
444
      Currently, if a client is declared <quote>invalid</quote> due to
421
445
      having timed out, the server does not record this fact onto
422
446
      permanent storage.  This has some security implications, see
423
 
      <xref linkend="CLIENTS"/>.
 
447
      <xref linkend="clients"/>.
424
448
    </para>
425
449
    <para>
426
450
      There is currently no way of querying the server of the current
434
458
      Debug mode is conflated with running in the foreground.
435
459
    </para>
436
460
    <para>
437
 
      The console log messages does not show a timestamp.
 
461
      The console log messages does not show a time stamp.
 
462
    </para>
 
463
    <para>
 
464
      This server does not check the expire time of clients’ OpenPGP
 
465
      keys.
438
466
    </para>
439
467
  </refsect1>
440
468
  
475
503
      </para>
476
504
    </informalexample>
477
505
  </refsect1>
478
 
 
 
506
  
479
507
  <refsect1 id="security">
480
508
    <title>SECURITY</title>
481
 
    <refsect2 id="SERVER">
 
509
    <refsect2 id="server">
482
510
      <title>SERVER</title>
483
511
      <para>
484
512
        Running this <command>&COMMANDNAME;</command> server program
485
513
        should not in itself present any security risk to the host
486
 
        computer running it.  The program does not need any special
487
 
        privileges to run, and is designed to run as a non-root user.
 
514
        computer running it.  The program switches to a non-root user
 
515
        soon after startup.
488
516
      </para>
489
517
    </refsect2>
490
 
    <refsect2 id="CLIENTS">
 
518
    <refsect2 id="clients">
491
519
      <title>CLIENTS</title>
492
520
      <para>
493
521
        The server only gives out its stored data to clients which
500
528
        <citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>
501
529
        <manvolnum>5</manvolnum></citerefentry>)
502
530
        <emphasis>must</emphasis> be made non-readable by anyone
503
 
        except the user running the server.
 
531
        except the user starting the server (usually root).
504
532
      </para>
505
533
      <para>
506
534
        As detailed in <xref linkend="checking"/>, the status of all
525
553
      </para>
526
554
      <para>
527
555
        For more details on client-side security, see
528
 
        <citerefentry><refentrytitle>password-request</refentrytitle>
 
556
        <citerefentry><refentrytitle>mandos-client</refentrytitle>
529
557
        <manvolnum>8mandos</manvolnum></citerefentry>.
530
558
      </para>
531
559
    </refsect2>
532
560
  </refsect1>
533
 
 
 
561
  
534
562
  <refsect1 id="see_also">
535
563
    <title>SEE ALSO</title>
536
564
    <para>
539
567
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
540
568
        <refentrytitle>mandos.conf</refentrytitle>
541
569
        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>
542
 
        <refentrytitle>password-request</refentrytitle>
 
570
        <refentrytitle>mandos-client</refentrytitle>
543
571
        <manvolnum>8mandos</manvolnum></citerefentry>, <citerefentry>
544
572
        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>
545
573
      </citerefentry>