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
+*rrqnet-cron.sh* is a management script for upholding an *rrqnet* plug
+for a nominated VPN confguration. The given _vpn_ (or the 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:
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+.
+That "server" declaration 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 that forwards packets
+between connections as well as to and from the tap. 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.
The +VPN+ variable may have multiple remote declarations, and include
both up-links and down-links, with or without thransport encryption
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).
+A VPN assignment like the above would downlink remotes in IP range
++192.168.0.0/16+, port 1400, without transport key, and uplink to
++10.61.4.72:2020+.
crontab set up
~~~~~~~~~~~~~~
The script *rrqnet-cron.sh* is intended to be set up in *crontab*, by
-a line as follows:
+a line such as the following:
----
* * * * * /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.
+ensuring that the *rrqnet* plug declared by
++/etc/rrqnet/conf.d/tap0-client.conf+ is still running or otherwise
+restart it.
NOTES
-----
Note that *rrqnet-cron.sh* sources the configuration file and exits
-after optionally spawning a *rrqnet* daemon. On may therefore safely
+after optionally spawning an *rrqnet* daemon. On may therefore safely
just change the cable set up, and kill *rrqnet* in order apply that
changed set up.
NAME
----
-rrqnet-ifupdown.sh - an ifupdown script to uphold rrqnet cables with
+rrqnet-ifupdown.sh - script for managing rrqnet virtual cables with
iup and ifdown
SYNOPSIS
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:
+*/etc/rrqnet/ifupdown.sh* is a utility script for managing +rrqnet+
+virtual cables via +/etc/network/interfaces+ declarations. In normal
+use the script is set up as "pre-up" and "post-down" scripts by means
+of links from +/etc/network/if-pre-up.d/rrqnet+ and from
++/etc/network/if-post-down.d/rrqnet+. It will then be invoked by
++ifup+ and +ifdown+ for handling the +rrqnet+ declarations and bring
+up or tear down +rrqnet+ virtual cable plugs over +tap+ interfaces.
+
+An +rrqnet+ virtual cable uses a +tap+ interface at each cable end
+host, and a service process (aptly named +rrqnet+) to tunnel the +tap+
+network traffic over UDP. Each +rrqnet+ process acts as a networking
+switch that facilitates level 2 connectivity among all its end points
+with packet routing according to the destination Ethernet machine
+addresses.
+
+This script handles the special purpose "option codes" for the IFACE
+stanzas that are used for declaring the +rrqnet+ daemon configuration
+to for the +tap+ interface for its virtual cabling. I.e., the IFACE
+stanza is made for the tap interface and it includes one or more of
+these +rrqnet+ options.
+
+The list of IFACE options for +rrqnet+ 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.
+This IFACE option is required both as way of marking that the stanza
+is for an +rrqnet+ virtual cable +tap+, and to declare which UDP port
+the +rrqnet+ daemon should listen on for incoming 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
+remotes for a single +rrqnet+ daemon 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.
+This IFACE option is used for declaring any additional +rrqnet+ daemon
+settings ([-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+ daemon 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].
+This IFACE option is only used to make the +tap+ (once created) to be
+made a "port" of the nominated preceding +bridge+ interface. The same
+things is achieved by including the +tap+ in the +bridge_ports+ list
+of the bridge, provided that the +tap+ is created before the bridge.
EXAMPLES
--------
-The virtual cabling requires configurations for all +rrqnet+ processes
-This script handles the particular configuration
The following is a configuration example:
----
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.
+The above example declares a virtual cable plug for UDP port +3636+
+tunneling through host +111.222.333.444+ port +3636+ where the local
++tap+ +mynet0+ has ipv4 address +10.0.0.2+. The +rrqnet_port+ option
+marks the stanza as an ++rrqnet+ virtual cabling set up which then is
+duly handled by +rrqnet-ifupdown.sh+.
+
+The +rrqnet_options+ in the example tells the +rrqnet+ process to use
+an ipv4-only socket, 10 packet buffers and a single delivery thread.
+If left out, the default is to use an ipv6 socket, 10 bufffers and 5
+threads.
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
+This script creates the +tap+ interface if needed, and brings it up.
+Thereafter, 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.
+Note that the +rrqnet+ virtual cable requires UDP networking for its
+tunnel traffic. The tunnel packets will have a UDP header in addition
+to the orignal packet, which means that packets grow with some 28/48
+(ipv4/6) bytes.
SEE ALSO
--------
* When a tap is used, stdin and stdout are closed, but stderr remains
open.
-* Without a *-t* argument, *rrqnet* will merely operate as a virtual
-switch among its channels.
-
* With "*-*" as tap name, *rrqnet* will use stdin/stdout as local
networking channel in a format compatible with VDE plugs.
+* Without a *-t* argument, *rrqnet* will operate merely as a virtual
+cable switch among its channels.
+
_address-block[:port][=cryptfile]_ [ *-i* _mac_[,_mac_]* ]::
Remotes are declared as +ipv4+ or +ipv6+ network address blocks
*rrqnet* includes logic aiming to protect against broadcast cycles.
Howewer it does not have the more advanced spanning tree logic that is
-offered by bridge interfaces. In general it's best to avoid cycles and
-rather run several *rrqnet* on a host with their local taps connected
-in a bridge interface.
+offered by bridge interfaces. In general it's probably best to avoid
+cabling cycles and perhaps rather run several *rrqnet* on a host with
+their taps connected with a bridge interface. Though, multiple virtual
+cabling paths between hosts might increase connection reliability.
By default *rrqnet* opens an +ipv6+ socket on the given port. This
mode handles both +ipv6+ and +ipv4+ remotes with +ipv4+ remotes
-handled by means of ipv6-mapped address translations. If *-4* is
-given, *rrqnet* opens an +ipv4+ socket instead, and it cannot then
-have +ipv6+ remotes.
+handled by means of standard ipv6-mapped address translations. If *-4*
+is given, *rrqnet* opens a plain +ipv4+ socket instead, and it cannot
+then have +ipv6+ remotes.
-A *rrqnet* daemon delivers the packets received from the local end,
+An *rrqnet* daemon delivers the packets received from the local end,
i.e., the _tap_ or _stdio_, to known remote ends according the
-targeted MAC addresses and established remote channels. Likewise,
-packets from remotes are delivered to the local end or to other
-remotes according to the targeted MAC addresses. If a packet is an
-Ethernet broadcast, it is delivered to all (known) channels except the
-one it came from.
+targeted MAC addresses through its established remote channels.
+Likewise, packets from remotes are delivered to the local end or to
+other remotes according to the targeted MAC addresses. If a packet is
+an Ethernet broadcast, it is delivered to all (known) channels except
+the one it came from.
If *rrqnet* is started without *-t* option it will operate like an
Ethernet switch that provides connectivity among its +UDP+ channels
This format declares remotes by +ipv4+ address, with optional network
prefix length (0-32), optional port (1-65535) and/or optional key file
-pathname. *rrqnet* will accept packets from sources that match. If the
-network prefix length, +n+, is omitted or given as 32, and a port is
-given, then the remote is taken as an _uplink_.
+pathname. *rrqnet* will accept packets from sources that match by
+prefix. If the network prefix length, +n+, is omitted or given as 32,
+and a port is given, then it declares an _uplink_.
.matching ipv4 uplink and downlink
====
This format declares remotes by ipv6 address, with optional network
prefix length (0-128) and/or optional key file pathname. *rrqnet* will
-accept packets from sources that match. This format (without square
-brackets) is without port number part, and it thus only declares a
-prefix mask for allowed sender hosts.
+accept packets from sources that match by prefix. This format (without
+square brackets) is without port number part, and it thus only
+declares a prefix mask for allowed remote hosts.
.ipv6 address block within square brackets
This format declares remotes by ipv6 address, with optional network
prefix length (0-128) within square brackets, then optionally a port
number and/or an optional key file pathname. *rrqnet* will accept
-packets from sources that match. If the network prefix length, +n+, is
-omitted, or given as 128, and a port number is given, then it declares
-an _uplink_.
+packets from sources that match by prefix. If the network prefix
+length, +n+, is omitted, or given as 128, and a port number is given,
+then it declares an _uplink_.
.matching ipv6 uplink and downlink
====
----
====
-Remotes are declarations to match the source IP addresses for UDP
-traffic. It is either a full host and port address, or an address
-block with or without port number. A full network address and port
+The remote declarations define by prefix match the allowed source IP
+addresses for incoming UDP traffic. A full network address and port
(e.g +[fe::1:4]:2300+ of example 2) declares an _uplink_ that the
-declaring *rrqnet* daemon will establish and maintain by means of
-regular heartbeat messaging. An address block declaration defines the
-mask for allowed incoming connections, aka _downlinks_, that teh
-declaring dameon expects are maintained as uplinks by the remote
-*rrqnet* daemons.
+*rrqnet* daemon will establish and maintain by means of regular
+"heartbeat" messaging. Other declarations define the mask for allowed
+incoming connections, aka _downlinks_, that the dameon expects the
+remote end to maintain as uplinks by the remote *rrqnet* daemons.
+
+Two (or more) +rrqnet+ plugs may be set up with uplink connections to
+each other in which case both (all) of them maintain the link.
+
+.example of multiple pair-wise uplinks
+====
+----
+[1.0.0.1]# rrqnet -t vpn0 2300 2.0.0.1:2300 3.0.0.1:2300 4.0.0.1:2300
+[2.0.0.1]# rrqnet -t vpn0 2300 1.0.0.1:2300 3.0.0.1:2300 4.0.0.1:2300
+[3.0.0.1]# rrqnet -t vpn0 2300 2.0.0.1:2300 1.0.0.1:2300 4.0.0.1:2300
+[4.0.0.1]# rrqnet -t vpn0 2300 2.0.0.1:2300 3.0.0.1:2300 1.0.0.1:2300
+----
+====
The *-i* option, if used for a remote declaration, is followed by a
comma separated list of the MAC addresses to ignore on the associated
TRANSPORT ENCRYPTION
--------------------
-Transport encryption is added to a channel by menas of using a shared
+Transport encryption is added to a channel by means of using a shared
key. This is a sizable file, say 1 Mb, of binary data that is used for
scrambling the network packets. For example, 1 Mb random data is fine.
That declaration says that all channels with hosts of ipv4 address
+10.2.0.0/16+, port 1400, use the file +/sec/keyfile+ for transport
-encryption.
-
+encryption. This may also be used as way of restricting remote
+connections to those that use the right key.
FURTHER EXAMPLES
----------------
Simple rrqnet set up (ipv6)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This is an example set up for connecting two hosts with *rrqnet*,
-without transport encryption. We pretend these hosts are mutually
-reachable with ipv6 addresses +fe::2+ and +fe::1:3+ respectively, and
-we want to use the ipv6 network +fd::1000:0/120+ over *rrqnet*. A
-nominal set up might then be as follows:
+This is an example of connecting two hosts with *rrqnet* without
+transport encryption. We pretend these hosts are mutually reachable
+with ipv6 addresses +fe::2+ and +fe::1:3+ respectively, and we want to
+use the ipv6 network +fd::1000:0/120+ over *rrqnet*. A nominal set up
+might then be as follows:
.simple rrqnet set up (ipv6)
====
----
====
-Thus, the host +fe::2+ is set up with a tap, +tap0+, having +ipv6+
-address and net +fd::1000:10/120+, and a *rrqnet* daemon for the tap
-and UDP port +1400+ that uplinks to a remote *rrqnet* at +fe::1:3+
-port +1400+. Similarly, the host +fe::1:3+ is set up with a tap
-+tap0+, having +ipv6+ address and net +fd::1000:20/120+, and a *rrqnet*
-daemon for the tap and UDP port +1400+ that uplinks to a remote
-*rrqnet* at +fe::2+ port +1400+.
+Thus, the host +fe::2+ is set up with a tap +tap0+ having ipv6 address
++fd::1000:10/120+, and an *rrqnet* daemon for the tap using UDP port
++1400+ and an uplink +fe::1:3+ port +1400+. Similarly, the host
++fe::1:3+ is set up with a tap +tap0+ having ipv6 address
++fd::1000:20/120+, and an *rrqnet* daemon for the tap using UDP port
++1400+ and an uplink (back) to +fe::2+ port +1400+.
This example also needs ipv6 address resolution set up, which uses the
MAC addresses of the two taps. Let's say it's +02:00:00:00:00:02+ for
Simple rrqnet set up (ipv4)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This is an example set up for connecting two hosts with *rrqnet*,
-without transport encryption. We pretend these hosts are mutually
-reachable with ipv4 addresses +10.0.0.1+ and +192.168.0.1+
-respectively, and we want to use the ipv4 network +10.100.100.0/24+
-over *rrqnet*. A nominal set up might be as follows:
+This is an example of connecting two hosts with *rrqnet* without
+transport encryption. We pretend these hosts are mutually reachable
+with ipv4 addresses +10.0.0.1+ and +192.168.0.1+ respectively, and we
+want to use the ipv4 network +10.100.100.0/24+ over *rrqnet*. A
+nominal set up might be as follows:
.Simple rrqnet set up (ipv4)
====
----
====
-Thus, the host +10.0.0.1+ is set up with a tap, +tap0+, having ipv4
-address and net +10.100.100.1/24+, and a *rrqnet* daemon for the tap
-and UDP port +1400+ that uplinks to a remote *rrqnet* at +192.168.0.1+
-port +1400+. Similarly, the host +192.168.0.1+ is set up with a tap
-+tap0+, having +ipv4+ address and net +10.100.100.2/24+, and a
-*rrqnet* daemon for the tap and UDP port +1400+ that uplinks to a
-remote *rrqnet* at +10.0.0.1+ port 1400.
+Thus, the host +10.0.0.1+ is set up with a tap +tap0+ having ipv4
+address +10.100.100.1/24+, and an *rrqnet* daemon for the tap and UDP
+port +1400+ uplink +192.168.0.1+ port +1400+. Similarly, the host
++192.168.0.1+ is set up with a tap +tap0+ having ipv4 address
++10.100.100.2/24+, and an *rrqnet* daemon for the tap and UDP port
++1400+ and uplink (back) to +10.0.0.1+ port 1400.
The kernel automagically performs ipv4 address resolution to learn the
MAC addresses associated with the remote ipv4 addresses through the
rrqnet set up through NAT
~~~~~~~~~~~~~~~~~~~~~~~~~
-If one of the hosts, say +192.168.0.1+ is behind a NAT router with
-different IP, say, a dynamic IP on the net +10.2.0.0/16+, we need a
+If one of the hosts, say +192.168.0.1+, is behind a NAT router with
+different IP, say a dynamic IP on the net +10.2.0.0/16+, we need a
different set up. In this scenario, the first host would be set up as
a "server" and the second a client that would utilize the router's NAT
function for return traffic. The set up would be as follows:
====
Thus, the "server" is set up to allow connections from any host on the
-network +10.2.0.0/16+, port 1400, while the "client" is set up the
-same way as in the simple example above. The client will establish and
+network +10.2.0.0/16+ port 1400 while the "client" is set up the same
+way as in the simple example above. The client will establish and
uphold the connection by virtue of its 30 second "heart beat", and
return traffic will be channeled via the router's NAT function.
Note that the server sees the _external_ IP of the client and not its
-_internal_ IP. The server's *rrqnet* therefor has a remote declaration
-to allow messages from that external IP, and in the example case, even
-an address block of a 16 bit common prefix (the choice of a 16 bit
-prefix is merely for the sake of this example).
+_internal_ IP. The server's *rrqnet* therefore has a remote
+declaration to allow messages from that external IP. In the example
+case it allows the address block of the 16 bit common prefix (the
+choice of a 16 bit prefix is merely for the sake of this example).
Multiple client hosts
~~~~~~~~~~~~~~~~~~~~~
-In a "client-server" set up, there can be any number of "client"
-hosts. However, the "clients" behind a common NAT router must then use
+In a "client-server" set up there can be any number of "client" hosts.
+However, the "clients" behind a common NAT router must then use
distinct ports as otherwise the router will be confused about the
return traffic.
-With multiple remote channels, a *rrqnet* daemon serves as a network
+With multiple remote channels, an *rrqnet* daemon serves as a network
switch that forwards traffic in between the channels as well as to and
from the "server" tap. The daemon also forwards Ethernet broadcasts
out on all established channels in support of ARP messaging.
-Further, a *rrqnet* daemon may be both a "server" with down-link
+Further, an *rrqnet* daemon may be both a "server" with down-link
channels, and a "client" with one or more up-link channels, all at the
same time. Such a daemon forwards traffic between all established
channels by means of the Ethernet addresses, as well as broadcasts
-onto all channels
+onto all channels.
Stdio network
~~~~~~~~~~~~~
-The *rrqnet* daemon may be set up to use standard input/output rather
-than a tap for local network traffic. This operation mode has some
-rare use cases, such as linking two *rrqnet* daemons, or connecting to
-a VDE network. For example:
+The *rrqnet* daemon may be configured to use standard input/output
+rather than a tap for local network traffic. This operation mode has
+more rare use cases, such as linking two *rrqnet* daemons or
+connecting to a VDE network. For example:
.stdio network between two rrqnet plugs
====
----
====
-That example set up would make a connection between the two "server"
-daemons operating at different UDP ports, accepting messages from any
-ipv4 host, where port +1400+ has +keyfile0+ for transport encryption,
-and +1401+ has +keyfile1+ for transport encryption.
+The example above connects the two "server" +rrqnet+ daemons operating
+at different UDP ports, each accepting messages from any ipv4 host.
+Port +1400+ has +keyfile0+ for transport encryption, and +1401+ has
++keyfile1+ for transport encryption.
-Another example would be for connecting the *rrqnet* traffic to a VDE
-network via a +vde_plug+ as in the following example:
+The follwoing, different, example connects the *rrqnet* traffic to a
+VDE network via a +vde_plug+:
.stdio network to a vde_plug
====
ends only, but it doesn't perform any payload verification. Messages
smaller than 12 bytes are taken as "heartbeats", and larger messages
are first decrypted as applicable, then treated as Ethernet messages
-and delivered according to their destination MAC addresses. *rrqnet*
-versions after 0.2.3 adds some data to the Ethernet packet in the UDP
-communication.
+and delivered according to their destination MAC addresses.
*rrqnet* bridges its connections, and forwards Ethernet broadcasts to
all known end-points except the incoming one. The input logic takes
timing logic based on binding MAC addresses to remotes. That binding
is sticky for a short time: 6s for broadcast and 20s for unicast. Any
packet received during that time from the same MAC address via another
-remote is dropped. Also, a downlink without incoming traffic for 3
-minutes is considered stale.
+remote is dropped. Also, downlinks without incoming traffic for 3
+minutes are considered stale.
*rrqnet* sends a "heartbeat" of an empty UDP message on its uplinks
every 30 seconds. This is done in order to maintain the channel with
projects / rrq / rrqnet.git / commitdiff