/mandos/release

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

« back to all changes in this revision

Viewing changes to plugins.d/mandos-client.xml

Merge from Björn.

Show diffs side-by-side

added added

removed removed

Lines of Context:
plugins.d/mandos-client.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-client">
6
 
<!ENTITY TIMESTAMP "2008-09-06">
 
5
<!ENTITY TIMESTAMP "2010-09-26">
 
6
<!ENTITY % common SYSTEM "../common.ent">
 
7
%common;
7
8
]>
8
9
 
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
10
11
  <refentryinfo>
11
12
    <title>Mandos Manual</title>
12
 
    <!-- Nwalsh’s docbook scripts use this to generate the footer: -->
 
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>8mandos</manvolnum>
48
50
      Client for <application>Mandos</application>
49
51
    </refpurpose>
50
52
  </refnamediv>
51
 
 
 
53
  
52
54
  <refsynopsisdiv>
53
55
    <cmdsynopsis>
54
56
      <command>&COMMANDNAME;</command>
91
93
      </arg>
92
94
      <sbr/>
93
95
      <arg>
 
96
        <option>--delay <replaceable>SECONDS</replaceable></option>
 
97
      </arg>
 
98
      <sbr/>
 
99
      <arg>
 
100
        <option>--retry <replaceable>SECONDS</replaceable></option>
 
101
      </arg>
 
102
      <sbr/>
 
103
      <arg>
94
104
        <option>--debug</option>
95
105
      </arg>
96
106
    </cmdsynopsis>
113
123
      </group>
114
124
    </cmdsynopsis>
115
125
  </refsynopsisdiv>
116
 
 
 
126
  
117
127
  <refsect1 id="description">
118
128
    <title>DESCRIPTION</title>
119
129
    <para>
120
130
      <command>&COMMANDNAME;</command> is a client program that
121
131
      communicates with <citerefentry><refentrytitle
122
132
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
123
 
      to get a password.  It uses IPv6 link-local addresses to get
124
 
      network connectivity, Zeroconf to find servers, and TLS with an
125
 
      OpenPGP key to ensure authenticity and confidentiality.  It
126
 
      keeps running, trying all servers on the network, until it
127
 
      receives a satisfactory reply or a TERM signal is received.
 
133
      to get a password.  In slightly more detail, this client program
 
134
      brings up a network interface, uses the interface’s IPv6
 
135
      link-local address to get network connectivity, uses Zeroconf to
 
136
      find servers on the local network, and communicates with servers
 
137
      using TLS with an OpenPGP key to ensure authenticity and
 
138
      confidentiality.  This client program keeps running, trying all
 
139
      servers on the network, until it receives a satisfactory reply
 
140
      or a TERM signal is received.  If no servers are found, or after
 
141
      all servers have been tried, it waits indefinitely for new
 
142
      servers to appear.
128
143
    </para>
129
144
    <para>
130
145
      This program is not meant to be run directly; it is really meant
184
199
      </varlistentry>
185
200
      
186
201
      <varlistentry>
187
 
        <term><option>--interface=
188
 
        <replaceable>NAME</replaceable></option></term>
 
202
        <term><option>--interface=<replaceable
 
203
        >NAME</replaceable></option></term>
189
204
        <term><option>-i
190
205
        <replaceable>NAME</replaceable></option></term>
191
206
        <listitem>
192
207
          <para>
193
208
            Network interface that will be brought up and scanned for
194
 
            Mandos servers to connect to.  The default it
195
 
            <quote><literal>eth0</literal></quote>.
 
209
            Mandos servers to connect to.  The default is the empty
 
210
            string, which will automatically choose an appropriate
 
211
            interface.
196
212
          </para>
197
213
          <para>
198
214
            If the <option>--connect</option> option is used, this
199
215
            specifies the interface to use to connect to the address
200
216
            given.
201
217
          </para>
 
218
          <para>
 
219
            Note that since this program will normally run in the
 
220
            initial RAM disk environment, the interface must be an
 
221
            interface which exists at that stage.  Thus, the interface
 
222
            can not be a pseudo-interface such as <quote>br0</quote>
 
223
            or <quote>tun0</quote>; such interfaces will not exist
 
224
            until much later in the boot process, and can not be used
 
225
            by this program.
 
226
          </para>
 
227
          <para>
 
228
            <replaceable>NAME</replaceable> can be the string
 
229
            <quote><literal>none</literal></quote>; this will not use
 
230
            any specific interface, and will not bring up an interface
 
231
            on startup.  This is not recommended, and only meant for
 
232
            advanced users.
 
233
          </para>
202
234
        </listitem>
203
235
      </varlistentry>
204
236
      
215
247
          </para>
216
248
        </listitem>
217
249
      </varlistentry>
218
 
 
 
250
      
219
251
      <varlistentry>
220
252
        <term><option>--seckey=<replaceable
221
253
        >FILE</replaceable></option></term>
238
270
                      xpointer="priority"/>
239
271
        </listitem>
240
272
      </varlistentry>
241
 
 
 
273
      
242
274
      <varlistentry>
