/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 plugins.d/mandos-client.xml

  • Committer: Teddy Hogeborn
  • Date: 2008-09-08 18:54:47 UTC
  • Revision ID: teddy@fukt.bsnet.se-20080908185447-dm2ertwxa20qbckf
* INSTALL: Even better text.

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">
4
5
<!ENTITY COMMANDNAME "mandos-client">
5
 
<!ENTITY TIMESTAMP "2011-10-03">
6
 
<!ENTITY % common SYSTEM "../common.ent">
7
 
%common;
 
6
<!ENTITY TIMESTAMP "2008-09-06">
8
7
]>
9
8
 
10
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
10
  <refentryinfo>
12
11
    <title>Mandos Manual</title>
13
 
    <!-- NWalsh’s docbook scripts use this to generate the footer: -->
 
12
    <!-- Nwalsh’s docbook scripts use this to generate the footer: -->
14
13
    <productname>Mandos</productname>
15
 
    <productnumber>&version;</productnumber>
 
14
    <productnumber>&VERSION;</productnumber>
16
15
    <date>&TIMESTAMP;</date>
17
16
    <authorgroup>
18
17
      <author>
19
18
        <firstname>Björn</firstname>
20
19
        <surname>Påhlsson</surname>
21
20
        <address>
22
 
          <email>belorn@recompile.se</email>
 
21
          <email>belorn@fukt.bsnet.se</email>
23
22
        </address>
24
23
      </author>
25
24
      <author>
26
25
        <firstname>Teddy</firstname>
27
26
        <surname>Hogeborn</surname>
28
27
        <address>
29
 
          <email>teddy@recompile.se</email>
 
28
          <email>teddy@fukt.bsnet.se</email>
30
29
        </address>
31
30
      </author>
32
31
    </authorgroup>
33
32
    <copyright>
34
33
      <year>2008</year>
35
 
      <year>2009</year>
36
 
      <year>2011</year>
37
34
      <holder>Teddy Hogeborn</holder>
38
35
      <holder>Björn Påhlsson</holder>
39
36
    </copyright>
40
37
    <xi:include href="../legalnotice.xml"/>
41
38
  </refentryinfo>
42
 
  
 
39
 
43
40
  <refmeta>
44
41
    <refentrytitle>&COMMANDNAME;</refentrytitle>
45
42
    <manvolnum>8mandos</manvolnum>
51
48
      Client for <application>Mandos</application>
52
49
    </refpurpose>
53
50
  </refnamediv>
54
 
  
 
51
 
55
52
  <refsynopsisdiv>
56
53
    <cmdsynopsis>
57
54
      <command>&COMMANDNAME;</command>
94
91
      </arg>
95
92
      <sbr/>
96
93
      <arg>
97
 
        <option>--delay <replaceable>SECONDS</replaceable></option>
98
 
      </arg>
99
 
      <sbr/>
100
 
      <arg>
101
 
        <option>--retry <replaceable>SECONDS</replaceable></option>
102
 
      </arg>
103
 
      <sbr/>
104
 
      <arg>
105
 
        <option>--network-hook-dir<replaceable>DIR</replaceable></option>
106
 
      </arg>
107
 
      <sbr/>
108
 
      <arg>
109
94
        <option>--debug</option>
110
95
      </arg>
111
96
    </cmdsynopsis>
128
113
      </group>
129
114
    </cmdsynopsis>
130
115
  </refsynopsisdiv>
131
 
  
 
116
 
132
117
  <refsect1 id="description">
133
118
    <title>DESCRIPTION</title>
134
119
    <para>
135
120
      <command>&COMMANDNAME;</command> is a client program that
136
121
      communicates with <citerefentry><refentrytitle
137
122
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
138
 
      to get a password.  In slightly more detail, this client program
139
 
      brings up a network interface, uses the interface’s IPv6
140
 
      link-local address to get network connectivity, uses Zeroconf to
141
 
      find servers on the local network, and communicates with servers
142
 
      using TLS with an OpenPGP key to ensure authenticity and
143
 
      confidentiality.  This client program keeps running, trying all
144
 
      servers on the network, until it receives a satisfactory reply
