/mandos/trunk

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