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