54
75
<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>
76
<arg choice='opt'>--connect<arg choice='plain'>IP</arg></arg>
77
<arg choice='opt'>--keydir<arg choice='plain'>KEYDIR</arg></arg>
78
<arg choice='opt'>--interface<arg choice='plain'>INTERFACE</arg></arg>
79
<arg choice='opt'>--pubkey<arg choice='plain'>PUBKEY</arg></arg>
80
<arg choice='opt'>--seckey<arg choice='plain'>SECKEY</arg></arg>
81
<arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>
82
<arg choice='opt'>--dh-bits<arg choice='plain'>BITS</arg></arg>
83
<arg choice='opt'>--debug</arg>
86
<command>&COMMANDNAME;</command>
87
<arg choice='plain'>--help</arg>
90
<command>&COMMANDNAME;</command>
91
<arg choice='plain'>--usage</arg>
94
<command>&COMMANDNAME;</command>
95
<arg choice='plain'>--version</arg>
124
99
<refsect1 id="description">
125
100
<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 servers, and TLS with an
132
OpenPGP key to ensure authenticity and confidentiality. It
133
keeps running, trying all servers on the network, until it
134
receives a satisfactory reply or a TERM signal is recieved.
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.
102
<command>&COMMANDNAME;</command> is a mandos plugin that works
103
like a client program that through avahi detects mandos servers,
104
sets up a gnutls connect and request a encrypted password. Any
105
passwords given is automaticly decrypted and passed to
158
110
<refsect1 id="options">
159
111
<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
113
Commonly not invoked as command lines but from configuration
114
file of plugin runner.
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>.
221
If the <option>--connect</option> option is used, this
222
specifies the interface to use to connect to the address
229
<term><option>--pubkey=<replaceable
230
>FILE</replaceable></option></term>
232
<replaceable>FILE</replaceable></option></term>
235
OpenPGP public key file base name. This will be combined
236
with the directory from the <option>--keydir</option>
237
option to form an absolute file name. The default name is
238
<quote><literal>pubkey.txt</literal></quote>.
244
<term><option>--seckey=<replaceable
245
>FILE</replaceable></option></term>
247
<replaceable>FILE</replaceable></option></term>
250
OpenPGP secret key file base name. This will be combined
251
with the directory from the <option>--keydir</option>
252
option to form an absolute file name. The default name is
253
<quote><literal>seckey.txt</literal></quote>.
259
<term><option>--priority=<replaceable
260
>STRING</replaceable></option></term>
262
<xi:include href="../mandos-options.xml"
263
xpointer="priority"/>
268
<term><option>--dh-bits=<replaceable
269
>BITS</replaceable></option></term>
272
Sets the number of bits to use for the prime number in the
273
TLS Diffie-Hellman key exchange. Default is 1024.
279
<term><option>--debug</option></term>
282
Enable debug mode. This will enable a lot of output to
283
standard error about what the program is doing. The
284
program will still perform all other functions normally.
287
It will also enable debug mode in the Avahi and GnuTLS
288
libraries, making them print large amounts of debugging
295
<term><option>--help</option></term>
296
<term><option>-?</option></term>
299
Gives a help message about options and their meanings.
305
<term><option>--usage</option></term>
308
Gives a short usage message.
314
<term><option>--version</option></term>
315
<term><option>-V</option></term>
318
Prints the program version.
119
<term><literal>-c</literal>, <literal>--connect=<replaceable>
120
IP</replaceable></literal></term>
123
Connect directly to a sepcified mandos server
129
<term><literal>-d</literal>, <literal>--keydir=<replaceable>
130
KEYDIR</replaceable></literal></term>
133
Directory where the openpgp keyring is
139
<term><literal>-i</literal>, <literal>--interface=
140
<replaceable>INTERFACE</replaceable></literal></term>
143
Interface that Avahi will conntect through
149
<term><literal>-p</literal>, <literal>--pubkey=<replaceable>
150
PUBKEY</replaceable></literal></term>
153
Public openpgp key for gnutls authentication
159
<term><literal>-s</literal>, <literal>--seckey=<replaceable>
160
SECKEY</replaceable></literal></term>
163
Secret openpgp key for gnutls authentication
169
<term><literal>--priority=<replaceable>PRIORITY</replaceable>
179
<term><literal>--dh-bits=<replaceable>BITS</replaceable>
183
dh-bits to use in gnutls communication
189
<term><literal>--debug</literal></term>
198
<term><literal>-?</literal>, <literal>--help</literal></term>
207
<term><literal>--usage</literal></term>
210
Gives a short usage message
216
<term><literal>-V</literal>, <literal>--version</literal></term>
219
Prints the program version
325
<refsect1 id="overview">
326
<title>OVERVIEW</title>
327
<xi:include href="../overview.xml"/>
329
This program is the client part. It is a plugin started by
330
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
331
<manvolnum>8mandos</manvolnum></citerefentry> which will run in
332
an initial <acronym>RAM</acronym> disk environment.
335
This program could, theoretically, be used as a keyscript in
336
<filename>/etc/crypttab</filename>, but it would then be
337
impossible to enter a password for the encrypted root disk at
338
the console, since this program does not read from the console
339
at all. This is why a separate plugin does that, which will be
340
run in parallell to this one by the plugin runner.
344
226
<refsect1 id="exit_status">
345
227
<title>EXIT STATUS</title>
347
This program will exit with a successful (zero) exit status if a
348
server could be found and the password received from it could be
349
successfully decrypted and output on standard output. The
350
program will exit with a non-zero exit status only if a critical
351
error occurs. Otherwise, it will forever connect to new
352
<application>Mandos</application> servers as they appear, trying
353
to get a decryptable password.
357
<refsect1 id="environment">
358
<title>ENVIRONMENT</title>
360
This program does not use any environment variables, not even
361
the ones provided by <citerefentry><refentrytitle
362
>cryptsetup</refentrytitle><manvolnum>8</manvolnum>
367
232
<refsect1 id="file">
368
233
<title>FILES</title>
371
<term><filename>/conf/conf.d/mandos/pubkey.txt</filename
373
<term><filename>/conf/conf.d/mandos/seckey.txt</filename
377
OpenPGP public and private key files, in <quote>ASCII
378
Armor</quote> format. These are the default file names,
379
they can be changed with the <option>--pubkey</option> and
380
<option>--seckey</option> options.
238
<refsect1 id="notes">
387
<!-- <refsect1 id="bugs"> -->
388
<!-- <title>BUGS</title> -->
393
<refsect1 id="example">
394
<title>EXAMPLE</title>
396
Note that normally, command line options will not be given
397
directly, but via options for the Mandos <citerefentry
398
><refentrytitle>plugin-runner</refentrytitle>
399
<manvolnum>8mandos</manvolnum></citerefentry>.
403
Normal invocation needs no options, if the network interface
404
is <quote>eth0</quote>:
407
<userinput>&COMMANDNAME;</userinput>
412
Search for Mandos servers on another interface:
415
<!-- do not wrap this line -->
416
<userinput>&COMMANDNAME; --interface eth1</userinput>
421
Run in debug mode, and use a custom key directory:
424
<!-- do not wrap this line -->
425
<userinput>&COMMANDNAME; --debug --keydir keydir</userinput>
430
Run in debug mode, with a custom key directory, and do not use
431
Zeroconf to locate a server; connect directly to the IPv6
432
address <quote><systemitem class="ipaddress"
433
>2001:db8:f983:bd0b:30de:ae4a:71f2:f672</systemitem></quote>,
434
port 4711, using interface eth2:
438
<!-- do not wrap this line -->
439
<userinput>&COMMANDNAME; --debug --keydir keydir --connect 2001:db8:f983:bd0b:30de:ae4a:71f2:f672:4711 --interface eth2</userinput>
250
<refsect1 id="examples">
251
<title>EXAMPLES</title>
445
256
<refsect1 id="security">