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 the empty
206
string, which will automatically choose an appropriate
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.
210
If the <option>--connect</option> option is used, this
211
specifies the interface to use to connect to the address
260
215
Note that since this program will normally run in the
261
216
initial RAM disk environment, the interface must be an
262
217
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"/>.
218
can not be a pseudo-interface such as <quote>br0</quote>
219
or <quote>tun0</quote>; such interfaces will not exist
220
until much later in the boot process, and can not be used
271
224
<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.
225
<quote><literal>none</literal></quote>; this will not use
226
any specific interface, and will not bring up an interface
227
on startup. This is not recommended, and only meant for
465
371
server could be found and the password received from it could be
466
372
successfully decrypted and output on standard output. The
467
373
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.
374
error occurs. Otherwise, it will forever connect to new
375
<application>Mandos</application> servers as they appear, trying
376
to get a decryptable password and print it.
474
380
<refsect1 id="environment">
475
381
<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
383
This program does not use any environment variables, not even
384
the ones provided by <citerefentry><refentrytitle
492
385
>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
390
<refsect1 id="files">
667
391
<title>FILES</title>