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

NAME
----
rrqnet-ifupdown.sh - an ifupdown script to uphold rrqnet cables with
iup and ifdown

SYNOPSIS
--------
 ln -s /etc/rrqnet/ifupdown.sh /etc/network/if-post-down.d/rrqnet
 ln -s /etc/rrqnet/ifupdown.sh /etc/network/if-pre-up.d/rrqnet

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

*/etc/rrqnet/ifupdown.sh* is a utility script for upholding +rrqnet+
virtual cables via +/etc/network/interfaces+. The script is set up
as both "pre-up" and "post-down" scripts for handling the associated
+rrqnet+ configurations to bring up and tear down virtual cable plugs
over +tap+ interfaces.

An +rrqnet+ virtual cable uses +tap+ interfaces at each cable end
host, which also have the service processes, aptly named +rrqnet+, to
forward network traffic over UDP. Each +rrqnet+ process acts as a
networking switch that facilitates level 2 connectivity among all its
end points according to the Ethernet machine addresses of the packets.

This script implements additional option codes for the IFACE stanzas
for declaring the configuration of the +rrqnet+ daemon that should use
a +tap+ interface for its virtual cabling. The list of options are:

*rrqnet_port* _port_::

This IFACE option is required both as way of identifying the stanza as
an +rrqnet+ virtual cable +tap+, and to declare which UDP port to use
for incomming cabling.

*rrqnet_remote* _remote_::

This IFACE option is used for declaring the remote connection details.
Refer to +rrqnet+ man page for the full specification. Multiple
remotes for a single +rrqnet+ process are declared by using multiple
+rrqnet_remote+ lines.

*rrqnet_options* _options_::

This IFACE option is used for declaring any additional rrqnet
configuration options ([-4] [-B n] [-T n] [-m mcast]). Refer to the
+rrqnet+ man page for the full specification.

*rrqnet_log* _level_ _pathname_::

This IFACE option is used for declaring the log level as one of +-v+,
+-vv+ or +-vvv+, and to nominate the log file. If omitted, all the
+rrqnet+ process output will be directed to +/dev/null+. If
__pathname_ is of the form "facility.priority", then stderr is sent to
+syslog+. Otherwise, stderr is appended to the nominated file.

*rrqnet_bridge* _bridge_::

This IFACE option is used if needed, to make the +tap+ once created to
be mad a "port" of the nominated preceding +bridge+ interface [3].

EXAMPLES
--------

The virtual cabling requires configurations for all +rrqnet+ processes
This script handles the particular configuration 
The following is a configuration example:

----
iface mynet0 inet static
    address 10.0.0.2/24
    broadcast 10.0.0.255
    rrqnet_port 3636
    rrqnet_options -4 -B 10 -T 1
    rrqnet_remote 111.222.333.444:3636=/sec/mynet.key
    rrqnet_log -v /var/log/mynet0.log
----

The illustration example is of a virtual cable plug using port +3636+
for UDP tunneling through host +111.222.333.444+, port +3636+, where
the local +tap+, named +mynet0+, has ipv4 address +10.0.0.2+. The
+rrqnet_port+ option is understood to identify the stanza as a virtual
cabling set up which then is duly handled by +rrqnet-ifupdown.sh+, and
all its options are used for declaring that tunneling. The
+rrqnet_options+ in the example tells the +rrqnet+ process to use an
ipv4-only socket, 10 packet buffers and a single delivery thread.

NOTES
-----

The script creates a +tap+ interface if needed, and brings it up as
needed. Then if so configured, the +tap+ is added to the +bridge+, and
then the +rrqnet+ virtual cable process is started under a +daemon+
supervision.

Note that the +rrqnet+ virtual cable requires real networking for its
UDP tunnel traffic. The real packets will have a UDP header in
addition to the orignal packet, which means that it grows packets with
some 28/48 (ipv4/6) bytes. This may cause packet fragmentation of the
tunneling packets which might be mitigated by configuring the
associated +tap+ that much smaller MTU.

SEE ALSO
--------

 *brctl(8)* - ethernet bridge administration
 *daemon(1)* - turns other processes into daemons
 *interfaces(5)* - network interface configuration for ifup and ifdown
 *rrqnet(8)* - packet tunneling over UDP, multiple channels
 
AUTHOR
------
Ralph Rönnquist <ralph.ronnquist@gmail.com>