/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release
129 by Teddy Hogeborn
* mandos-clients.conf.xml: Changed all single quotes to double quotes
1
<?xml version="1.0" encoding="UTF-8"?>
24.1.23 by Björn Påhlsson
Added manual pages for:
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
<!ENTITY VERSION "1.0">
171 by Teddy Hogeborn
Renamed "password-request" to "mandos-client".
5
<!ENTITY COMMANDNAME "mandos-client">
6
<!ENTITY TIMESTAMP "2008-09-06">
24.1.23 by Björn Påhlsson
Added manual pages for:
7
]>
8
131 by Teddy Hogeborn
* Makefile: Make all DocBook rules include legalnotice.xml as a
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
24.1.23 by Björn Påhlsson
Added manual pages for:
10
  <refentryinfo>
112 by Teddy Hogeborn
* mandos-clients.conf.xml (/refentry/refentryinfo/title): Changed to
11
    <title>Mandos Manual</title>
129 by Teddy Hogeborn
* mandos-clients.conf.xml: Changed all single quotes to double quotes
12
    <!-- Nwalsh’s docbook scripts use this to generate the footer: -->
112 by Teddy Hogeborn
* mandos-clients.conf.xml (/refentry/refentryinfo/title): Changed to
13
    <productname>Mandos</productname>
24.1.23 by Björn Påhlsson
Added manual pages for:
14
    <productnumber>&VERSION;</productnumber>
111 by Teddy Hogeborn
* mandos-clients.conf.xml (ENTITY TIMESTAMP): New. Automatically
15
    <date>&TIMESTAMP;</date>
24.1.23 by Björn Påhlsson
Added manual pages for:
16
    <authorgroup>
17
      <author>
18
	<firstname>Björn</firstname>
19
	<surname>Påhlsson</surname>
20
	<address>
21
	  <email>belorn@fukt.bsnet.se</email>
22
	</address>
23
      </author>
24
      <author>
25
	<firstname>Teddy</firstname>
26
	<surname>Hogeborn</surname>
27
	<address>
28
	  <email>teddy@fukt.bsnet.se</email>
29
	</address>
30
      </author>
31
    </authorgroup>
32
    <copyright>
33
      <year>2008</year>
128 by Teddy Hogeborn
* plugin-runner.xml (/refentry/refentryinfo/copyright): Split
34
      <holder>Teddy Hogeborn</holder>
35
      <holder>Björn Påhlsson</holder>
24.1.23 by Björn Påhlsson
Added manual pages for:
36
    </copyright>
131 by Teddy Hogeborn
* Makefile: Make all DocBook rules include legalnotice.xml as a
37
    <xi:include href="../legalnotice.xml"/>
24.1.23 by Björn Påhlsson
Added manual pages for:
38
  </refentryinfo>
39
40
  <refmeta>
41
    <refentrytitle>&COMMANDNAME;</refentrytitle>
42
    <manvolnum>8mandos</manvolnum>
43
  </refmeta>
44
  
45
  <refnamediv>
46
    <refname><command>&COMMANDNAME;</command></refname>
47
    <refpurpose>
172 by Teddy Hogeborn
* plugins.d/mandos-client.xml (NAME, OVERVIEW, EXIT STATUS): Improved
48
      Client for <application>Mandos</application>
24.1.23 by Björn Påhlsson
Added manual pages for:
49
    </refpurpose>
50
  </refnamediv>
51
52
  <refsynopsisdiv>
53
    <cmdsynopsis>
54
      <command>&COMMANDNAME;</command>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
55
      <group>
56
	<arg choice="plain"><option>--connect
156 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Improved spelling.
57
	<replaceable>ADDRESS</replaceable><literal>:</literal
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
58
	><replaceable>PORT</replaceable></option></arg>
59
	<arg choice="plain"><option>-c
156 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Improved spelling.
60
	<replaceable>ADDRESS</replaceable><literal>:</literal
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
61
	><replaceable>PORT</replaceable></option></arg>
62
      </group>
63
      <sbr/>
64
      <group>
65
	<arg choice="plain"><option>--interface
66
	<replaceable>NAME</replaceable></option></arg>
67
	<arg choice="plain"><option>-i
