126
145
<command>&COMMANDNAME;</command> is a client program that
127
146
communicates with <citerefentry><refentrytitle
128
147
>mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
129
to get a password. It uses IPv6 link-local addresses to get
130
network connectivity, Zeroconf to find servers, and TLS with an
131
OpenPGP key to ensure authenticity and confidentiality. It
132
keeps running, trying all servers on the network, until it
133
receives a satisfactory reply or a TERM signal is received.
148
to get a password. In slightly more detail, this client program
149
brings up network interfaces, uses the interfaces’ IPv6
150
link-local addresses to get network connectivity, uses Zeroconf
151
to find servers on the local network, and communicates with
152
servers using TLS with an OpenPGP key to ensure authenticity and
153
confidentiality. This client program keeps running, trying all
154
servers on the network, until it receives a satisfactory reply
155
or a TERM signal. After all servers have been tried, all
156
servers are periodically retried. If no servers are found it
157
will wait indefinitely for new servers to appear.
160
The network interfaces are selected like this: If any interfaces
161
are specified using the <option>--interface</option> option,
162
those interface are used. Otherwise,
163
<command>&COMMANDNAME;</command> will use all interfaces that
164
are not loopback interfaces, are not point-to-point interfaces,
165
are capable of broadcasting and do not have the NOARP flag (see
166
<citerefentry><refentrytitle>netdevice</refentrytitle>
167
<manvolnum>7</manvolnum></citerefentry>). (If the
168
<option>--connect</option> option is used, point-to-point
169
interfaces and non-broadcast interfaces are accepted.) If any
170
used interfaces are not up and running, they are first taken up
171
(and later taken down again on program exit).
174
Before network interfaces are selected, all <quote>network
175
hooks</quote> are run; see <xref linkend="network-hooks"/>.
136
178
This program is not meant to be run directly; it is really meant
183
225
assumed to separate the address from the port number.
186
This option is normally only useful for testing and
228
Normally, Zeroconf would be used to locate Mandos servers,
229
in which case this option would only be used when testing
193
<term><option>--interface=
194
<replaceable>NAME</replaceable></option></term>
236
<term><option>--interface=<replaceable
237
>NAME</replaceable><arg rep='repeat'>,<replaceable
238
>NAME</replaceable></arg></option></term>
196
<replaceable>NAME</replaceable></option></term>
240
<replaceable>NAME</replaceable><arg rep='repeat'>,<replaceable
241
>NAME</replaceable></arg></option></term>
199
Network interface that will be brought up and scanned for
200
Mandos servers to connect to. The default it
201
<quote><literal>eth0</literal></quote>.
204
If the <option>--connect</option> option is used, this
205
specifies the interface to use to connect to the address
244
Comma separated list of network interfaces that will be
245
brought up and scanned for Mandos servers to connect to.
246
The default is the empty string, which will automatically
247
use all appropriate interfaces.
250
If the <option>--connect</option> option is used, and
251
exactly one interface name is specified (except
252
<quote><literal>none</literal></quote>), this specifies
253
the interface to use to connect to the address given.
256
Note that since this program will normally run in the
257
initial RAM disk environment, the interface must be an
258
interface which exists at that stage. Thus, the interface
259
can normally not be a pseudo-interface such as
260
<quote>br0</quote> or <quote>tun0</quote>; such interfaces
261
will not exist until much later in the boot process, and
262
can not be used by this program, unless created by a
263
<quote>network hook</quote> — see <xref
264
linkend="network-hooks"/>.
267
<replaceable>NAME</replaceable> can be the string
268
<quote><literal>none</literal></quote>; this will make
269
<command>&COMMANDNAME;</command> only bring up interfaces
270
specified <emphasis>before</emphasis> this string. This
271
is not recommended, and only meant for advanced users.
349
461
server could be found and the password received from it could be
350
462
successfully decrypted and output on standard output. The
351
463
program will exit with a non-zero exit status only if a critical
352
error occurs. Otherwise, it will forever connect to new
353
<application>Mandos</application> servers as they appear, trying
354
to get a decryptable password and print it.
464
error occurs. Otherwise, it will forever connect to any
465
discovered <application>Mandos</application> servers, trying to
466
get a decryptable password and print it.
358
470
<refsect1 id="environment">
359
471
<title>ENVIRONMENT</title>
474
<term><envar>MANDOSPLUGINHELPERDIR</envar></term>
477
This environment variable will be assumed to contain the
478
directory containing any helper executables. The use and
479
nature of these helper executables, if any, is
480
purposefully not documented.
361
This program does not use any environment variables, not even
362
the ones provided by <citerefentry><refentrytitle
486
This program does not use any other environment variables, not
487
even the ones provided by <citerefentry><refentrytitle
363
488
>cryptsetup</refentrytitle><manvolnum>8</manvolnum>
493
<refsect1 id="network-hooks">
494
<title>NETWORK HOOKS</title>
496
If a network interface like a bridge or tunnel is required to
497
find a Mandos server, this requires the interface to be up and
498
running before <command>&COMMANDNAME;</command> starts looking
499
for Mandos servers. This can be accomplished by creating a
500
<quote>network hook</quote> program, and placing it in a special
504
Before the network is used (and again before program exit), any
505
runnable programs found in the network hook directory are run
506
with the argument <quote><literal>start</literal></quote> or
507
<quote><literal>stop</literal></quote>. This should bring up or
508
down, respectively, any network interface which
509
<command>&COMMANDNAME;</command> should use.
511
<refsect2 id="hook-requirements">
512
<title>REQUIREMENTS</title>
514
A network hook must be an executable file, and its name must
515
consist entirely of upper and lower case letters, digits,
516
underscores, periods, and hyphens.
519
A network hook will receive one argument, which can be one of
524
<term><literal>start</literal></term>
527
This should make the network hook create (if necessary)
528
and bring up a network interface.
533
<term><literal>stop</literal></term>
536
This should make the network hook take down a network
537
interface, and delete it if it did not exist previously.
542
<term><literal>files</literal></term>
545
This should make the network hook print, <emphasis>one
546
file per line</emphasis>, all the files needed for it to
547
run. (These files will be copied into the initial RAM
548
filesystem.) Typical use is for a network hook which is
549
a shell script to print its needed binaries.
552
It is not necessary to print any non-executable files
553
already in the network hook directory, these will be
554
copied implicitly if they otherwise satisfy the name
560
<term><literal>modules</literal></term>
563
This should make the network hook print, <emphasis>on
564
separate lines</emphasis>, all the kernel modules needed
565
for it to run. (These modules will be copied into the
566
initial RAM filesystem.) For instance, a tunnel
568
<quote><literal>tun</literal></quote> module.
574
The network hook will be provided with a number of environment
579
<term><envar>MANDOSNETHOOKDIR</envar></term>
582
The network hook directory, specified to
583
<command>&COMMANDNAME;</command> by the
584
<option>--network-hook-dir</option> option. Note: this
585
should <emphasis>always</emphasis> be used by the
586
network hook to refer to itself or any files in the hook
587
directory it may require.
592
<term><envar>DEVICE</envar></term>
595
The network interfaces, as specified to
596
<command>&COMMANDNAME;</command> by the
597
<option>--interface</option> option, combined to one
598
string and separated by commas. If this is set, and
599
does not contain the interface a hook will bring up,
600
there is no reason for a hook to continue.
605
<term><envar>MODE</envar></term>
608
This will be the same as the first argument;
609
i.e. <quote><literal>start</literal></quote>,
610
<quote><literal>stop</literal></quote>,
611
<quote><literal>files</literal></quote>, or
612
<quote><literal>modules</literal></quote>.
617
<term><envar>VERBOSITY</envar></term>
620
This will be the <quote><literal>1</literal></quote> if
621
the <option>--debug</option> option is passed to
622
<command>&COMMANDNAME;</command>, otherwise
623
<quote><literal>0</literal></quote>.
628
<term><envar>DELAY</envar></term>
631
This will be the same as the <option>--delay</option>
632
option passed to <command>&COMMANDNAME;</command>. Is
633
only set if <envar>MODE</envar> is
634
<quote><literal>start</literal></quote> or
635
<quote><literal>stop</literal></quote>.
640
<term><envar>CONNECT</envar></term>
643
This will be the same as the <option>--connect</option>
644
option passed to <command>&COMMANDNAME;</command>. Is
645
only set if <option>--connect</option> is passed and
646
<envar>MODE</envar> is
647
<quote><literal>start</literal></quote> or
648
<quote><literal>stop</literal></quote>.
654
A hook may not read from standard input, and should be
655
restrictive in printing to standard output or standard error
656
unless <varname>VERBOSITY</varname> is
657
<quote><literal>1</literal></quote>.
368
662
<refsect1 id="files">
369
663
<title>FILES</title>