1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
<!ENTITY VERSION "1.0">
5
<!ENTITY COMMANDNAME "password-request">
6
<!ENTITY TIMESTAMP "2008-09-03">
9
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
<title>Mandos Manual</title>
12
<!-- Nwalsh’s docbook scripts use this to generate the footer: -->
13
<productname>Mandos</productname>
14
<productnumber>&VERSION;</productnumber>
15
<date>&TIMESTAMP;</date>
18
<firstname>Björn</firstname>
19
<surname>Påhlsson</surname>
21
<email>belorn@fukt.bsnet.se</email>
25
<firstname>Teddy</firstname>
26
<surname>Hogeborn</surname>
28
<email>teddy@fukt.bsnet.se</email>
34
<holder>Teddy Hogeborn</holder>
35
<holder>Björn Påhlsson</holder>
37
<xi:include href="../legalnotice.xml"/>
41
<refentrytitle>&COMMANDNAME;</refentrytitle>
42
<manvolnum>8mandos</manvolnum>
46
<refname><command>&COMMANDNAME;</command></refname>
54
<command>&COMMANDNAME;</command>
56
<arg choice="plain"><option>--connect
57
<replaceable>IPADDR</replaceable><literal>:</literal
58
><replaceable>PORT</replaceable></option></arg>
59
<arg choice="plain"><option>-c
60
<replaceable>IPADDR</replaceable><literal>:</literal
61
><replaceable>PORT</replaceable></option></arg>
65
<arg choice="plain"><option>--keydir
66
<replaceable>DIRECTORY</replaceable></option></arg>
67
<arg choice="plain"><option>-d
68
<replaceable>DIRECTORY</replaceable></option></arg>
72
<arg choice="plain"><option>--interface
73
<replaceable>NAME</replaceable></option></arg>
74
<arg choice="plain"><option>-i
75
<replaceable>NAME</replaceable></option></arg>
79
<arg choice="plain"><option>--pubkey
80
<replaceable>FILE</replaceable></option></arg>
81
<arg choice="plain"><option>-p
82
<replaceable>FILE</replaceable></option></arg>
86
<arg choice="plain"><option>--seckey
87
<replaceable>FILE</replaceable></option></arg>
88
<arg choice="plain"><option>-s
89
<replaceable>FILE</replaceable></option></arg>
93
<option>--priority <replaceable>STRING</replaceable></option>
97
<option>--dh-bits <replaceable>BITS</replaceable></option>
101
<option>--debug</option>
105
<command>&COMMANDNAME;</command>
107
<arg choice="plain"><option>--help</option></arg>
108
<arg choice="plain"><option>-?</option></arg>
112
<command>&COMMANDNAME;</command>
113
<arg choice="plain"><option>--usage</option></arg>
116
<command>&COMMANDNAME;</command>
118
<arg choice="plain"><option>--version</option></arg>
119
<arg choice="plain"><option>-V</option></arg>
124
<refsect1 id="description">
125
<title>DESCRIPTION</title>
127
<command>&COMMANDNAME;</command> is a client program that
128
communicates with <citerefentry><refentrytitle
129
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
130
to get a password. It uses IPv6 link-local addresses to get
131
network connectivity, Zeroconf to find the server, and TLS with
132
an OpenPGP key to ensure authenticity and confidentiality. It
133
keeps running, trying all servers on the network, until it
134
receives a satisfactory reply.
137
This program is not meant to be run directly; it is really meant
138
to run as a plugin of the <application>Mandos</application>
139
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
140
<manvolnum>8mandos</manvolnum></citerefentry>, which runs in the
141
initial <acronym>RAM</acronym> disk environment because it is
142
specified as a <quote>keyscript</quote> in the <citerefentry>
143
<refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
144
</citerefentry> file.
148
<refsect1 id="purpose">
149
<title>PURPOSE</title>
151
The purpose of this is to enable <emphasis>remote and unattended
152
rebooting</emphasis> of client host computer with an
153
<emphasis>encrypted root file system</emphasis>. See <xref
154
linkend="overview"/> for details.
158
<refsect1 id="options">
159
<title>OPTIONS</title>
161
This program is commonly not invoked from the command line; it
162
is normally started by the <application>Mandos</application>
163
plugin runner, see <citerefentry><refentrytitle
164
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
165
</citerefentry>. Any command line options this program accepts
166
are therefore normally provided by the plugin runner, and not
172
<term><option>--connect=<replaceable
173
>ADDRESS</replaceable><literal>:</literal><replaceable
174
>PORT</replaceable></option></term>
176
<replaceable>ADDRESS</replaceable><literal>:</literal
177
><replaceable>PORT</replaceable></option></term>
180
Do not use Zeroconf to locate servers. Connect directly
181
to only one specified <application>Mandos</application>
182
server. Note that an IPv6 address has colon characters in
183
it, so the <emphasis>last</emphasis> colon character is
184
assumed to separate the address from the port number.
187
This option is normally only useful for testing and
194
<term><option>--keydir=<replaceable
195
>DIRECTORY</replaceable></option></term>
197
<replaceable>DIRECTORY</replaceable></option></term>
200
Directory to read the OpenPGP key files
201
<filename>pubkey.txt</filename> and
202
<filename>seckey.txt</filename> from. The default is
203
<filename>/conf/conf.d/mandos</filename> (in the initial
204
<acronym>RAM</acronym> disk environment).
210
<term><option>--interface=
211
<replaceable>NAME</replaceable></option></term>
213
<replaceable>NAME</replaceable></option></term>
216
Network interface that will be brought up and scanned for
217
Mandos servers to connect to. The default it
218
<quote><literal>eth0</literal></quote>.
224
<term><option>--pubkey=<replaceable
225
>FILE</replaceable></option></term>
227
<replaceable>FILE</replaceable></option></term>
230
OpenPGP public key file base name. This will be combined
231
with the directory from the <option>--keydir</option>
232
option to form an absolute file name. The default name is
233
<quote><literal>pubkey.txt</literal></quote>.
239
<term><option>--seckey=<replaceable
240
>FILE</replaceable></option></term>
242
<replaceable>FILE</replaceable></option></term>
245
OpenPGP secret key file base name. This will be combined
246
with the directory from the <option>--keydir</option>
247
option to form an absolute file name. The default name is
248
<quote><literal>seckey.txt</literal></quote>.
254
<term><option>--priority=<replaceable
255
>STRING</replaceable></option></term>
257
<xi:include href="../mandos-options.xml"
258
xpointer="priority"/>
263
<term><option>--dh-bits=<replaceable
264
>BITS</replaceable></option></term>
267
Sets the number of bits to use for the prime number in the
268
TLS Diffie-Hellman key exchange. Default is 1024.
274
<term><option>--debug</option></term>
277
Enable debug mode. This will enable a lot of output to
278
standard error about what the program is doing. The
279
program will still perform all other functions normally.
282
It will also enable debug mode in the Avahi and GnuTLS
283
libraries, making them print large amounts of debugging
290
<term><option>--help</option></term>
291
<term><option>-?</option></term>
294
Gives a help message about options and their meanings.
300
<term><option>--usage</option></term>
303
Gives a short usage message.
309
<term><option>--version</option></term>
310
<term><option>-V</option></term>
313
Prints the program version.
320
<refsect1 id="overview">
321
<title>OVERVIEW</title>
322
<xi:include href="../overview.xml"/>
324
This program is the client part. It is a plugin started by
325
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
326
<manvolnum>8mandos</manvolnum></citerefentry> which will run in
327
an initial <acronym>RAM</acronym> disk environment.
330
This program could, theoretically, be used as a keyscript in
331
<filename>/etc/crypttab</filename>, but it would then be
332
impossible to enter a password for the encrypted root disk at
333
the console, since this program does not read from the console
334
at all. This is why a separate plugin does that, which will be
335
run in parallell to this one by the plugin runner.
339
<refsect1 id="exit_status">
340
<title>EXIT STATUS</title>
342
This program will exit with a successful (zero) exit status if a
343
server could be found and the password received from it could be
344
successfully decrypted and output on standard output. The
345
program will exit with a non-zero exit status only if a critical
346
error occurs. Otherwise, it will forever connect to new
347
<application>Mandos</application> servers as they appear, trying
348
to get a decryptable password.
352
<refsect1 id="environment">
353
<title>ENVIRONMENT</title>
355
This program does not use any environment variables, not even
356
the ones provided by <citerefentry><refentrytitle
357
>cryptsetup</refentrytitle><manvolnum>8</manvolnum>
374
<refsect1 id="example">
375
<title>EXAMPLE</title>
380
<refsect1 id="security">
381
<title>SECURITY</title>
386
<refsect1 id="see_also">
387
<title>SEE ALSO</title>
389
<citerefentry><refentrytitle>mandos</refentrytitle>
390
<manvolnum>8</manvolnum></citerefentry>,
391
<citerefentry><refentrytitle>password-prompt</refentrytitle>
392
<manvolnum>8mandos</manvolnum></citerefentry>,
393
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
394
<manvolnum>8mandos</manvolnum></citerefentry>
398
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
402
<ulink url="http://www.avahi.org/">Avahi</ulink>
407
url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>
412
url="http://www.gnupg.org/related_software/gpgme/"
417
<citation>RFC 4880: <citetitle>OpenPGP Message
418
Format</citetitle></citation>
422
<citation>RFC 5081: <citetitle>Using OpenPGP Keys for
423
Transport Layer Security</citetitle></citation>
427
<citation>RFC 4291: <citetitle>IP Version 6 Addressing
428
Architecture</citetitle>, section 2.5.6, Link-Local IPv6
429
Unicast Addresses</citation>
435
<!-- Local Variables: -->
436
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
437
<!-- time-stamp-end: "[\"']>" -->
438
<!-- time-stamp-format: "%:y-%02m-%02d" -->