68
	<replaceable>NAME</replaceable></option></arg>
69
      </group>
70
      <sbr/>
71
      <group>
72
	<arg choice="plain"><option>--pubkey
73
	<replaceable>FILE</replaceable></option></arg>
74
	<arg choice="plain"><option>-p
75
	<replaceable>FILE</replaceable></option></arg>
76
      </group>
77
      <sbr/>
78
      <group>
79
	<arg choice="plain"><option>--seckey
80
	<replaceable>FILE</replaceable></option></arg>
81
	<arg choice="plain"><option>-s
82
	<replaceable>FILE</replaceable></option></arg>
83
      </group>
84
      <sbr/>
85
      <arg>
86
	<option>--priority <replaceable>STRING</replaceable></option>
87
      </arg>
88
      <sbr/>
89
      <arg>
90
	<option>--dh-bits <replaceable>BITS</replaceable></option>
91
      </arg>
92
      <sbr/>
93
      <arg>
94
	<option>--debug</option>
95
      </arg>
96
    </cmdsynopsis>
97
    <cmdsynopsis>
98
      <command>&COMMANDNAME;</command>
99
      <group choice="req">
129 by Teddy Hogeborn
* mandos-clients.conf.xml: Changed all single quotes to double quotes
100
	<arg choice="plain"><option>--help</option></arg>
101
	<arg choice="plain"><option>-?</option></arg>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
102
      </group>
103
    </cmdsynopsis>
104
    <cmdsynopsis>
105
      <command>&COMMANDNAME;</command>
129 by Teddy Hogeborn
* mandos-clients.conf.xml: Changed all single quotes to double quotes
106
      <arg choice="plain"><option>--usage</option></arg>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
107
    </cmdsynopsis>
108
    <cmdsynopsis>
109
      <command>&COMMANDNAME;</command>
110
      <group choice="req">
129 by Teddy Hogeborn
* mandos-clients.conf.xml: Changed all single quotes to double quotes
111
	<arg choice="plain"><option>--version</option></arg>
112
	<arg choice="plain"><option>-V</option></arg>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
113
      </group>
114
    </cmdsynopsis>
24.1.23 by Björn Påhlsson
Added manual pages for:
115
  </refsynopsisdiv>
116
117
  <refsect1 id="description">
118
    <title>DESCRIPTION</title>
119
    <para>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
120
      <command>&COMMANDNAME;</command> is a client program that
121
      communicates with <citerefentry><refentrytitle
122
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
123
      to get a password.  It uses IPv6 link-local addresses to get
145 by Teddy Hogeborn
* plugins.d/password-request.xml (DESCRIPTION): Improved wording.
124
      network connectivity, Zeroconf to find servers, and TLS with an
125
      OpenPGP key to ensure authenticity and confidentiality.  It
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
126
      keeps running, trying all servers on the network, until it
156 by Teddy Hogeborn
* mandos-clients.conf.xml (OPTIONS): Improved spelling.
127
      receives a satisfactory reply or a TERM signal is received.
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
128
    </para>
129
    <para>
130
      This program is not meant to be run directly; it is really meant
131
      to run as a plugin of the <application>Mandos</application>
132
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
143 by Teddy Hogeborn
* Makefile (mandos.8): Add dependency on "overview.xml" and
133
      <manvolnum>8mandos</manvolnum></citerefentry>, which runs in the
134
      initial <acronym>RAM</acronym> disk environment because it is
135
      specified as a <quote>keyscript</quote> in the <citerefentry>
136
      <refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
137
      </citerefentry> file.
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
138
    </para>
139
  </refsect1>
140
  
141
  <refsect1 id="purpose">
142
    <title>PURPOSE</title>
143
    <para>
144
      The purpose of this is to enable <emphasis>remote and unattended
145
      rebooting</emphasis> of client host computer with an
146
      <emphasis>encrypted root file system</emphasis>.  See <xref
147
      linkend="overview"/> for details.
148
    </para>
149
  </refsect1>
150
  
24.1.55 by Björn Påhlsson
updated some partial manual pages
151
  <refsect1 id="options">
152
    <title>OPTIONS</title>
153
    <para>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
154
      This program is commonly not invoked from the command line; it
155
      is normally started by the <application>Mandos</application>