145
 
      or a TERM signal.  After all servers have been tried, all
146
 
      servers are periodically retried.  If no servers are found it
147
 
      will wait indefinitely for new servers to appear.
 
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.
148
128
    </para>
149
129
    <para>
150
130
      This program is not meant to be run directly; it is really meant
204
184
      </varlistentry>
205
185
      
206
186
      <varlistentry>
207
 
        <term><option>--interface=<replaceable
208
 
        >NAME</replaceable></option></term>
 
187
        <term><option>--interface=
 
188
        <replaceable>NAME</replaceable></option></term>
209
189
        <term><option>-i
210
190
        <replaceable>NAME</replaceable></option></term>
211
191
        <listitem>
212
192
          <para>
213
193
            Network interface that will be brought up and scanned for
214
 
            Mandos servers to connect to.  The default is the empty
215
 
            string, which will automatically choose an appropriate
216
 
            interface.
 
194
            Mandos servers to connect to.  The default it
 
195
            <quote><literal>eth0</literal></quote>.
217
196
          </para>
218
197
          <para>
219
198
            If the <option>--connect</option> option is used, this
220
199
            specifies the interface to use to connect to the address
221
200
            given.
222
201
          </para>
223
 
          <para>
224
 
            Note that since this program will normally run in the
225
 
            initial RAM disk environment, the interface must be an
226
 
            interface which exists at that stage.  Thus, the interface
227
 
            can not be a pseudo-interface such as <quote>br0</quote>
228
 
            or <quote>tun0</quote>; such interfaces will not exist
229
 
            until much later in the boot process, and can not be used
230
 
            by this program.
231
 
          </para>
232
 
          <para>
233
 
            <replaceable>NAME</replaceable> can be the string
234
 
            <quote><literal>none</literal></quote>; this will not use
235
 
            any specific interface, and will not bring up an interface
236
 
            on startup.  This is not recommended, and only meant for
237
 
            advanced users.
238
 
          </para>
239
202
        </listitem>
240
203
      </varlistentry>
241
204
      
252
215
          </para>
253
216
        </listitem>
254
217
      </varlistentry>
255
 
      
 
218
 
256
219
      <varlistentry>
257
220
        <term><option>--seckey=<replaceable
258
221
        >FILE</replaceable></option></term>
275
238
                      xpointer="priority"/>
276
239
        </listitem>
277
240
      </varlistentry>
278
 
      
 
241
 
279
242
      <varlistentry>
280
243
        <term><option>--dh-bits=<replaceable
281
244
        >BITS</replaceable></option></term>
286
249
          </para>
287
250
        </listitem>
288
251
      </varlistentry>
289
 
 
290
 
      <varlistentry>
291
 
        <term><option>--delay=<replaceable
292
 
        >SECONDS</replaceable></option></term>
293
 
        <listitem>
294
 
          <para>
295
 
            After bringing the network interface up, the program waits
296
 
            for the interface to arrive in a <quote>running</quote>
297
 
            state before proceeding.  During this time, the kernel log
298
 
            level will be lowered to reduce clutter on the system
299
 
            console, alleviating any other plugins which might be
300
 
            using the system console.  This option sets the upper
301
 
            limit of seconds to wait.  The default is 2.5 seconds.
302
 
          </para>
303
 
        </listitem>
304
 
      </varlistentry>
305
 
 
306
 
      <varlistentry>
307
 
        <term><option>--retry=<replaceable
308
 
        >SECONDS</replaceable></option></term>
309
 
        <listitem>
310
 
          <para>
311
 
            All Mandos servers are tried repeatedly until a password
312
 
            is received.  This value specifies, in seconds, how long
313
 
            between each successive try <emphasis>for the same
314
 
            server</emphasis>.  The default is 10 seconds.
315
 
          </para>
316
 
        </listitem>
317
 
      </varlistentry>
318
 
 
319
 
      <varlistentry>
320
 
        <term><option>--network-hook-dir=<replaceable
321
 
        >DIR</replaceable></option></term>
322
 
        <listitem>
323
 
          <para>
324
 
            Network hook directory.  The default directory is
