rrqnet-cron.sh.8.adoc

   1 rrqnet-cron.sh(8)
   2 =================
   3 :doctype: manpage
   4 :revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
   5
   6 NAME
   7 ----
   8 rrqnet-cron.sh - Management script to uphold a *rrqnet* plug.
   9
  10 SYNOPSIS
  11 --------
  12 *rrqnet-cron.sh* _vpn_ ...
  13
  14 DESCRIPTION
  15 -----------
  16
  17 *rrqnet-cron.sh* is a management script for upholding a *rrqnet* plug
  18 for a nominated VPN confguration. The given _vpn_, or several, is the
  19 pathname relative to the configuration root directory and with a
  20 +.conf+ extension added, as in +/etc/rrqnet/conf.d/+*vpn*+.conf+.
  21
  22 The following is a configuration file example:
  23
  24 ./etc/rrqnet/conf.d/tap0-client.conf
  25 ----
  26 TAP=tap0
  27 MAC=02:00:00:00:01:00
  28 BR=
  29 IP=192.168.10.2
  30 PORT=1500
  31 OPTIONS=( )
  32 VPN=( 10.61.4.72:2020=/etc/rrqnet/keys/example.key )
  33 VERBOSE=-v
  34 ----
  35
  36  * The `TAP` assignment names the tap interface to use.
  37  * The optional MAC assignment, if provided, tells *rrqnet-cron.sh* to
  38    set the Ethernet address of the tap interface as given.
  39  * The optional `BR` assignment, if provided, tells *rrqnet-cron.sh*
  40    to add the tap interface to the bridge upon start.
  41  * The optional `IP` assignment, if provided, tells *rrqnet-cron.sh*
  42    how to configure the tap interface when it is brought up. If empty,
  43    the tap interface is brought up without confgiured IP address.
  44  * The `PORT` assignment declares which port *rrqnet* should listen
  45    on. It will listen on that port on all interfaces.
  46  * The optional `OPTIONS` is intended for the -B and -T options to
  47    *rrqnet*.
  48  * The `VPN` assignment declares the remotes for *rrqnet*.
  49  * The optional `VERBOSE` assignment, which must be `-v`, `-vv` or
  50    `-vvv` unless empty, defines the verbosity level for *rrqnet*.
  51
  52 The above example declares an uplink remote at example ivp4 address
  53 `10.61.4.72`, port 2020, and using a transport encryption key. The
  54 remote host at that IP address should have a corresponding
  55 declaration, perhaps as follows:
  56
  57 ./etc/rrqnet/conf.d/tap0-server.conf
  58 ----
  59 TAP=tap0
  60 IP=192.168.10.1
  61 PORT=2020
  62 VPN=( 0.0.0.0/0=/etc/rrqnet/keys/example.key )
  63 ----
  64
  65 That "server" declaration is allows UDP packets from any host and
  66 port, requiring the them to use the same transport encryption key. The
  67 *rrqnet* "server" plug then works like a switch, which forwards
  68 packets between connections as well as to and from the tap. Actual
  69 connections are identified by the remote MAC addresses, and it's up to
  70 the remote ends to resolve IP addresses to the MAC addresses on the
  71 virtual net, which in the example would be +192.168.10.0/24+.
  72
  73 The +VPN+ variable may have multiple remote declarations, and include
  74 both up-links and down-links, with or without thransport encryption
  75 keys. E.g.,
  76 ----
  77 VPN=( 192.168.0.0/16:1400 10.61.4.72:2020=/sec/example.key )
  78 ----
  79
  80 A VPN assignment like that would both allow remotes in IP range
  81 +192.168.0.0/16+, port 1400, without transport key, and have an
  82 up-link to that example "server" remote above (though, for the sake of
  83 example, having its key residing at a different pathname).
  84
  85 crontab set up
  86 ~~~~~~~~~~~~~~
  87
  88 The script *rrqnet-cron.sh* is intended to be set up in *crontab*, by
  89 a line as follows:
  90 ----
  91 * * * * * /usr/local/sbin/rrqnet-cron.sh tap0-client
  92 ----
  93
  94 By that *crontab* line, the script will be invoked every minute for
  95 unsuting that the *rrqnet* plug declared by
  96 +/etc/rrqnet/conf.d/tap0-client.conf+, is still running, and otherwise
  97 start or restart it.
  98
  99 The script uses a lock file that gets named by the `TAP` assignment,
 100 as in +/var/lock/rrqnet-tap0+, for the example. This allows an
 101 alternative management set up, for a *rrqnet* cable to be maintained
 102 with an almost immediate restart when it goes down, through a simple
 103 loop like the following:
 104 ----
 105 # while flock /var/lock/rrqnet-tap0 ; do rrqnet-cron.sh tap0 done
 106 ----
 107 That control loop would be waiting for the running *rrqnet* to release
 108 the file lock on +/var/lock/rrqnet-tap0+, and then, almost immediately
 109 restart the virtual cable.
 110
 111 NOTES
 112 -----
 113
 114 Note that *rrqnet-cron.sh* sources the configuration file and exits
 115 after optionally spawning a *rrqnet* daemon. On may therefore safely
 116 just change the cable set up, and kill *rrqnet* in order apply that
 117 changed set up.
 118
 119 SEE ALSO
 120 --------
 121 *rrqnet(8)* - Packet tunneling over UDP, multiple channels
 122
 123 AUTHOR
 124 ------
 125 Ralph Rönnquist <ralph.ronnquist@gmail.com>