156
      plugin runner, see <citerefentry><refentrytitle
157
      >plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
158
      </citerefentry>.  Any command line options this program accepts
159
      are therefore normally provided by the plugin runner, and not
160
      directly.
24.1.55 by Björn Påhlsson
updated some partial manual pages
161
    </para>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
162
    
24.1.23 by Björn Påhlsson
Added manual pages for:
163
    <variablelist>
164
      <varlistentry>
127 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
165
	<term><option>--connect=<replaceable
143 by Teddy Hogeborn
* Makefile (mandos.8): Add dependency on "overview.xml" and
166
	>ADDRESS</replaceable><literal>:</literal><replaceable
127 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
167
	>PORT</replaceable></option></term>
168
	<term><option>-c
143 by Teddy Hogeborn
* Makefile (mandos.8): Add dependency on "overview.xml" and
169
	<replaceable>ADDRESS</replaceable><literal>:</literal
127 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
170
	><replaceable>PORT</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
171
	<listitem>
172
	  <para>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
173
	    Do not use Zeroconf to locate servers.  Connect directly
174
	    to only one specified <application>Mandos</application>
175
	    server.  Note that an IPv6 address has colon characters in
176
	    it, so the <emphasis>last</emphasis> colon character is
177
	    assumed to separate the address from the port number.
178
	  </para>
179
	  <para>
143 by Teddy Hogeborn
* Makefile (mandos.8): Add dependency on "overview.xml" and
180
	    This option is normally only useful for testing and
181
	    debugging.
24.1.23 by Björn Påhlsson
Added manual pages for:
182
	  </para>
183
	</listitem>
184
      </varlistentry>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
185
      
24.1.23 by Björn Påhlsson
Added manual pages for:
186
      <varlistentry>
127 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
187
	<term><option>--interface=
188
	<replaceable>NAME</replaceable></option></term>
189
	<term><option>-i
190
	<replaceable>NAME</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
191
	<listitem>
192
	  <para>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
193
	    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>.
24.1.23 by Björn Påhlsson
Added manual pages for:
196
	  </para>
146 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Improved wording.
197
	  <para>
198
	    If the <option>--connect</option> option is used, this
199
	    specifies the interface to use to connect to the address
200
	    given.
201
	  </para>
24.1.23 by Björn Påhlsson
Added manual pages for:
202
	</listitem>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
203
      </varlistentry>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
204
      
24.1.23 by Björn Påhlsson
Added manual pages for:
205
      <varlistentry>
127 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
206
	<term><option>--pubkey=<replaceable
207
	>FILE</replaceable></option></term>
208
	<term><option>-p
209
	<replaceable>FILE</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
210
	<listitem>
211
	  <para>
151 by Teddy Hogeborn
* plugins.d/password-request.xml (SYNOPSYS): Removed "--keydir".
212
	    OpenPGP public key file name.  The default name is
213
	    <quote><filename>/conf/conf.d/mandos/pubkey.txt</filename
214
	    ></quote>.
24.1.23 by Björn Påhlsson
Added manual pages for:
215
	  </para>
216
	</listitem>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
217
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
218
219
      <varlistentry>
127 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
220
	<term><option>--seckey=<replaceable
221
	>FILE</replaceable></option></term>
222
	<term><option>-s
223
	<replaceable>FILE</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
224
	<listitem>
225
	  <para>
151 by Teddy Hogeborn
* plugins.d/password-request.xml (SYNOPSYS): Removed "--keydir".
226
	    OpenPGP secret key file name.  The default name is
227
	    <quote><filename>/conf/conf.d/mandos/seckey.txt</filename
228
	    ></quote>.
24.1.23 by Björn Påhlsson
Added manual pages for:
229
	  </para>
230
	</listitem>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
231
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
232
      
233
      <varlistentry>
127 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
234
	<term><option>--priority=<replaceable
235
	>STRING</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
236
	<listitem>
143 by Teddy Hogeborn
* Makefile (mandos.8): Add dependency on "overview.xml" and
237
	  <xi:include href="../mandos-options.xml"
238
		      xpointer="priority"/>
24.1.23 by Björn Påhlsson
Added manual pages for:
239
	</listitem>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
