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