126
148
<command>&COMMANDNAME;</command> is a client program that
127
149
communicates with <citerefentry><refentrytitle
128
150
>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.
151
to get a password. In slightly more detail, this client program
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
156
confidentiality. This client program keeps running, trying all
157
servers on the network, until it receives a satisfactory reply
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.
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).
177
Before network interfaces are selected, all <quote>network
178
hooks</quote> are run; see <xref linkend="network-hooks"/>.
136
181
This program is not meant to be run directly; it is really meant
183
228
assumed to separate the address from the port number.
186
This option is normally only useful for testing and
231
Normally, Zeroconf would be used to locate Mandos servers,
232
in which case this option would only be used when testing
193
<term><option>--interface=
194
<replaceable>NAME</replaceable></option></term>
239
<term><option>--interface=<replaceable
240
>NAME</replaceable><arg rep='repeat'>,<replaceable
241
>NAME</replaceable></arg></option></term>
196
<replaceable>NAME</replaceable></option></term>
243
<replaceable>NAME</replaceable><arg rep='repeat'>,<replaceable
244
>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
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.
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.
259
Note that since this program will normally run in the
260
initial RAM disk environment, the interface must be an
261
interface which exists at that stage. Thus, the interface
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"/>.
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.
349
464
server could be found and the password received from it could be
350
465
successfully decrypted and output on standard output. The
351
466
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.
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.
358
473
<refsect1 id="environment">
359
474
<title>ENVIRONMENT</title>
477
<term><envar>MANDOSPLUGINHELPERDIR</envar></term>
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.
361
This program does not use any environment variables, not even
362
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
363
491
>cryptsetup</refentrytitle><manvolnum>8</manvolnum>
496
<refsect1 id="network-hooks">
497
<title>NETWORK HOOKS</title>
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
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.
514
<refsect2 id="hook-requirements">
515
<title>REQUIREMENTS</title>
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.
522
A network hook will receive one argument, which can be one of
527
<term><literal>start</literal></term>
530
This should make the network hook create (if necessary)
531
and bring up a network interface.
536
<term><literal>stop</literal></term>
539
This should make the network hook take down a network
540
interface, and delete it if it did not exist previously.
545
<term><literal>files</literal></term>
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.
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
563
<term><literal>modules</literal></term>
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
571
<quote><literal>tun</literal></quote> module.
577
The network hook will be provided with a number of environment
582
<term><envar>MANDOSNETHOOKDIR</envar></term>
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.
595
<term><envar>DEVICE</envar></term>
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.
608
<term><envar>MODE</envar></term>
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>.
620
<term><envar>VERBOSITY</envar></term>
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>.
631
<term><envar>DELAY</envar></term>
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>.
643
<term><envar>CONNECT</envar></term>
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>.
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>.
368
665
<refsect1 id="files">
369
666
<title>FILES</title>