240
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
241
242
      <varlistentry>
127 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
243
	<term><option>--dh-bits=<replaceable
244
	>BITS</replaceable></option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
245
	<listitem>
246
	  <para>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
247
	    Sets the number of bits to use for the prime number in the
248
	    TLS Diffie-Hellman key exchange.  Default is 1024.
24.1.23 by Björn Påhlsson
Added manual pages for:
249
	  </para>
250
	</listitem>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
251
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
252
      
253
      <varlistentry>
127 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
254
	<term><option>--debug</option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
255
	<listitem>
256
	  <para>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
257
	    Enable debug mode.  This will enable a lot of output to
258
	    standard error about what the program is doing.  The
259
	    program will still perform all other functions normally.
260
	  </para>
261
	  <para>
262
	    It will also enable debug mode in the Avahi and GnuTLS
263
	    libraries, making them print large amounts of debugging
264
	    output.
24.1.23 by Björn Påhlsson
Added manual pages for:
265
	  </para>
266
	</listitem>
267
      </varlistentry>
268
      
269
      <varlistentry>
127 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
270
	<term><option>--help</option></term>
271
	<term><option>-?</option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
272
	<listitem>
273
	  <para>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
274
	    Gives a help message about options and their meanings.
24.1.23 by Björn Påhlsson
Added manual pages for:
275
	  </para>
276
	</listitem>
277
      </varlistentry>
278
      
279
      <varlistentry>
127 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
280
	<term><option>--usage</option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
281
	<listitem>
282
	  <para>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
283
	    Gives a short usage message.
24.1.23 by Björn Påhlsson
Added manual pages for:
284
	  </para>
285
	</listitem>
286
      </varlistentry>
287
288
      <varlistentry>
127 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Make replaceables match
289
	<term><option>--version</option></term>
290
	<term><option>-V</option></term>
24.1.23 by Björn Påhlsson
Added manual pages for:
291
	<listitem>
292
	  <para>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
293
	    Prints the program version.
24.1.23 by Björn Påhlsson
Added manual pages for:
294
	  </para>
295
	</listitem>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
296
      </varlistentry>
24.1.23 by Björn Påhlsson
Added manual pages for:
297
    </variablelist>
298
  </refsect1>
24.1.55 by Björn Påhlsson
updated some partial manual pages
299
143 by Teddy Hogeborn
* Makefile (mandos.8): Add dependency on "overview.xml" and
300
  <refsect1 id="overview">
301
    <title>OVERVIEW</title>
302
    <xi:include href="../overview.xml"/>
303
    <para>
304
      This program is the client part.  It is a plugin started by
305
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
306
      <manvolnum>8mandos</manvolnum></citerefentry> which will run in
307
      an initial <acronym>RAM</acronym> disk environment.
308
    </para>
309
    <para>
310
      This program could, theoretically, be used as a keyscript in
311
      <filename>/etc/crypttab</filename>, but it would then be
144 by Teddy Hogeborn
* plugins.d/password-request.xml (OVERVIEW): Improved wording.
312
      impossible to enter a password for the encrypted root disk at
313
      the console, since this program does not read from the console
172 by Teddy Hogeborn
* plugins.d/mandos-client.xml (NAME, OVERVIEW, EXIT STATUS): Improved
314
      at all.  This is why a separate plugin runner (<citerefentry>
315
      <refentrytitle>plugin-runner</refentrytitle>
316
      <manvolnum>8mandos</manvolnum></citerefentry>) is used to run
317
      both this program and others in in parallel,
318
      <emphasis>one</emphasis> of which will prompt for passwords on
319
      the system console.
143 by Teddy Hogeborn
* Makefile (mandos.8): Add dependency on "overview.xml" and
320
    </para>
321
  </refsect1>
322
  
24.1.55 by Björn Påhlsson
updated some partial manual pages
323
  <refsect1 id="exit_status">
324
    <title>EXIT STATUS</title>
325
    <para>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
326
      This program will exit with a successful (zero) exit status if a
327
      server could be found and the password received from it could be
328
      successfully decrypted and output on standard output.  The
329
      program will exit with a non-zero exit status only if a critical
330
      error occurs.  Otherwise, it will forever connect to new