325
 
            <quote><filename class="directory"
326
 
            >/lib/mandos/network-hooks.d</filename></quote>.
327
 
          </para>
328
 
        </listitem>
329
 
      </varlistentry>
330
252
      
331
253
      <varlistentry>
332
254
        <term><option>--debug</option></term>
362
284
          </para>
363
285
        </listitem>
364
286
      </varlistentry>
365
 
      
 
287
 
366
288
      <varlistentry>
367
289
        <term><option>--version</option></term>
368
290
        <term><option>-V</option></term>
374
296
      </varlistentry>
375
297
    </variablelist>
376
298
  </refsect1>
377
 
  
 
299
 
378
300
  <refsect1 id="overview">
379
301
    <title>OVERVIEW</title>
380
302
    <xi:include href="../overview.xml"/>
405
327
      server could be found and the password received from it could be
406
328
      successfully decrypted and output on standard output.  The
407
329
      program will exit with a non-zero exit status only if a critical
408
 
      error occurs.  Otherwise, it will forever connect to any
409
 
      discovered <application>Mandos</application> servers, trying to
410
 
      get a decryptable password and print it.
 
330
      error occurs.  Otherwise, it will forever connect to new
 
331
      <application>Mandos</application> servers as they appear, trying
 
332
      to get a decryptable password and print it.
411
333
    </para>
412
334
  </refsect1>
413
335
  
421
343
    </para>
422
344
  </refsect1>
423
345
  
424
 
  <refsect1 id="files">
 
346
  <refsect1 id="file">
425
347
    <title>FILES</title>
426
348
    <variablelist>
427
349
      <varlistentry>
446
368
<!--     <para> -->
447
369
<!--     </para> -->
448
370
<!--   </refsect1> -->
449
 
  
 
371
 
450
372
  <refsect1 id="example">
451
373
    <title>EXAMPLE</title>
452
374
    <para>
488
410
    <informalexample>
489
411
      <para>
490
412
        Run in debug mode, with a custom key, and do not use Zeroconf
491
 
        to locate a server; connect directly to the IPv6 link-local
492
 
        address <quote><systemitem class="ipaddress"
493
 
        >fe80::aede:48ff:fe71:f6f2</systemitem></quote>, port 4711,
494
 
        using interface eth2:
 
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:
495
417
      </para>
496
418
      <para>
497
419
 
498
420
<!-- do not wrap this line -->
499
 
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --connect fe80::aede:48ff:fe71:f6f2:4711 --interface eth2</userinput>
 
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>
500
422
 
501
423
      </para>
502
424
    </informalexample>
503
425
  </refsect1>
504
 
  
 
426
 
505
427
  <refsect1 id="security">
506
428
    <title>SECURITY</title>
507
429
    <para>
527
449
      The only remaining weak point is that someone with physical
528
450
      access to the client hard drive might turn off the client
529
451
      computer, read the OpenPGP keys directly from the hard drive,
530
 
      and communicate with the server.  To safeguard against this, the
531
 
      server is supposed to notice the client disappearing and stop
532
 
      giving out the encrypted data.  Therefore, it is important to
533
 
      set the timeout and checker interval values tightly on the
534
 
      server.  See <citerefentry><refentrytitle
 
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
535
457
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
536
458
    </para>
537
459
    <para>
548
470
      confidential.
549
471
    </para>
550
472
  </refsect1>
551
 
  
 
473
 
552
474
  <refsect1 id="see_also">
553
475
    <title>SEE ALSO</title>
554
476
    <para>
555
 
      <citerefentry><refentrytitle>intro</refentrytitle>
556
 
      <manvolnum>8mandos</manvolnum></citerefentry>,
557
477
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
558
478
      <manvolnum>8</manvolnum></citerefentry>,
559
479
      <citerefentry><refentrytitle>crypttab</refentrytitle>
681
601
      </varlistentry>
682
602
    </variablelist>
683
603
  </refsect1>
 
604
 
684
605
</refentry>
685
 
 
686
606
<!-- Local Variables: -->
687
607
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
688
608
<!-- time-stamp-end: "[\"']>" -->