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