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