144 by Teddy Hogeborn
* plugins.d/password-request.xml (OVERVIEW): Improved wording.
331
      <application>Mandos</application> servers as they appear, trying
172 by Teddy Hogeborn
* plugins.d/mandos-client.xml (NAME, OVERVIEW, EXIT STATUS): Improved
332
      to get a decryptable password and print it.
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
333
    </para>
334
  </refsect1>
335
  
143 by Teddy Hogeborn
* Makefile (mandos.8): Add dependency on "overview.xml" and
336
  <refsect1 id="environment">
337
    <title>ENVIRONMENT</title>
338
    <para>
339
      This program does not use any environment variables, not even
340
      the ones provided by <citerefentry><refentrytitle
341
      >cryptsetup</refentrytitle><manvolnum>8</manvolnum>
342
    </citerefentry>.
343
    </para>
344
  </refsect1>
142 by Teddy Hogeborn
* plugins.d/password-request.c (main): Change default GnuTLS priority
345
  
24.1.55 by Björn Påhlsson
updated some partial manual pages
346
  <refsect1 id="file">
347
    <title>FILES</title>
146 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Improved wording.
348
    <variablelist>
349
      <varlistentry>
350
	<term><filename>/conf/conf.d/mandos/pubkey.txt</filename
351
	></term>
352
	<term><filename>/conf/conf.d/mandos/seckey.txt</filename
353
	></term>
354
	<listitem>
355
	  <para>
356
	    OpenPGP public and private key files, in <quote>ASCII
357
	    Armor</quote> format.  These are the default file names,
358
	    they can be changed with the <option>--pubkey</option> and
359
	    <option>--seckey</option> options.
360
	  </para>
361
	</listitem>
362
      </varlistentry>
363
    </variablelist>
118 by Teddy Hogeborn
* mandos-keygen.xml (SYNOPSIS): Fixed tags. Unify short and long
364
  </refsect1>
24.1.55 by Björn Påhlsson
updated some partial manual pages
365
  
146 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Improved wording.
366
<!--   <refsect1 id="bugs"> -->
367
<!--     <title>BUGS</title> -->
368
<!--     <para> -->
369
<!--     </para> -->
370
<!--   </refsect1> -->
24.1.55 by Björn Påhlsson
updated some partial manual pages
371
87 by Teddy Hogeborn
* Makefile: Bug fix: fixed creation of man pages in "plugins.d".
372
  <refsect1 id="example">
373
    <title>EXAMPLE</title>
24.1.55 by Björn Påhlsson
updated some partial manual pages
374
    <para>
146 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Improved wording.
375
      Note that normally, command line options will not be given
376
      directly, but via options for the Mandos <citerefentry
377
      ><refentrytitle>plugin-runner</refentrytitle>
378
      <manvolnum>8mandos</manvolnum></citerefentry>.
24.1.55 by Björn Påhlsson
updated some partial manual pages
379
    </para>
146 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Improved wording.
380
    <informalexample>
381
      <para>
382
	Normal invocation needs no options, if the network interface
383
	is <quote>eth0</quote>:
384
      </para>
385
      <para>
386
	<userinput>&COMMANDNAME;</userinput>
387
      </para>
388
    </informalexample>
389
    <informalexample>
390
      <para>
158 by Teddy Hogeborn
* plugins.d/password-request.xml (EXAMPLE): Improved wording.
391
	Search for Mandos servers (and connect to them) using another
392
	interface:
146 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Improved wording.
393
      </para>
394
      <para>
395
	<!-- do not wrap this line -->
396
	<userinput>&COMMANDNAME; --interface eth1</userinput>
397
      </para>
398
    </informalexample>
399
    <informalexample>
400
      <para>
151 by Teddy Hogeborn
* plugins.d/password-request.xml (SYNOPSYS): Removed "--keydir".
401
	Run in debug mode, and use a custom key:
146 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Improved wording.
402
      </para>
403
      <para>
151 by Teddy Hogeborn
* plugins.d/password-request.xml (SYNOPSYS): Removed "--keydir".
404
405
<!-- do not wrap this line -->
406
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt</userinput>
407
146 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Improved wording.
408
      </para>
409
    </informalexample>
410
    <informalexample>
