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