150
127
communicates with <citerefentry><refentrytitle
151
128
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
152
129
to get a password. In slightly more detail, this client program
153
brings up network interfaces, uses the interfaces’ IPv6
154
link-local addresses to get network connectivity, uses Zeroconf
155
to find servers on the local network, and communicates with
156
servers using TLS with an OpenPGP key to ensure authenticity and
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
157
134
confidentiality. This client program keeps running, trying all
158
135
servers on the network, until it receives a satisfactory reply
159
or a TERM signal. After all servers have been tried, all
160
servers are periodically retried. If no servers are found it
161
will wait indefinitely for new servers to appear.
164
The network interfaces are selected like this: If any interfaces
165
are specified using the <option>--interface</option> option,
166
those interface are used. Otherwise,
167
<command>&COMMANDNAME;</command> will use all interfaces that
168
are not loopback interfaces, are not point-to-point interfaces,
169
are capable of broadcasting and do not have the NOARP flag (see
170
<citerefentry><refentrytitle>netdevice</refentrytitle>
171
<manvolnum>7</manvolnum></citerefentry>). (If the
172
<option>--connect</option> option is used, point-to-point
173
interfaces and non-broadcast interfaces are accepted.) If any
174
used interfaces are not up and running, they are first taken up
175
(and later taken down again on program exit).
178
Before network interfaces are selected, all <quote>network
179
hooks</quote> are run; see <xref linkend="network-hooks"/>.
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
182
141
This program is not meant to be run directly; it is really meant
229
188
assumed to separate the address from the port number.
232
Normally, Zeroconf would be used to locate Mandos servers,
233
in which case this option would only be used when testing
191
This option is normally only useful for testing and
240
198
<term><option>--interface=<replaceable
241
>NAME</replaceable><arg rep='repeat'>,<replaceable
242
>NAME</replaceable></arg></option></term>
199
>NAME</replaceable></option></term>
244
<replaceable>NAME</replaceable><arg rep='repeat'>,<replaceable
245
>NAME</replaceable></arg></option></term>
201
<replaceable>NAME</replaceable></option></term>
248
Comma separated list of network interfaces that will be
249
brought up and scanned for Mandos servers to connect to.
250
The default is the empty string, which will automatically
251
use all appropriate interfaces.
204
Network interface that will be brought up and scanned for
205
Mandos servers to connect to. The default is
206
<quote><literal>eth0</literal></quote>.
254
If the <option>--connect</option> option is used, and
255
exactly one interface name is specified (except
256
<quote><literal>none</literal></quote>), this specifies
257
the interface to use to connect to the address given.
209
If the <option>--connect</option> option is used, this
210
specifies the interface to use to connect to the address
260
214
Note that since this program will normally run in the
261
215
initial RAM disk environment, the interface must be an
262
216
interface which exists at that stage. Thus, the interface
263
can normally not be a pseudo-interface such as
264
<quote>br0</quote> or <quote>tun0</quote>; such interfaces
265
will not exist until much later in the boot process, and
266
can not be used by this program, unless created by a
267
<quote>network hook</quote> — see <xref
268
linkend="network-hooks"/>.
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
271
<replaceable>NAME</replaceable> can be the string
272
<quote><literal>none</literal></quote>; this will make
273
<command>&COMMANDNAME;</command> only bring up interfaces
274
specified <emphasis>before</emphasis> this string. This
275
is not recommended, and only meant for advanced users.
223
<replaceable>NAME</replaceable> can be the empty string;
224
this will not use any specific interface, and will not
225
bring up an interface on startup. This is not
226
recommended, and only meant for advanced users.
465
369
server could be found and the password received from it could be
466
370
successfully decrypted and output on standard output. The
467
371
program will exit with a non-zero exit status only if a critical
468
error occurs. Otherwise, it will forever connect to any
469
discovered <application>Mandos</application> servers, trying to
470
get a decryptable password and print it.
372
error occurs. Otherwise, it will forever connect to new
373
<application>Mandos</application> servers as they appear, trying
374
to get a decryptable password and print it.
474
378
<refsect1 id="environment">
475
379
<title>ENVIRONMENT</title>
478
<term><envar>MANDOSPLUGINHELPERDIR</envar></term>
481
This environment variable will be assumed to contain the
482
directory containing any helper executables. The use and
483
nature of these helper executables, if any, is
484
purposefully not documented.
490
This program does not use any other environment variables, not
491
even the ones provided by <citerefentry><refentrytitle
381
This program does not use any environment variables, not even
382
the ones provided by <citerefentry><refentrytitle
492
383
>cryptsetup</refentrytitle><manvolnum>8</manvolnum>
497
<refsect1 id="network-hooks">
498
<title>NETWORK HOOKS</title>
500
If a network interface like a bridge or tunnel is required to
501
find a Mandos server, this requires the interface to be up and
502
running before <command>&COMMANDNAME;</command> starts looking
503
for Mandos servers. This can be accomplished by creating a
504
<quote>network hook</quote> program, and placing it in a special
508
Before the network is used (and again before program exit), any
509
runnable programs found in the network hook directory are run
510
with the argument <quote><literal>start</literal></quote> or
511
<quote><literal>stop</literal></quote>. This should bring up or
512
down, respectively, any network interface which
513
<command>&COMMANDNAME;</command> should use.
515
<refsect2 id="hook-requirements">
516
<title>REQUIREMENTS</title>
518
A network hook must be an executable file, and its name must
519
consist entirely of upper and lower case letters, digits,
520
underscores, periods, and hyphens.
523
A network hook will receive one argument, which can be one of
528
<term><literal>start</literal></term>
531
This should make the network hook create (if necessary)
532
and bring up a network interface.
537
<term><literal>stop</literal></term>
540
This should make the network hook take down a network
541
interface, and delete it if it did not exist previously.
546
<term><literal>files</literal></term>
549
This should make the network hook print, <emphasis>one
550
file per line</emphasis>, all the files needed for it to
551
run. (These files will be copied into the initial RAM
552
filesystem.) Typical use is for a network hook which is
553
a shell script to print its needed binaries.
556
It is not necessary to print any non-executable files
557
already in the network hook directory, these will be
558
copied implicitly if they otherwise satisfy the name
564
<term><literal>modules</literal></term>
567
This should make the network hook print, <emphasis>on
568
separate lines</emphasis>, all the kernel modules needed
569
for it to run. (These modules will be copied into the
570
initial RAM filesystem.) For instance, a tunnel
572
<quote><literal>tun</literal></quote> module.
578
The network hook will be provided with a number of environment
583
<term><envar>MANDOSNETHOOKDIR</envar></term>
586
The network hook directory, specified to
587
<command>&COMMANDNAME;</command> by the
588
<option>--network-hook-dir</option> option. Note: this
589
should <emphasis>always</emphasis> be used by the
590
network hook to refer to itself or any files in the hook
591
directory it may require.
596
<term><envar>DEVICE</envar></term>
599
The network interfaces, as specified to
600
<command>&COMMANDNAME;</command> by the
601
<option>--interface</option> option, combined to one
602
string and separated by commas. If this is set, and
603
does not contain the interface a hook will bring up,
604
there is no reason for a hook to continue.
609
<term><envar>MODE</envar></term>
612
This will be the same as the first argument;
613
i.e. <quote><literal>start</literal></quote>,
614
<quote><literal>stop</literal></quote>,
615
<quote><literal>files</literal></quote>, or
616
<quote><literal>modules</literal></quote>.
621
<term><envar>VERBOSITY</envar></term>
624
This will be the <quote><literal>1</literal></quote> if
625
the <option>--debug</option> option is passed to
626
<command>&COMMANDNAME;</command>, otherwise
627
<quote><literal>0</literal></quote>.
632
<term><envar>DELAY</envar></term>
635
This will be the same as the <option>--delay</option>
636
option passed to <command>&COMMANDNAME;</command>. Is
637
only set if <envar>MODE</envar> is
638
<quote><literal>start</literal></quote> or
639
<quote><literal>stop</literal></quote>.
644
<term><envar>CONNECT</envar></term>
647
This will be the same as the <option>--connect</option>
648
option passed to <command>&COMMANDNAME;</command>. Is
649
only set if <option>--connect</option> is passed and
650
<envar>MODE</envar> is
651
<quote><literal>start</literal></quote> or
652
<quote><literal>stop</literal></quote>.
658
A hook may not read from standard input, and should be
659
restrictive in printing to standard output or standard error
660
unless <varname>VERBOSITY</varname> is
661
<quote><literal>1</literal></quote>.
666
388
<refsect1 id="files">
667
389
<title>FILES</title>