411
      <para>
151 by Teddy Hogeborn
* plugins.d/password-request.xml (SYNOPSYS): Removed "--keydir".
412
	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"
146 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Improved wording.
415
	>2001:db8:f983:bd0b:30de:ae4a:71f2:f672</systemitem></quote>,
416
	port 4711, using interface eth2:
417
      </para>
418
      <para>
419
420
<!-- do not wrap this line -->
151 by Teddy Hogeborn
* plugins.d/password-request.xml (SYNOPSYS): Removed "--keydir".
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>
146 by Teddy Hogeborn
* plugins.d/password-request.xml (OPTIONS): Improved wording.
422
423
      </para>
424
    </informalexample>
24.1.55 by Björn Påhlsson
updated some partial manual pages
425
  </refsect1>
426
427
  <refsect1 id="security">
428
    <title>SECURITY</title>
429
    <para>
147 by Teddy Hogeborn
* plugins.d/password-request.c (init_gnutls_global): Improved wording
430
      This program is set-uid to root, but will switch back to the
148 by Teddy Hogeborn
* plugins.d/password-request.xml (OVERVIEW): Refer to
431
      original (and presumably non-privileged) user and group after
432
      bringing up the network interface.
147 by Teddy Hogeborn
* plugins.d/password-request.c (init_gnutls_global): Improved wording
433
    </para>
434
    <para>
435
      To use this program for its intended purpose (see <xref
436
      linkend="purpose"/>), the password for the root file system will
437
      have to be given out to be stored in a server computer, after
438
      having been encrypted using an OpenPGP key.  This encrypted data
439
      which will be stored in a server can only be decrypted by the
440
      OpenPGP key, and the data will only be given out to those
441
      clients who can prove they actually have that key.  This key,
442
      however, is stored unencrypted on the client side in its initial
443
      <acronym>RAM</acronym> disk image file system.  This is normally
444
      readable by all, but this is normally fixed during installation
445
      of this program; file permissions are set so that no-one is able
446
      to read that file.
447
    </para>
448
    <para>
449
      The only remaining weak point is that someone with physical
450
      access to the client hard drive might turn off the client
451
      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
457
      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
458
    </para>
459
    <para>
148 by Teddy Hogeborn
* plugins.d/password-request.xml (OVERVIEW): Refer to
460
      It will also help if the checker program on the server is
461
      configured to request something from the client which can not be
462
      spoofed by someone else on the network, unlike unencrypted
463
      <acronym>ICMP</acronym> echo (<quote>ping</quote>) replies.
464
    </para>
465
    <para>
466
      <emphasis>Note</emphasis>: This makes it completely insecure to
467
      have <application >Mandos</application> clients which dual-boot
468
      to another operating system which is <emphasis>not</emphasis>
469
      trusted to keep the initial <acronym>RAM</acronym> disk image
470
      confidential.
24.1.55 by Björn Påhlsson
updated some partial manual pages
471
    </para>
472
  </refsect1>
473
474
  <refsect1 id="see_also">
475
    <title>SEE ALSO</title>
114 by Teddy Hogeborn
* mandos-clients.conf.xml (SEE ALSO): Alphabetized, as per
476
    <para>
148 by Teddy Hogeborn
* plugins.d/password-request.xml (OVERVIEW): Refer to
477
      <citerefentry><refentrytitle>cryptsetup</refentrytitle>
478
      <manvolnum>8</manvolnum></citerefentry>,
479
      <citerefentry><refentrytitle>crypttab</refentrytitle>
480
      <manvolnum>5</manvolnum></citerefentry>,
114 by Teddy Hogeborn
* mandos-clients.conf.xml (SEE ALSO): Alphabetized, as per
481
      <citerefentry><refentrytitle>mandos</refentrytitle>
482
      <manvolnum>8</manvolnum></citerefentry>,
483
      <citerefentry><refentrytitle>password-prompt</refentrytitle>
484
      <manvolnum>8mandos</manvolnum></citerefentry>,
485
      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
486
      <manvolnum>8mandos</manvolnum></citerefentry>
487
    </para>
148 by Teddy Hogeborn
* plugins.d/password-request.xml (OVERVIEW): Refer to
488
    <variablelist>
