rrqnet-cron.sh(8)
=================
:doctype: manpage
:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}

NAME
----
rrqnet-cron.sh - Management script to uphold a *rrqnet* plug.

SYNOPSIS
--------
*rrqnet-cron.sh* _vpn_ ...

DESCRIPTION
-----------

*rrqnet-cron.sh* is a management script for upholding a *rrqnet* plug
for a nominated VPN confguration. The given _vpn_, or several, is the
pathname relative to the configuration root directory and with a
+.conf+ extension added, as in +/etc/rrqnet/conf.d/+*vpn*+.conf+.

The following is a configuration file example:

./etc/rrqnet/conf.d/tap0-client.conf
----
TAP=tap0
MAC=02:00:00:00:01:00
BR=
IP=192.168.10.2
PORT=1500
OPTIONS=( )
VPN=( 10.61.4.72:2020=/etc/rrqnet/keys/example.key )
VERBOSE=-v
----

 * The `TAP` assignment names the tap interface to use.
 * The optional MAC assignment, if provided, tells *rrqnet-cron.sh* to
   set the Ethernet address of the tap interface as given.
 * The optional `BR` assignment, if provided, tells *rrqnet-cron.sh*
   to add the tap interface to the bridge upon start.
 * The optional `IP` assignment, if provided, tells *rrqnet-cron.sh*
   how to configure the tap interface when it is brought up. If empty,
   the tap interface is brought up without confgiured IP address.
 * The `PORT` assignment declares which port *rrqnet* should listen
   on. It will listen on that port on all interfaces.
 * The optional `OPTIONS` is intended for the -B and -T options to
   *rrqnet*.
 * The `VPN` assignment declares the remotes for *rrqnet*.
 * The optional `VERBOSE` assignment, which must be `-v`, `-vv` or
   `-vvv` unless empty, defines the verbosity level for *rrqnet*.

The above example declares an uplink remote at example ivp4 address
`10.61.4.72`, port 2020, and using a transport encryption key. The
remote host at that IP address should have a corresponding
declaration, perhaps as follows:

./etc/rrqnet/conf.d/tap0-server.conf
----
TAP=tap0
IP=192.168.10.1
PORT=2020
VPN=( 0.0.0.0/0=/etc/rrqnet/keys/example.key )
----

That "server" declaration is allows UDP packets from any host and
port, requiring the them to use the same transport encryption key. The
*rrqnet* "server" plug then works like a switch, which forwards
packets between connections as well as to and from the tap. Actual
connections are identified by the remote MAC addresses, and it's up to
the remote ends to resolve IP addresses to the MAC addresses on the
virtual net, which in the example would be +192.168.10.0/24+.

The +VPN+ variable may have multiple remote declarations, and include
both up-links and down-links, with or without thransport encryption
keys. E.g.,
----
VPN=( 192.168.0.0/16:1400 10.61.4.72:2020=/sec/example.key )
----

A VPN assignment like that would both allow remotes in IP range
+192.168.0.0/16+, port 1400, without transport key, and have an
up-link to that example "server" remote above (though, for the sake of
example, having its key residing at a different pathname).

crontab set up
~~~~~~~~~~~~~~

The script *rrqnet-cron.sh* is intended to be set up in *crontab*, by
a line as follows:
----
* * * * * /usr/local/sbin/rrqnet-cron.sh tap0-client
----

By that *crontab* line, the script will be invoked every minute for
unsuting that the *rrqnet* plug declared by
+/etc/rrqnet/conf.d/tap0-client.conf+, is still running, and otherwise
start or restart it.

The script uses a lock file that gets named by the `TAP` assignment,
as in +/var/lock/rrqnet-tap0+, for the example. This allows an
alternative management set up, for a *rrqnet* cable to be maintained
with an almost immediate restart when it goes down, through a simple
loop like the following:
----
# while flock /var/lock/rrqnet-tap0 ; do rrqnet-cron.sh tap0 done
----
That control loop would be waiting for the running *rrqnet* to release
the file lock on +/var/lock/rrqnet-tap0+, and then, almost immediately
restart the virtual cable.

NOTES
-----

Note that *rrqnet-cron.sh* sources the configuration file and exits
after optionally spawning a *rrqnet* daemon. On may therefore safely
just change the cable set up, and kill *rrqnet* in order apply that
changed set up.

SEE ALSO
--------
*rrqnet(8)* - Packet tunneling over UDP, multiple channels

AUTHOR
------
Ralph Rönnquist <ralph.ronnquist@gmail.com>