To get this branch, use:
bzr branch
http://bzr.recompile.se/loggerhead/mandos/release
« back to all changes in this revision
Viewing changes to plugins.d/mandos-client.xml
- browse files at revision 237.25.6
- compare with another revision
- download diff
- download tarball
- view history from revision 237.25.6
- Committer: Teddy Hogeborn
- Date: 2015-07-06 20:09:47 UTC
- mto: (237.7.307 trunk)
- mto: This revision was merged to the branch mainline in revision 325.
- Revision ID: teddy@recompile.se-20150706200947-w21u4eq74efgl6r5
Fix minor bugs and typos and add some more debug output.
* Makefile (install-client-nokey): Create plugin-helpers directory and
the mandos-client-iprouteadddel
helper program.
* initramfs-tools-hook (PLUGINHELPERDIR): Fix typo.
* plugins.d/mandos-client.c: Change terminology; routes are "deleted",
not "removed". All occurences changed.
(add_remove_local_route): Renamed to "add_delete_local_route". All
callers changed. Also pass "--debug" flag
to helper if in debug mode.
(add_local_route): Add debugging output.
(remove_local_route): Renamed to "delete_local_route". All callers
changed. Also pass "--debug" flag to helper
if in debug mode.
(start_mandos_communication): Add debug output when adding route.
* Makefile (install-client-nokey): Create plugin-helpers directory and
the mandos-client-iprouteadddel
helper program.
* initramfs-tools-hook (PLUGINHELPERDIR): Fix typo.
* plugins.d/mandos-client.c: Change terminology; routes are "deleted",
not "removed". All occurences changed.
(add_remove_local_route): Renamed to "add_delete_local_route". All
callers changed. Also pass "--debug" flag
to helper if in debug mode.
(add_local_route): Add debugging output.
(remove_local_route): Renamed to "delete_local_route". All callers
changed. Also pass "--debug" flag to helper
if in debug mode.
(start_mandos_communication): Add debug output when adding route.
- files added:
- .bzr-builddeb
- debian
- debian/po
- debian/source
- debian/upstream
- network-hooks.d
- plugin-helpers
- files renamed:
- server.py => mandos
- server.conf => mandos.conf
- plugbasedclient.c => plugin-runner.c
- plugins.d/mandosclient.c => plugins.d/mandos-client.c
- plugins.d/passprompt.c => plugins.d/password-prompt.c
- files modified:
- Makefile
added
removed
plugins.d/mandos-client.xml
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 COMMANDNAME "mandos-client">
5
<!ENTITY TIMESTAMP "2015-06-29">
6
<!ENTITY % common SYSTEM "../common.ent">
7
%common;
8
]>
9
10
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
11
<refentryinfo>
12
<title>Mandos Manual</title>
13
<!-- NWalsh’s docbook scripts use this to generate the footer: -->
14
<productname>Mandos</productname>
15
<productnumber>&version;</productnumber>
16
<date>&TIMESTAMP;</date>
17
<authorgroup>
18
<author>
19
<firstname>Björn</firstname>
20
<surname>Påhlsson</surname>
21
<address>
22
<email>belorn@recompile.se</email>
23
</address>
24
</author>
25
<author>
26
<firstname>Teddy</firstname>
27
<surname>Hogeborn</surname>
28
<address>
29
<email>teddy@recompile.se</email>
30
</address>
31
</author>
32
</authorgroup>
33
<copyright>
34
<year>2008</year>
35
<year>2009</year>
36
<year>2012</year>
37
<year>2013</year>
38
<year>2014</year>
39
<year>2015</year>
40
<holder>Teddy Hogeborn</holder>
41
<holder>Björn Påhlsson</holder>
42
</copyright>
43
<xi:include href="../legalnotice.xml"/>
44
</refentryinfo>
45
46
<refmeta>
47
<refentrytitle>&COMMANDNAME;</refentrytitle>
48
<manvolnum>8mandos</manvolnum>
49
</refmeta>
50
51
<refnamediv>
52
<refname><command>&COMMANDNAME;</command></refname>
53
<refpurpose>
54
Client for <application>Mandos</application>
55
</refpurpose>
56
</refnamediv>
57
58
<refsynopsisdiv>
59
<cmdsynopsis>
60
<command>&COMMANDNAME;</command>
61
<group>
62
<arg choice="plain"><option>--connect
63
<replaceable>ADDRESS</replaceable><literal>:</literal
64
><replaceable>PORT</replaceable></option></arg>
65
<arg choice="plain"><option>-c
66
<replaceable>ADDRESS</replaceable><literal>:</literal
67
><replaceable>PORT</replaceable></option></arg>
68
</group>
69
<sbr/>
70
<group rep='repeat'>
71
<arg choice="plain"><option>--interface
72
<replaceable>NAME</replaceable><arg rep='repeat'
73
>,<replaceable>NAME</replaceable></arg></option></arg>
74
<arg choice="plain"><option>-i <replaceable>NAME</replaceable
75
><arg rep='repeat'>,<replaceable>NAME</replaceable></arg
76
></option></arg>
77
</group>
78
<sbr/>
79
<group>
80
<arg choice="plain"><option>--pubkey
81
<replaceable>FILE</replaceable></option></arg>
82
<arg choice="plain"><option>-p
83
<replaceable>FILE</replaceable></option></arg>
84
</group>
85
<sbr/>
86
<group>
87
<arg choice="plain"><option>--seckey
88
<replaceable>FILE</replaceable></option></arg>
89
<arg choice="plain"><option>-s
90
<replaceable>FILE</replaceable></option></arg>
91
</group>
92
<sbr/>
93
<arg>
94
<option>--priority <replaceable>STRING</replaceable></option>
95
</arg>
96
<sbr/>
97
<arg>
98
<option>--dh-bits <replaceable>BITS</replaceable></option>
99
</arg>
100
<sbr/>
101
<arg>
102
<option>--delay <replaceable>SECONDS</replaceable></option>
103
</arg>
104
<sbr/>
105
<arg>
106
<option>--retry <replaceable>SECONDS</replaceable></option>
107
</arg>
108
<sbr/>
109
<arg>
110
<option>--network-hook-dir
111
<replaceable>DIR</replaceable></option>
112
</arg>
113
<sbr/>
114
<arg>
115
<option>--debug</option>
116
</arg>
117
</cmdsynopsis>
118
<cmdsynopsis>
119
<command>&COMMANDNAME;</command>
120
<group choice="req">
121
<arg choice="plain"><option>--help</option></arg>
122
<arg choice="plain"><option>-?</option></arg>
123
</group>
124
</cmdsynopsis>
125
<cmdsynopsis>
126
<command>&COMMANDNAME;</command>
127
<arg choice="plain"><option>--usage</option></arg>
128
</cmdsynopsis>
129
<cmdsynopsis>
130
<command>&COMMANDNAME;</command>
131
<group choice="req">
132
<arg choice="plain"><option>--version</option></arg>
133
<arg choice="plain"><option>-V</option></arg>
134
</group>
135
</cmdsynopsis>
136
</refsynopsisdiv>
137
138
<refsect1 id="description">
139
<title>DESCRIPTION</title>
140
<para>
141
<command>&COMMANDNAME;</command> is a client program that
142
communicates with <citerefentry><refentrytitle
143
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
144
to get a password. In slightly more detail, this client program
145
brings up network interfaces, uses the interfaces’ IPv6
146
link-local addresses to get network connectivity, uses Zeroconf
147
to find servers on the local network, and communicates with
148
servers using TLS with an OpenPGP key to ensure authenticity and
149
confidentiality. This client program keeps running, trying all
150
servers on the network, until it receives a satisfactory reply
151
or a TERM signal. After all servers have been tried, all
152
servers are periodically retried. If no servers are found it
153
will wait indefinitely for new servers to appear.
154
</para>
155
<para>
156
The network interfaces are selected like this: If any interfaces
157
are specified using the <option>--interface</option> option,
158
those interface are used. Otherwise,
159
<command>&COMMANDNAME;</command> will use all interfaces that
160
are not loopback interfaces, are not point-to-point interfaces,
161
are capable of broadcasting and do not have the NOARP flag (see
162
<citerefentry><refentrytitle>netdevice</refentrytitle>
163
<manvolnum>7</manvolnum></citerefentry>). (If the
164
<option>--connect</option> option is used, point-to-point
165
interfaces and non-broadcast interfaces are accepted.) If any
166
used interfaces are not up and running, they are first taken up
167
(and later taken down again on program exit).
168
</para>
169
<para>
170
Before network interfaces are selected, all <quote>network
171
hooks</quote> are run; see <xref linkend="network-hooks"/>.
172
</para>
173
<para>
174
This program is not meant to be run directly; it is really meant
175
to run as a plugin of the <application>Mandos</application>
176
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
177
<manvolnum>8mandos</manvolnum></citerefentry>, which runs in the
178
initial <acronym>RAM</acronym> disk environment because it is
179
specified as a <quote>keyscript</quote> in the <citerefentry>
180
<refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum>
181
</citerefentry> file.
182
</para>
183
</refsect1>
184
185
<refsect1 id="purpose">
186
<title>PURPOSE</title>
187
<para>
188
The purpose of this is to enable <emphasis>remote and unattended
189
rebooting</emphasis> of client host computer with an
190
<emphasis>encrypted root file system</emphasis>. See <xref
191
linkend="overview"/> for details.
192
</para>
193
</refsect1>
194
195
<refsect1 id="options">
196
<title>OPTIONS</title>
197
<para>
198
This program is commonly not invoked from the command line; it
199
is normally started by the <application>Mandos</application>
200
plugin runner, see <citerefentry><refentrytitle
201
>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
202
</citerefentry>. Any command line options this program accepts
203
are therefore normally provided by the plugin runner, and not
204
directly.
205
</para>
206
207
<variablelist>
208
<varlistentry>
209
<term><option>--connect=<replaceable
210
>ADDRESS</replaceable><literal>:</literal><replaceable
211
>PORT</replaceable></option></term>
212
<term><option>-c
213
<replaceable>ADDRESS</replaceable><literal>:</literal
214
><replaceable>PORT</replaceable></option></term>
215
<listitem>
216
<para>
217
Do not use Zeroconf to locate servers. Connect directly
218
to only one specified <application>Mandos</application>
219
server. Note that an IPv6 address has colon characters in
220
it, so the <emphasis>last</emphasis> colon character is
221
assumed to separate the address from the port number.
222
</para>
223
<para>
224
Normally, Zeroconf would be used to locate Mandos servers,
225
in which case this option would only be used when testing
226
and debugging.
227
</para>
228
</listitem>
229
</varlistentry>
230
231
<varlistentry>
232
<term><option>--interface=<replaceable
233
>NAME</replaceable><arg rep='repeat'>,<replaceable
234
>NAME</replaceable></arg></option></term>
235
<term><option>-i
236
<replaceable>NAME</replaceable><arg rep='repeat'>,<replaceable
237
>NAME</replaceable></arg></option></term>
238
<listitem>
239
<para>
240
Comma separated list of network interfaces that will be
241
brought up and scanned for Mandos servers to connect to.
242
The default is the empty string, which will automatically
243
use all appropriate interfaces.
244
</para>
245
<para>
246
If the <option>--connect</option> option is used, and
247
exactly one interface name is specified (except
248
<quote><literal>none</literal></quote>), this specifies
249
the interface to use to connect to the address given.
250
</para>
251
<para>
252
Note that since this program will normally run in the
253
initial RAM disk environment, the interface must be an
254
interface which exists at that stage. Thus, the interface
255
can normally not be a pseudo-interface such as
256
<quote>br0</quote> or <quote>tun0</quote>; such interfaces
257
will not exist until much later in the boot process, and
258
can not be used by this program, unless created by a
259
<quote>network hook</quote> — see <xref
260
linkend="network-hooks"/>.
261
</para>
262
<para>
263
<replaceable>NAME</replaceable> can be the string
264
<quote><literal>none</literal></quote>; this will make
265
<command>&COMMANDNAME;</command> only bring up interfaces
266
specified <emphasis>before</emphasis> this string. This
267
is not recommended, and only meant for advanced users.
268
</para>
269
</listitem>
270
</varlistentry>
271
272
<varlistentry>
273
<term><option>--pubkey=<replaceable
274
>FILE</replaceable></option></term>
275
<term><option>-p
276
<replaceable>FILE</replaceable></option></term>
277
<listitem>
278
<para>
279
OpenPGP public key file name. The default name is
280
<quote><filename>/conf/conf.d/mandos/pubkey.txt</filename
281
></quote>.
282
</para>
283
</listitem>
284
</varlistentry>
285
286
<varlistentry>
287
<term><option>--seckey=<replaceable
288
>FILE</replaceable></option></term>
289
<term><option>-s
290
<replaceable>FILE</replaceable></option></term>
291
<listitem>
292
<para>
293
OpenPGP secret key file name. The default name is
294
<quote><filename>/conf/conf.d/mandos/seckey.txt</filename
295
></quote>.
296
</para>
297
</listitem>
298
</varlistentry>
299
300
<varlistentry>
301
<term><option>--priority=<replaceable
302
>STRING</replaceable></option></term>
303
<listitem>
304
<xi:include href="../mandos-options.xml"
305
xpointer="priority"/>
306
</listitem>
307
</varlistentry>
308
309
<varlistentry>
310
<term><option>--dh-bits=<replaceable
311
>BITS</replaceable></option></term>
312
<listitem>
313
<para>
314
Sets the number of bits to use for the prime number in the
315
TLS Diffie-Hellman key exchange. Default is 1024.
316
</para>
317
</listitem>
318
</varlistentry>
319
320
<varlistentry>
321
<term><option>--delay=<replaceable
322
>SECONDS</replaceable></option></term>
323
<listitem>
324
<para>
325
After bringing a network interface up, the program waits
326
for the interface to arrive in a <quote>running</quote>
327
state before proceeding. During this time, the kernel log
328
level will be lowered to reduce clutter on the system
329
console, alleviating any other plugins which might be
330
using the system console. This option sets the upper
331
limit of seconds to wait. The default is 2.5 seconds.
332
</para>
333
</listitem>
334
</varlistentry>
335
336
<varlistentry>
337
<term><option>--retry=<replaceable
338
>SECONDS</replaceable></option></term>
339
<listitem>
340
<para>
341
All Mandos servers are tried repeatedly until a password
342
is received. This value specifies, in seconds, how long
343
between each successive try <emphasis>for the same
344
server</emphasis>. The default is 10 seconds.
345
</para>
346
</listitem>
347
</varlistentry>
348
349
<varlistentry>
350
<term><option>--network-hook-dir=<replaceable
351
>DIR</replaceable></option></term>
352
<listitem>
353
<para>
354
Network hook directory. The default directory is
355
<quote><filename class="directory"
356
>/lib/mandos/network-hooks.d</filename></quote>.
357
</para>
358
</listitem>
359
</varlistentry>
360
361
<varlistentry>
362
<term><option>--debug</option></term>
363
<listitem>
364
<para>
365
Enable debug mode. This will enable a lot of output to
366
standard error about what the program is doing. The
367
program will still perform all other functions normally.
368
</para>
369
<para>
370
It will also enable debug mode in the Avahi and GnuTLS
371
libraries, making them print large amounts of debugging
372
output.
373
</para>
374
</listitem>
375
</varlistentry>
376
377
<varlistentry>
378
<term><option>--help</option></term>
379
<term><option>-?</option></term>
380
<listitem>
381
<para>
382
Gives a help message about options and their meanings.
383
</para>
384
</listitem>
385
</varlistentry>
386
387
<varlistentry>
388
<term><option>--usage</option></term>
389
<listitem>
390
<para>
391
Gives a short usage message.
392
</para>
393
</listitem>
394
</varlistentry>
395
396
<varlistentry>
397
<term><option>--version</option></term>
398
<term><option>-V</option></term>
399
<listitem>
400
<para>
401
Prints the program version.
402
</para>
403
</listitem>
404
</varlistentry>
405
</variablelist>
406
</refsect1>
407
408
<refsect1 id="overview">
409
<title>OVERVIEW</title>
410
<xi:include href="../overview.xml"/>
411
<para>
412
This program is the client part. It is a plugin started by
413
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
414
<manvolnum>8mandos</manvolnum></citerefentry> which will run in
415
an initial <acronym>RAM</acronym> disk environment.
416
</para>
417
<para>
418
This program could, theoretically, be used as a keyscript in
419
<filename>/etc/crypttab</filename>, but it would then be
420
impossible to enter a password for the encrypted root disk at
421
the console, since this program does not read from the console
422
at all. This is why a separate plugin runner (<citerefentry>
423
<refentrytitle>plugin-runner</refentrytitle>
424
<manvolnum>8mandos</manvolnum></citerefentry>) is used to run
425
both this program and others in in parallel,
426
<emphasis>one</emphasis> of which (<citerefentry>
427
<refentrytitle>password-prompt</refentrytitle>
428
<manvolnum>8mandos</manvolnum></citerefentry>) will prompt for
429
passwords on the system console.
430
</para>
431
</refsect1>
432
433
<refsect1 id="exit_status">
434
<title>EXIT STATUS</title>
435
<para>
436
This program will exit with a successful (zero) exit status if a
437
server could be found and the password received from it could be
438
successfully decrypted and output on standard output. The
439
program will exit with a non-zero exit status only if a critical
440
error occurs. Otherwise, it will forever connect to any
441
discovered <application>Mandos</application> servers, trying to
442
get a decryptable password and print it.
443
</para>
444
</refsect1>
445
446
<refsect1 id="environment">
447
<title>ENVIRONMENT</title>
448
<variablelist>
449
<varlistentry>
450
<term><envar>MANDOSPLUGINHELPERDIR</envar></term>
451
<listitem>
452
<para>
453
This environment variable will be assumed to contain the
454
directory containing any helper executables. The use and
455
nature of these helper executables, if any, is
456
purposefully not documented.
457
</para>
458
</listitem>
459
</varlistentry>
460
</variablelist>
461
<para>
462
This program does not use any other environment variables, not
463
even the ones provided by <citerefentry><refentrytitle
464
>cryptsetup</refentrytitle><manvolnum>8</manvolnum>
465
</citerefentry>.
466
</para>
467
</refsect1>
468
469
<refsect1 id="network-hooks">
470
<title>NETWORK HOOKS</title>
471
<para>
472
If a network interface like a bridge or tunnel is required to
473
find a Mandos server, this requires the interface to be up and
474
running before <command>&COMMANDNAME;</command> starts looking
475
for Mandos servers. This can be accomplished by creating a
476
<quote>network hook</quote> program, and placing it in a special
477
directory.
478
</para>
479
<para>
480
Before the network is used (and again before program exit), any
481
runnable programs found in the network hook directory are run
482
with the argument <quote><literal>start</literal></quote> or
483
<quote><literal>stop</literal></quote>. This should bring up or
484
down, respectively, any network interface which
485
<command>&COMMANDNAME;</command> should use.
486
</para>
487
<refsect2 id="hook-requirements">
488
<title>REQUIREMENTS</title>
489
<para>
490
A network hook must be an executable file, and its name must
491
consist entirely of upper and lower case letters, digits,
492
underscores, periods, and hyphens.
493
</para>
494
<para>
495
A network hook will receive one argument, which can be one of
496
the following:
497
</para>
498
<variablelist>
499
<varlistentry>
500
<term><literal>start</literal></term>
501
<listitem>
502
<para>
503
This should make the network hook create (if necessary)
504
and bring up a network interface.
505
</para>
506
</listitem>
507
</varlistentry>
508
<varlistentry>
509
<term><literal>stop</literal></term>
510
<listitem>
511
<para>
512
This should make the network hook take down a network
513
interface, and delete it if it did not exist previously.
514
</para>
515
</listitem>
516
</varlistentry>
517
<varlistentry>
518
<term><literal>files</literal></term>
519
<listitem>
520
<para>
521
This should make the network hook print, <emphasis>one
522
file per line</emphasis>, all the files needed for it to
523
run. (These files will be copied into the initial RAM
524
filesystem.) Typical use is for a network hook which is
525
a shell script to print its needed binaries.
526
</para>
527
<para>
528
It is not necessary to print any non-executable files
529
already in the network hook directory, these will be
530
copied implicitly if they otherwise satisfy the name
531
requirements.
532
</para>
533
</listitem>
534
</varlistentry>
535
<varlistentry>
536
<term><literal>modules</literal></term>
537
<listitem>
538
<para>
539
This should make the network hook print, <emphasis>on
540
separate lines</emphasis>, all the kernel modules needed
541
for it to run. (These modules will be copied into the
542
initial RAM filesystem.) For instance, a tunnel
543
interface needs the
544
<quote><literal>tun</literal></quote> module.
545
</para>
546
</listitem>
547
</varlistentry>
548
</variablelist>
549
<para>
550
The network hook will be provided with a number of environment
551
variables:
552
</para>
553
<variablelist>
554
<varlistentry>
555
<term><envar>MANDOSNETHOOKDIR</envar></term>
556
<listitem>
557
<para>
558
The network hook directory, specified to
559
<command>&COMMANDNAME;</command> by the
560
<option>--network-hook-dir</option> option. Note: this
561
should <emphasis>always</emphasis> be used by the
562
network hook to refer to itself or any files in the hook
563
directory it may require.
564
</para>
565
</listitem>
566
</varlistentry>
567
<varlistentry>
568
<term><envar>DEVICE</envar></term>
569
<listitem>
570
<para>
571
The network interfaces, as specified to
572
<command>&COMMANDNAME;</command> by the
573
<option>--interface</option> option, combined to one
574
string and separated by commas. If this is set, and
575
does not contain the interface a hook will bring up,
576
there is no reason for a hook to continue.
577
</para>
578
</listitem>
579
</varlistentry>
580
<varlistentry>
581
<term><envar>MODE</envar></term>
582
<listitem>
583
<para>
584
This will be the same as the first argument;
585
i.e. <quote><literal>start</literal></quote>,
586
<quote><literal>stop</literal></quote>,
587
<quote><literal>files</literal></quote>, or
588
<quote><literal>modules</literal></quote>.
589
</para>
590
</listitem>
591
</varlistentry>
592
<varlistentry>
593
<term><envar>VERBOSITY</envar></term>
594
<listitem>
595
<para>
596
This will be the <quote><literal>1</literal></quote> if
597
the <option>--debug</option> option is passed to
598
<command>&COMMANDNAME;</command>, otherwise
599
<quote><literal>0</literal></quote>.
600
</para>
601
</listitem>
602
</varlistentry>
603
<varlistentry>
604
<term><envar>DELAY</envar></term>
605
<listitem>
606
<para>
607
This will be the same as the <option>--delay</option>
608
option passed to <command>&COMMANDNAME;</command>. Is
609
only set if <envar>MODE</envar> is
610
<quote><literal>start</literal></quote> or
611
<quote><literal>stop</literal></quote>.
612
</para>
613
</listitem>
614
</varlistentry>
615
<varlistentry>
616
<term><envar>CONNECT</envar></term>
617
<listitem>
618
<para>
619
This will be the same as the <option>--connect</option>
620
option passed to <command>&COMMANDNAME;</command>. Is
621
only set if <option>--connect</option> is passed and
622
<envar>MODE</envar> is
623
<quote><literal>start</literal></quote> or
624
<quote><literal>stop</literal></quote>.
625
</para>
626
</listitem>
627
</varlistentry>
628
</variablelist>
629
<para>
630
A hook may not read from standard input, and should be
631
restrictive in printing to standard output or standard error
632
unless <varname>VERBOSITY</varname> is
633
<quote><literal>1</literal></quote>.
634
</para>
635
</refsect2>
636
</refsect1>
637
638
<refsect1 id="files">
639
<title>FILES</title>
640
<variablelist>
641
<varlistentry>
642
<term><filename>/conf/conf.d/mandos/pubkey.txt</filename
643
></term>
644
<term><filename>/conf/conf.d/mandos/seckey.txt</filename
645
></term>
646
<listitem>
647
<para>
648
OpenPGP public and private key files, in <quote>ASCII
649
Armor</quote> format. These are the default file names,
650
they can be changed with the <option>--pubkey</option> and
651
<option>--seckey</option> options.
652
</para>
653
</listitem>
654
</varlistentry>
655
<varlistentry>
656
<term><filename
657
class="directory">/lib/mandos/network-hooks.d</filename></term>
658
<listitem>
659
<para>
660
Directory where network hooks are located. Change this
661
with the <option>--network-hook-dir</option> option. See
662
<xref linkend="network-hooks"/>.
663
</para>
664
</listitem>
665
</varlistentry>
666
</variablelist>
667
</refsect1>
668
669
<!-- <refsect1 id="bugs"> -->
670
<!-- <title>BUGS</title> -->
671
<!-- <para> -->
672
<!-- </para> -->
673
<!-- </refsect1> -->
674
675
<refsect1 id="example">
676
<title>EXAMPLE</title>
677
<para>
678
Note that normally, command line options will not be given
679
directly, but via options for the Mandos <citerefentry
680
><refentrytitle>plugin-runner</refentrytitle>
681
<manvolnum>8mandos</manvolnum></citerefentry>.
682
</para>
683
<informalexample>
684
<para>
685
Normal invocation needs no options, if the network interfaces
686
can be automatically determined:
687
</para>
688
<para>
689
<userinput>&COMMANDNAME;</userinput>
690
</para>
691
</informalexample>
692
<informalexample>
693
<para>
694
Search for Mandos servers (and connect to them) using one
695
specific interface:
696
</para>
697
<para>
698
<!-- do not wrap this line -->
699
<userinput>&COMMANDNAME; --interface eth1</userinput>
700
</para>
701
</informalexample>
702
<informalexample>
703
<para>
704
Run in debug mode, and use a custom key:
705
</para>
706
<para>
707
708
<!-- do not wrap this line -->
709
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt</userinput>
710
711
</para>
712
</informalexample>
713
<informalexample>
714
<para>
715
Run in debug mode, with a custom key, and do not use Zeroconf
716
to locate a server; connect directly to the IPv6 link-local
717
address <quote><systemitem class="ipaddress"
718
>fe80::aede:48ff:fe71:f6f2</systemitem></quote>, port 4711,
719
using interface eth2:
720
</para>
721
<para>
722
723
<!-- do not wrap this line -->
724
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --connect fe80::aede:48ff:fe71:f6f2:4711 --interface eth2</userinput>
725
726
</para>
727
</informalexample>
728
</refsect1>
729
730
<refsect1 id="security">
731
<title>SECURITY</title>
732
<para>
733
This program is set-uid to root, but will switch back to the
734
original (and presumably non-privileged) user and group after
735
bringing up the network interface.
736
</para>
737
<para>
738
To use this program for its intended purpose (see <xref
739
linkend="purpose"/>), the password for the root file system will
740
have to be given out to be stored in a server computer, after
741
having been encrypted using an OpenPGP key. This encrypted data
742
which will be stored in a server can only be decrypted by the
743
OpenPGP key, and the data will only be given out to those
744
clients who can prove they actually have that key. This key,
745
however, is stored unencrypted on the client side in its initial
746
<acronym>RAM</acronym> disk image file system. This is normally
747
readable by all, but this is normally fixed during installation
748
of this program; file permissions are set so that no-one is able
749
to read that file.
750
</para>
751
<para>
752
The only remaining weak point is that someone with physical
753
access to the client hard drive might turn off the client
754
computer, read the OpenPGP keys directly from the hard drive,
755
and communicate with the server. To safeguard against this, the
756
server is supposed to notice the client disappearing and stop
757
giving out the encrypted data. Therefore, it is important to
758
set the timeout and checker interval values tightly on the
759
server. See <citerefentry><refentrytitle
760
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
761
</para>
762
<para>
763
It will also help if the checker program on the server is
764
configured to request something from the client which can not be
765
spoofed by someone else on the network, like SSH server key
766
fingerprints, and unlike unencrypted <acronym>ICMP</acronym>
767
echo (<quote>ping</quote>) replies.
768
</para>
769
<para>
770
<emphasis>Note</emphasis>: This makes it completely insecure to
771
have <application >Mandos</application> clients which dual-boot
772
to another operating system which is <emphasis>not</emphasis>
773
trusted to keep the initial <acronym>RAM</acronym> disk image
774
confidential.
775
</para>
776
</refsect1>
777
778
<refsect1 id="see_also">
779
<title>SEE ALSO</title>
780
<para>
781
<citerefentry><refentrytitle>intro</refentrytitle>
782
<manvolnum>8mandos</manvolnum></citerefentry>,
783
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
784
<manvolnum>8</manvolnum></citerefentry>,
785
<citerefentry><refentrytitle>crypttab</refentrytitle>
786
<manvolnum>5</manvolnum></citerefentry>,
787
<citerefentry><refentrytitle>mandos</refentrytitle>
788
<manvolnum>8</manvolnum></citerefentry>,
789
<citerefentry><refentrytitle>password-prompt</refentrytitle>
790
<manvolnum>8mandos</manvolnum></citerefentry>,
791
<citerefentry><refentrytitle>plugin-runner</refentrytitle>
792
<manvolnum>8mandos</manvolnum></citerefentry>
793
</para>
794
<variablelist>
795
<varlistentry>
796
<term>
797
<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>
798
</term>
799
<listitem>
800
<para>
801
Zeroconf is the network protocol standard used for finding
802
Mandos servers on the local network.
803
</para>
804
</listitem>
805
</varlistentry>
806
<varlistentry>
807
<term>
808
<ulink url="http://www.avahi.org/">Avahi</ulink>
809
</term>
810
<listitem>
811
<para>
812
Avahi is the library this program calls to find Zeroconf
813
services.
814
</para>
815
</listitem>
816
</varlistentry>
817
<varlistentry>
818
<term>
819
<ulink url="http://www.gnu.org/software/gnutls/"
820
>GnuTLS</ulink>
821
</term>
822
<listitem>
823
<para>
824
GnuTLS is the library this client uses to implement TLS for
825
communicating securely with the server, and at the same time
826
send the public OpenPGP key to the server.
827
</para>
828
</listitem>
829
</varlistentry>
830
<varlistentry>
831
<term>
832
<ulink url="http://www.gnupg.org/related_software/gpgme/"
833
>GPGME</ulink>
834
</term>
835
<listitem>
836
<para>
837
GPGME is the library used to decrypt the OpenPGP data sent
838
by the server.
839
</para>
840
</listitem>
841
</varlistentry>
842
<varlistentry>
843
<term>
844
RFC 4291: <citetitle>IP Version 6 Addressing
845
Architecture</citetitle>
846
</term>
847
<listitem>
848
<variablelist>
849
<varlistentry>
850
<term>Section 2.2: <citetitle>Text Representation of
851
Addresses</citetitle></term>
852
<listitem><para/></listitem>
853
</varlistentry>
854
<varlistentry>
855
<term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6
856
Address</citetitle></term>
857
<listitem><para/></listitem>
858
</varlistentry>
859
<varlistentry>
860
<term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast
861
Addresses</citetitle></term>
862
<listitem>
863
<para>
864
This client uses IPv6 link-local addresses, which are
865
immediately usable since a link-local addresses is
866
automatically assigned to a network interface when it
867
is brought up.
868
</para>
869
</listitem>
870
</varlistentry>
871
</variablelist>
872
</listitem>
873
</varlistentry>
874
<varlistentry>
875
<term>
876
RFC 4346: <citetitle>The Transport Layer Security (TLS)
877
Protocol Version 1.1</citetitle>
878
</term>
879
<listitem>
880
<para>
881
TLS 1.1 is the protocol implemented by GnuTLS.
882
</para>
883
</listitem>
884
</varlistentry>
885
<varlistentry>
886
<term>
887
RFC 4880: <citetitle>OpenPGP Message Format</citetitle>
888
</term>
889
<listitem>
890
<para>
891
The data received from the server is binary encrypted
892
OpenPGP data.
893
</para>
894
</listitem>
895
</varlistentry>
896
<varlistentry>
897
<term>
898
RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer
899
Security</citetitle>
900
</term>
901
<listitem>
902
<para>
903
This is implemented by GnuTLS and used by this program so
904
that OpenPGP keys can be used.
905
</para>
906
</listitem>
907
</varlistentry>
908
</variablelist>
909
</refsect1>
910
</refentry>
911
912
<!-- Local Variables: -->
913
<!-- time-stamp-start: "<!ENTITY TIMESTAMP [\"']" -->
914
<!-- time-stamp-end: "[\"']>" -->
915
<!-- time-stamp-format: "%:y-%02m-%02d" -->
916
<!-- End: -->
Loggerhead is a web-based interface for Breezy
Version: 2.0.2.dev0