489
      <varlistentry>
490
	<term>
491
	  <ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
492
	</term>
493
	<listitem>
494
	  <para>
495
	    Zeroconf is the network protocol standard used for finding
496
	    Mandos servers on the local network.
497
	  </para>
498
	</listitem>
499
      </varlistentry>
500
      <varlistentry>
501
	<term>
502
	  <ulink url="http://www.avahi.org/">Avahi</ulink>
503
	</term>
504
      <listitem>
505
	<para>
506
	  Avahi is the library this program calls to find Zeroconf
507
	  services.
508
	</para>
509
      </listitem>
510
      </varlistentry>
511
      <varlistentry>
512
	<term>
513
	  <ulink url="http://www.gnu.org/software/gnutls/"
514
	  >GnuTLS</ulink>
515
	</term>
516
      <listitem>
517
	<para>
518
	  GnuTLS is the library this client uses to implement TLS for
519
	  communicating securely with the server, and at the same time
520
	  send the public OpenPGP key to the server.
521
	</para>
522
      </listitem>
523
      </varlistentry>
524
      <varlistentry>
525
	<term>
526
	  <ulink url="http://www.gnupg.org/related_software/gpgme/"
527
		 >GPGME</ulink>
528
	</term>
529
	<listitem>
530
	  <para>
531
	    GPGME is the library used to decrypt the OpenPGP data sent
532
	    by the server.
533
	  </para>
534
	</listitem>
535
      </varlistentry>
536
      <varlistentry>
537
	<term>
538
	  RFC 4291: <citetitle>IP Version 6 Addressing
539
	  Architecture</citetitle>
540
	</term>
541
	<listitem>
542
	  <variablelist>
543
	    <varlistentry>
544
	      <term>Section 2.2: <citetitle>Text Representation of
545
	      Addresses</citetitle></term>
546
	      <listitem><para/></listitem>
547
	    </varlistentry>
548
	    <varlistentry>
549
	      <term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
550
	      Address</citetitle></term>
551
	      <listitem><para/></listitem>
552
	    </varlistentry>
553
	    <varlistentry>
554
	    <term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
555
	    Addresses</citetitle></term>
556
	    <listitem>
557
	      <para>
558
		This client uses IPv6 link-local addresses, which are
559
		immediately usable since a link-local addresses is
560
		automatically assigned to a network interfaces when it
561
		is brought up.
562
	      </para>
563
	    </listitem>
564
	    </varlistentry>
565
	  </variablelist>
566
	</listitem>
567
      </varlistentry>
568
      <varlistentry>
569
	<term>
570
	  RFC 4346: <citetitle>The Transport Layer Security (TLS)
571
	  Protocol Version 1.1</citetitle>
572
	</term>
573
      <listitem>
574
	<para>
575
	  TLS 1.1 is the protocol implemented by GnuTLS.
576
	</para>
577
      </listitem>
578
      </varlistentry>
579
      <varlistentry>
580
	<term>
581
	  RFC 4880: <citetitle>OpenPGP Message Format</citetitle>
582
	</term>
583
      <listitem>
584
	<para>
585
	  The data received from the server is binary encrypted
586
	  OpenPGP data.
587
	</para>
588
      </listitem>
589
      </varlistentry>
590
      <varlistentry>
591
	<term>
592
	  RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
593
	  Security</citetitle>
594
	</term>
595
      <listitem>
596
	<para>
597
	  This is implemented by GnuTLS and used by this program so
598
	  that OpenPGP keys can be used.
599
	</para>
600
      </listitem>
601
      </varlistentry>
602
    </variablelist>
81 by Teddy Hogeborn
* Makefile (GNUTLS_CFLAGS, GNUTLS_LIBS, AVAHI_CFLAGS, AVAHI_LIBS,
603
  </refsect1>
604
24.1.23 by Björn Påhlsson
Added manual pages for:
605
</refentry>
111 by Teddy Hogeborn
* mandos-clients.conf.xml (ENTITY TIMESTAMP): New. Automatically
606
<!-- Local Variables: -->
607
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
608
<!-- time-stamp-end: "[\"']>" -->
609
<!-- time-stamp-format: "%:y-%02m-%02d" -->
610
<!-- End: -->