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