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