243
275
        <term><option>--dh-bits=<replaceable
244
276
        >BITS</replaceable></option></term>
249
281
          </para>
250
282
        </listitem>
251
283
      </varlistentry>
 
284
 
 
285
      <varlistentry>
 
286
        <term><option>--delay=<replaceable
 
287
        >SECONDS</replaceable></option></term>
 
288
        <listitem>
 
289
          <para>
 
290
            After bringing the network interface up, the program waits
 
291
            for the interface to arrive in a <quote>running</quote>
 
292
            state before proceeding.  During this time, the kernel log
 
293
            level will be lowered to reduce clutter on the system
 
294
            console, alleviating any other plugins which might be
 
295
            using the system console.  This option sets the upper
 
296
            limit of seconds to wait.  The default is 2.5 seconds.
 
297
          </para>
 
298
        </listitem>
 
299
      </varlistentry>
 
300
 
 
301
      <varlistentry>
 
302
        <term><option>--retry=<replaceable
 
303
        >SECONDS</replaceable></option></term>
 
304
        <listitem>
 
305
          <para>
 
306
            All Mandos servers servers are tried repeatedly until a
 
307
            password is received.  This value specifies, in seconds,
 
308
            how long between each successive try <emphasis>for the
 
309
            same server</emphasis>.  The default is 10 seconds.
 
310
          </para>
 
311
        </listitem>
 
312
      </varlistentry>
252
313
      
253
314
      <varlistentry>
254
315
        <term><option>--debug</option></term>
284
345
          </para>
285
346
        </listitem>
286
347
      </varlistentry>
287
 
 
 
348
      
288
349
      <varlistentry>
289
350
        <term><option>--version</option></term>
290
351
        <term><option>-V</option></term>
296
357
      </varlistentry>
297
358
    </variablelist>
298
359
  </refsect1>
299
 
 
 
360
  
300
361
  <refsect1 id="overview">
301
362
    <title>OVERVIEW</title>
302
363
    <xi:include href="../overview.xml"/>
343
404
    </para>
344
405
  </refsect1>
345
406
  
346
 
  <refsect1 id="file">
 
407
  <refsect1 id="files">
347
408
    <title>FILES</title>
348
409
    <variablelist>
349
410
      <varlistentry>
368
429
<!--     <para> -->
369
430
<!--     </para> -->
370
431
<!--   </refsect1> -->
371
 
 
 
432
  
372
433
  <refsect1 id="example">
373
434
    <title>EXAMPLE</title>
374
435
    <para>
410
471
    <informalexample>
411
472
      <para>
412
473
        Run in debug mode, with a custom key, and do not use Zeroconf
413
 
        to locate a server; connect directly to the IPv6 address
414
 
        <quote><systemitem class="ipaddress"
415
 
        >2001:db8:f983:bd0b:30de:ae4a:71f2:f672</systemitem></quote>,
416
 
        port 4711, using interface eth2:
 
474
        to locate a server; connect directly to the IPv6 link-local
 
475
        address <quote><systemitem class="ipaddress"
 
476
        >fe80::aede:48ff:fe71:f6f2</systemitem></quote>, port 4711,
 
477
        using interface eth2:
417
478
      </para>
418
479
      <para>
419
480
 
420
481
<!-- do not wrap this line -->
421
 
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --connect 2001:db8:f983:bd0b:30de:ae4a:71f2:f672:4711 --interface eth2</userinput>
 
482
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --connect fe80::aede:48ff:fe71:f6f2:4711 --interface eth2</userinput>
422
483
 
423
484
      </para>
424
485
    </informalexample>
425
486
  </refsect1>
426
 
 
 
487
  
427
488
  <refsect1 id="security">
428
489
    <title>SECURITY</title>
429
490
    <para>
449
510
      The only remaining weak point is that someone with physical
450
511
      access to the client hard drive might turn off the client
451
512
      computer, read the OpenPGP keys directly from the hard drive,
452
 
      and communicate with the server.  The defense against this is
453
 
      that the server is supposed to notice the client disappearing
454
 
      and will stop giving out the encrypted data.  Therefore, it is
455
 
      important to set the timeout and checker interval values tightly
456
 
      on the server.  See <citerefentry><refentrytitle
 
513
      and communicate with the server.  To safeguard against this, the
 
514
      server is supposed to notice the client disappearing and stop
 
515
      giving out the encrypted data.  Therefore, it is important to
 
516
      set the timeout and checker interval values tightly on the
 
517
      server.  See <citerefentry><refentrytitle
457
518
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
458
519
    </para>
459
520
    <para>
470
531
      confidential.
471
532
    </para>
472
533
  </refsect1>
473
 
 
 
534
  
474
535
  <refsect1 id="see_also">
475
536
    <title>SEE ALSO</title>
476
537
    <para>
601
662
      </varlistentry>
602
663
    </variablelist>
603
664
  </refsect1>
604
 
 
605
665
</refentry>
 
666
 
606
667
<!-- Local Variables: -->
607
668
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
608
669
<!-- time-stamp-end: "[\"']>" -->