To get this branch, use:
bzr branch
http://bzr.recompile.se/loggerhead/mandos/trunk
« back to all changes in this revision
Viewing changes to plugins.d/mandos-client.xml
- browse files at revision 831
- compare with another revision
- download diff
- download tarball
- view history from revision 831
- Committer: Teddy Hogeborn
- Date: 2016-03-13 00:37:02 UTC
- Revision ID: teddy@recompile.se-20160313003702-dulwtwt8ilpojra9
Server: Fix bug where it did not exit timely on signals
Use GLib.unix_signal_add() instead of signal.signal() to catch
signals; this will allow GLib to do its internal magic with signal
file descriptors. (GLib does not handle signals properly otherwise.)
The function unix_signal_add() requires GLib 2.30 or later, which was
not required by PyGobject until version 3.7.1, so depend on this.
* INSTALL (Mandos Server): Document dependency on PyGObject 3.7.1
* mandos (main): Use GLib.unix_signal_add instead of signal.signal.
* init.d-mandos (do_stop): Remove workaround.
* mandos.service ([Service]): - '' -
Use GLib.unix_signal_add() instead of signal.signal() to catch
signals; this will allow GLib to do its internal magic with signal
file descriptors. (GLib does not handle signals properly otherwise.)
The function unix_signal_add() requires GLib 2.30 or later, which was
not required by PyGobject until version 3.7.1, so depend on this.
* INSTALL (Mandos Server): Document dependency on PyGObject 3.7.1
* mandos (main): Use GLib.unix_signal_add instead of signal.signal.
* init.d-mandos (do_stop): Remove workaround.
* mandos.service ([Service]): - '' -
- files added:
- DBUS-API
- debian/source
- debian/upstream
- network-hooks.d
- plugin-helpers
- files modified:
- .bzrignore
added
removed
plugins.d/mandos-client.xml
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
4
<!ENTITY COMMANDNAME "mandos-client">
5
<!ENTITY TIMESTAMP "2009-01-24">
5
<!ENTITY TIMESTAMP "2016-03-05">
6
6
<!ENTITY % common SYSTEM "../common.ent">
7
7
%common;
8
8
]>
19
19
<firstname>Björn</firstname>
20
20
<surname>Påhlsson</surname>
21
21
<address>
22
<email>belorn@fukt.bsnet.se</email>
22
<email>belorn@recompile.se</email>
23
23
</address>
24
24
</author>
25
25
<author>
26
26
<firstname>Teddy</firstname>
27
27
<surname>Hogeborn</surname>
28
28
<address>
29
<email>teddy@fukt.bsnet.se</email>
29
<email>teddy@recompile.se</email>
30
30
</address>
31
31
</author>
32
32
</authorgroup>
33
33
<copyright>
34
34
<year>2008</year>
35
35
<year>2009</year>
36
<year>2010</year>
37
<year>2011</year>
38
<year>2012</year>
39
<year>2013</year>
40
<year>2014</year>
41
<year>2015</year>
42
<year>2016</year>
36
43
<holder>Teddy Hogeborn</holder>
37
44
<holder>Björn Påhlsson</holder>
38
45
</copyright>
63
70
><replaceable>PORT</replaceable></option></arg>
64
71
</group>
65
72
<sbr/>
66
<group>
73
<group rep='repeat'>
67
74
<arg choice="plain"><option>--interface
68
<replaceable>NAME</replaceable></option></arg>
69
<arg choice="plain"><option>-i
70
<replaceable>NAME</replaceable></option></arg>
75
<replaceable>NAME</replaceable><arg rep='repeat'
76
>,<replaceable>NAME</replaceable></arg></option></arg>
77
<arg choice="plain"><option>-i <replaceable>NAME</replaceable
78
><arg rep='repeat'>,<replaceable>NAME</replaceable></arg
79
></option></arg>
71
80
</group>
72
81
<sbr/>
73
82
<group>
93
102
</arg>
94
103
<sbr/>
95
104
<arg>
105
<option>--dh-params <replaceable>FILE</replaceable></option>
106
</arg>
107
<sbr/>
108
<arg>
96
109
<option>--delay <replaceable>SECONDS</replaceable></option>
97
110
</arg>
98
111
<sbr/>
99
112
<arg>
113
<option>--retry <replaceable>SECONDS</replaceable></option>
114
</arg>
115
<sbr/>
116
<arg>
117
<option>--network-hook-dir
118
<replaceable>DIR</replaceable></option>
119
</arg>
120
<sbr/>
121
<arg>
100
122
<option>--debug</option>
101
123
</arg>
102
124
</cmdsynopsis>
127
149
communicates with <citerefentry><refentrytitle
128
150
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
129
151
to get a password. In slightly more detail, this client program
130
brings up a network interface, uses the interface’s IPv6
131
link-local address to get network connectivity, uses Zeroconf to
132
find servers on the local network, and communicates with servers
133
using TLS with an OpenPGP key to ensure authenticity and
152
brings up network interfaces, uses the interfaces’ IPv6
153
link-local addresses to get network connectivity, uses Zeroconf
154
to find servers on the local network, and communicates with
155
servers using TLS with an OpenPGP key to ensure authenticity and
134
156
confidentiality. This client program keeps running, trying all
135
157
servers on the network, until it receives a satisfactory reply
136
or a TERM signal is received. If no servers are found, or after
137
all servers have been tried, it waits indefinitely for new
138
servers to appear.
158
or a TERM signal. After all servers have been tried, all
159
servers are periodically retried. If no servers are found it
160
will wait indefinitely for new servers to appear.
161
</para>
162
<para>
163
The network interfaces are selected like this: If any interfaces
164
are specified using the <option>--interface</option> option,
165
those interface are used. Otherwise,
166
<command>&COMMANDNAME;</command> will use all interfaces that
167
are not loopback interfaces, are not point-to-point interfaces,
168
are capable of broadcasting and do not have the NOARP flag (see
169
<citerefentry><refentrytitle>netdevice</refentrytitle>
170
<manvolnum>7</manvolnum></citerefentry>). (If the
171
<option>--connect</option> option is used, point-to-point
172
interfaces and non-broadcast interfaces are accepted.) If any
173
used interfaces are not up and running, they are first taken up
174
(and later taken down again on program exit).
175
</para>
176
<para>
177
Before network interfaces are selected, all <quote>network
178
hooks</quote> are run; see <xref linkend="network-hooks"/>.
139
179
</para>
140
180
<para>
141
181
This program is not meant to be run directly; it is really meant
188
228
assumed to separate the address from the port number.
189
229
</para>
190
230
<para>
191
This option is normally only useful for testing and
192
debugging.
231
Normally, Zeroconf would be used to locate Mandos servers,
232
in which case this option would only be used when testing
233
and debugging.
193
234
</para>
194
235
</listitem>
195
236
</varlistentry>
196
237
197
238
<varlistentry>
198
<term><option>--interface=
199
<replaceable>NAME</replaceable></option></term>
239
<term><option>--interface=<replaceable
240
>NAME</replaceable><arg rep='repeat'>,<replaceable
241
>NAME</replaceable></arg></option></term>
200
242
<term><option>-i
201
<replaceable>NAME</replaceable></option></term>
243
<replaceable>NAME</replaceable><arg rep='repeat'>,<replaceable
244
>NAME</replaceable></arg></option></term>
202
245
<listitem>
203
246
<para>
204
Network interface that will be brought up and scanned for
205
Mandos servers to connect to. The default it
206
<quote><literal>eth0</literal></quote>.
247
Comma separated list of network interfaces that will be
248
brought up and scanned for Mandos servers to connect to.
249
The default is the empty string, which will automatically
250
use all appropriate interfaces.
207
251
</para>
208
252
<para>
209
If the <option>--connect</option> option is used, this
210
specifies the interface to use to connect to the address
211
given.
253
If the <option>--connect</option> option is used, and
254
exactly one interface name is specified (except
255
<quote><literal>none</literal></quote>), this specifies
256
the interface to use to connect to the address given.
212
257
</para>
213
258
<para>
214
259
Note that since this program will normally run in the
215
260
initial RAM disk environment, the interface must be an
216
261
interface which exists at that stage. Thus, the interface
217
can not be a pseudo-interface such as <quote>br0</quote>
218
or <quote>tun0</quote>; such interfaces will not exist
219
until much later in the boot process, and can not be used
220
by this program.
262
can normally not be a pseudo-interface such as
263
<quote>br0</quote> or <quote>tun0</quote>; such interfaces
264
will not exist until much later in the boot process, and
265
can not be used by this program, unless created by a
266
<quote>network hook</quote> — see <xref
267
linkend="network-hooks"/>.
268
</para>
269
<para>
270
<replaceable>NAME</replaceable> can be the string
271
<quote><literal>none</literal></quote>; this will make
272
<command>&COMMANDNAME;</command> only bring up interfaces
273
specified <emphasis>before</emphasis> this string. This
274
is not recommended, and only meant for advanced users.
221
275
</para>
222
276
</listitem>
223
277
</varlistentry>
265
319
<listitem>
266
320
<para>
267
321
Sets the number of bits to use for the prime number in the
268
TLS Diffie-Hellman key exchange. Default is 1024.
322
TLS Diffie-Hellman key exchange. The default value is
323
selected automatically based on the OpenPGP key. Note
324
that if the <option>--dh-params</option> option is used,
325
the values from that file will be used instead.
326
</para>
327
</listitem>
328
</varlistentry>
329
330
<varlistentry>
331
<term><option>--dh-params=<replaceable
332
>FILE</replaceable></option></term>
333
<listitem>
334
<para>
335
Specifies a PEM-encoded PKCS#3 file to read the parameters
336
needed by the TLS Diffie-Hellman key exchange from. If
337
this option is not given, or if the file for some reason
338
could not be used, the parameters will be generated on
339
startup, which will take some time and processing power.
340
Those using servers running under time, power or processor
341
constraints may want to generate such a file in advance
342
and use this option.
269
343
</para>
270
344
</listitem>
271
345
</varlistentry>
275
349
>SECONDS</replaceable></option></term>
276
350
<listitem>
277
351
<para>
278
After bringing the network interface up, the program waits
352
After bringing a network interface up, the program waits
279
353
for the interface to arrive in a <quote>running</quote>
280
354
state before proceeding. During this time, the kernel log
281
355
level will be lowered to reduce clutter on the system
285
359
</para>
286
360
</listitem>
287
361
</varlistentry>
362
363
<varlistentry>
364
<term><option>--retry=<replaceable
365
>SECONDS</replaceable></option></term>
366
<listitem>
367
<para>
368
All Mandos servers are tried repeatedly until a password
369
is received. This value specifies, in seconds, how long
370
between each successive try <emphasis>for the same
371
server</emphasis>. The default is 10 seconds.
372
</para>
373
</listitem>
374
</varlistentry>
375
376
<varlistentry>
377
<term><option>--network-hook-dir=<replaceable
378
>DIR</replaceable></option></term>
379
<listitem>
380
<para>
381
Network hook directory. The default directory is
382
<quote><filename class="directory"
383
>/lib/mandos/network-hooks.d</filename></quote>.
384
</para>
385
</listitem>
386
</varlistentry>
288
387
289
388
<varlistentry>
290
389
<term><option>--debug</option></term>
351
450
<refentrytitle>plugin-runner</refentrytitle>
352
451
<manvolnum>8mandos</manvolnum></citerefentry>) is used to run
353
452
both this program and others in in parallel,
354
<emphasis>one</emphasis> of which will prompt for passwords on
355
the system console.
453
<emphasis>one</emphasis> of which (<citerefentry>
454
<refentrytitle>password-prompt</refentrytitle>
455
<manvolnum>8mandos</manvolnum></citerefentry>) will prompt for
456
passwords on the system console.
356
457
</para>
357
458
</refsect1>
358
459
363
464
server could be found and the password received from it could be
364
465
successfully decrypted and output on standard output. The
365
466
program will exit with a non-zero exit status only if a critical
366
error occurs. Otherwise, it will forever connect to new
367
<application>Mandos</application> servers as they appear, trying
368
to get a decryptable password and print it.
467
error occurs. Otherwise, it will forever connect to any
468
discovered <application>Mandos</application> servers, trying to
469
get a decryptable password and print it.
369
470
</para>
370
471
</refsect1>
371
472
372
473
<refsect1 id="environment">
373
474
<title>ENVIRONMENT</title>
475
<variablelist>
476
<varlistentry>
477
<term><envar>MANDOSPLUGINHELPERDIR</envar></term>
478
<listitem>
479
<para>
480
This environment variable will be assumed to contain the
481
directory containing any helper executables. The use and
482
nature of these helper executables, if any, is
483
purposefully not documented.
484
</para>
485
</listitem>
486
</varlistentry>
487
</variablelist>
374
488
<para>
375
This program does not use any environment variables, not even
376
the ones provided by <citerefentry><refentrytitle
489
This program does not use any other environment variables, not
490
even the ones provided by <citerefentry><refentrytitle
377
491
>cryptsetup</refentrytitle><manvolnum>8</manvolnum>
378
492
</citerefentry>.
379
493
</para>
380
494
</refsect1>
381
495
496
<refsect1 id="network-hooks">
497
<title>NETWORK HOOKS</title>
498
<para>
499
If a network interface like a bridge or tunnel is required to
500
find a Mandos server, this requires the interface to be up and
501
running before <command>&COMMANDNAME;</command> starts looking
502
for Mandos servers. This can be accomplished by creating a
503
<quote>network hook</quote> program, and placing it in a special
504
directory.
505
</para>
506
<para>
507
Before the network is used (and again before program exit), any
508
runnable programs found in the network hook directory are run
509
with the argument <quote><literal>start</literal></quote> or
510
<quote><literal>stop</literal></quote>. This should bring up or
511
down, respectively, any network interface which
512
<command>&COMMANDNAME;</command> should use.
513
</para>
514
<refsect2 id="hook-requirements">
515
<title>REQUIREMENTS</title>
516
<para>
517
A network hook must be an executable file, and its name must
518
consist entirely of upper and lower case letters, digits,
519
underscores, periods, and hyphens.
520
</para>
521
<para>
522
A network hook will receive one argument, which can be one of
523
the following:
524
</para>
525
<variablelist>
526
<varlistentry>
527
<term><literal>start</literal></term>
528
<listitem>
529
<para>
530
This should make the network hook create (if necessary)
531
and bring up a network interface.
532
</para>
533
</listitem>
534
</varlistentry>
535
<varlistentry>
536
<term><literal>stop</literal></term>
537
<listitem>
538
<para>
539
This should make the network hook take down a network
540
interface, and delete it if it did not exist previously.
541
</para>
542
</listitem>
543
</varlistentry>
544
<varlistentry>
545
<term><literal>files</literal></term>
546
<listitem>
547
<para>
548
This should make the network hook print, <emphasis>one
549
file per line</emphasis>, all the files needed for it to
550
run. (These files will be copied into the initial RAM
551
filesystem.) Typical use is for a network hook which is
552
a shell script to print its needed binaries.
553
</para>
554
<para>
555
It is not necessary to print any non-executable files
556
already in the network hook directory, these will be
557
copied implicitly if they otherwise satisfy the name
558
requirements.
559
</para>
560
</listitem>
561
</varlistentry>
562
<varlistentry>
563
<term><literal>modules</literal></term>
564
<listitem>
565
<para>
566
This should make the network hook print, <emphasis>on
567
separate lines</emphasis>, all the kernel modules needed
568
for it to run. (These modules will be copied into the
569
initial RAM filesystem.) For instance, a tunnel
570
interface needs the
571
<quote><literal>tun</literal></quote> module.
572
</para>
573
</listitem>
574
</varlistentry>
575
</variablelist>
576
<para>
577
The network hook will be provided with a number of environment
578
variables:
579
</para>
580
<variablelist>
581
<varlistentry>
582
<term><envar>MANDOSNETHOOKDIR</envar></term>
583
<listitem>
584
<para>
585
The network hook directory, specified to
586
<command>&COMMANDNAME;</command> by the
587
<option>--network-hook-dir</option> option. Note: this
588
should <emphasis>always</emphasis> be used by the
589
network hook to refer to itself or any files in the hook
590
directory it may require.
591
</para>
592
</listitem>
593
</varlistentry>
594
<varlistentry>
595
<term><envar>DEVICE</envar></term>
596
<listitem>
597
<para>
598
The network interfaces, as specified to
599
<command>&COMMANDNAME;</command> by the
600
<option>--interface</option> option, combined to one
601
string and separated by commas. If this is set, and
602
does not contain the interface a hook will bring up,
603
there is no reason for a hook to continue.
604
</para>
605
</listitem>
606
</varlistentry>
607
<varlistentry>
608
<term><envar>MODE</envar></term>
609
<listitem>
610
<para>
611
This will be the same as the first argument;
612
i.e. <quote><literal>start</literal></quote>,
613
<quote><literal>stop</literal></quote>,
614
<quote><literal>files</literal></quote>, or
615
<quote><literal>modules</literal></quote>.
616
</para>
617
</listitem>
618
</varlistentry>
619
<varlistentry>
620
<term><envar>VERBOSITY</envar></term>
621
<listitem>
622
<para>
623
This will be the <quote><literal>1</literal></quote> if
624
the <option>--debug</option> option is passed to
625
<command>&COMMANDNAME;</command>, otherwise
626
<quote><literal>0</literal></quote>.
627
</para>
628
</listitem>
629
</varlistentry>
630
<varlistentry>
631
<term><envar>DELAY</envar></term>
632
<listitem>
633
<para>
634
This will be the same as the <option>--delay</option>
635
option passed to <command>&COMMANDNAME;</command>. Is
636
only set if <envar>MODE</envar> is
637
<quote><literal>start</literal></quote> or
638
<quote><literal>stop</literal></quote>.
639
</para>
640
</listitem>
641
</varlistentry>
642
<varlistentry>
643
<term><envar>CONNECT</envar></term>
644
<listitem>
645
<para>
646
This will be the same as the <option>--connect</option>
647
option passed to <command>&COMMANDNAME;</command>. Is
648
only set if <option>--connect</option> is passed and
649
<envar>MODE</envar> is
650
<quote><literal>start</literal></quote> or
651
<quote><literal>stop</literal></quote>.
652
</para>
653
</listitem>
654
</varlistentry>
655
</variablelist>
656
<para>
657
A hook may not read from standard input, and should be
658
restrictive in printing to standard output or standard error
659
unless <varname>VERBOSITY</varname> is
660
<quote><literal>1</literal></quote>.
661
</para>
662
</refsect2>
663
</refsect1>
664
382
665
<refsect1 id="files">
383
666
<title>FILES</title>
384
667
<variablelist>
396
679
</para>
397
680
</listitem>
398
681
</varlistentry>
682
<varlistentry>
683
<term><filename
684
class="directory">/lib/mandos/network-hooks.d</filename></term>
685
<listitem>
686
<para>
687
Directory where network hooks are located. Change this
688
with the <option>--network-hook-dir</option> option. See
689
<xref linkend="network-hooks"/>.
690
</para>
691
</listitem>
692
</varlistentry>
399
693
</variablelist>
400
694
</refsect1>
401
695
402
<!-- <refsect1 id="bugs"> -->
403
<!-- <title>BUGS</title> -->
404
<!-- <para> -->
405
<!-- </para> -->
406
<!-- </refsect1> -->
696
<refsect1 id="bugs">
697
<title>BUGS</title>
698
<xi:include href="../bugs.xml"/>
699
</refsect1>
407
700
408
701
<refsect1 id="example">
409
702
<title>EXAMPLE</title>
415
708
</para>
416
709
<informalexample>
417
710
<para>
418
Normal invocation needs no options, if the network interface
419
is <quote>eth0</quote>:
711
Normal invocation needs no options, if the network interfaces
712
can be automatically determined:
420
713
</para>
421
714
<para>
422
715
<userinput>&COMMANDNAME;</userinput>
424
717
</informalexample>
425
718
<informalexample>
426
719
<para>
427
Search for Mandos servers (and connect to them) using another
428
interface:
720
Search for Mandos servers (and connect to them) using one
721
specific interface:
429
722
</para>
430
723
<para>
431
724
<!-- do not wrap this line -->
446
739
<informalexample>
447
740
<para>
448
741
Run in debug mode, with a custom key, and do not use Zeroconf
449
to locate a server; connect directly to the IPv6 address
450
<quote><systemitem class="ipaddress"
451
>2001:db8:f983:bd0b:30de:ae4a:71f2:f672</systemitem></quote>,
452
port 4711, using interface eth2:
742
to locate a server; connect directly to the IPv6 link-local
743
address <quote><systemitem class="ipaddress"
744
>fe80::aede:48ff:fe71:f6f2</systemitem></quote>, port 4711,
745
using interface eth2:
453
746
</para>
454
747
<para>
455
748
456
749
<!-- do not wrap this line -->
457
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --connect 2001:db8:f983:bd0b:30de:ae4a:71f2:f672:4711 --interface eth2</userinput>
750
<userinput>&COMMANDNAME; --debug --pubkey keydir/pubkey.txt --seckey keydir/seckey.txt --connect fe80::aede:48ff:fe71:f6f2:4711 --interface eth2</userinput>
458
751
459
752
</para>
460
753
</informalexample>
495
788
<para>
496
789
It will also help if the checker program on the server is
497
790
configured to request something from the client which can not be
498
spoofed by someone else on the network, unlike unencrypted
499
<acronym>ICMP</acronym> echo (<quote>ping</quote>) replies.
791
spoofed by someone else on the network, like SSH server key
792
fingerprints, and unlike unencrypted <acronym>ICMP</acronym>
793
echo (<quote>ping</quote>) replies.
500
794
</para>
501
795
<para>
502
796
<emphasis>Note</emphasis>: This makes it completely insecure to
510
804
<refsect1 id="see_also">
511
805
<title>SEE ALSO</title>
512
806
<para>
807
<citerefentry><refentrytitle>intro</refentrytitle>
808
<manvolnum>8mandos</manvolnum></citerefentry>,
513
809
<citerefentry><refentrytitle>cryptsetup</refentrytitle>
514
810
<manvolnum>8</manvolnum></citerefentry>,
515
811
<citerefentry><refentrytitle>crypttab</refentrytitle>
593
889
<para>
594
890
This client uses IPv6 link-local addresses, which are
595
891
immediately usable since a link-local addresses is
596
automatically assigned to a network interfaces when it
892
automatically assigned to a network interface when it
597
893
is brought up.
598
894
</para>
599
895
</listitem>
Loggerhead is a web-based interface for Breezy
Version: 2.0.2.dev0