MAN8DIR = $(DESTDIR)/usr/local/share/man/man8
SBINFILES = rrqnet rrqnet-cron.sh
-ETCFILES = set-source-route.sh
+ETCFILES = set-source-route.sh ifupdown.sh
MAN1FILES =
-MAN8FILES = rrqnet.8 rrqnet-cron.sh.8
+MAN8FILES = rrqnet.8 rrqnet-cron.sh.8 rrqnet-ifupdown.sh.8
HTMLDOC = $(MAN8FILES:%=%.html)
+.PHONY: ifupdown.sh
+
all: $(SBINFILES) $(ETCFILES) $(MAN1FILES) $(MAN8FILES) $(HTMLDOC)
+squeezetest: squeeze.c squeezetest.c
+
$(HTMLDOC): %.html: %.adoc
asciidoc -bhtml $^
$(addprefix $(ETCDIR)/,conf.d keys):
mkdir -p $@
-$(ETCCFG)/cron.sh: rrqnet-cron.sh
+$(ETCDIR)/ifupdown.sh: rrqnet-ifupdown.sh
$(INSTALL) -D -T $< $@
$(SBINDIR)/% $(ETCDIR)/% $(MAN1DIR)/% $(MAN8DIR)/%: %
--- /dev/null
+#!/bin/sh
+#
+# Control script for starting or stopping an rrqnet virtual cable via
+# ifup/ifdown. To use this, you need firstly to links to this script
+# set up as /etc/network/if-pre-up.d/rrqnet and
+# /etc/network/if-down.d/rrqnet. Secondly, you need a stanza in
+# /etc/network/interfaces for the cabling tap and its associated
+# configuration settings.
+#
+# "rrqnet name" is the primary stanza key, which result in
+# a creation of a tap by that name, supported by an rrqnet plug
+# according to the setup in /etc/rrqnet/conf.d/name.conf
+
+#echo '===========' >> /tmp/FOO
+#env >> /tmp/FOO
+
+# Verify that it's an rrqnet stanza
+[ -z "$IF_RRQNET_PORT" ] && exit 0
+
+# An rrqnet stanza may have the following settings:
+# rrqnet_port <port>
+# rrqnet_remote <remote declaration>
+# rrqnet_options <options>
+# rrqnet_log <level> <pathname>
+# rrqnet_bridge <bridge>
+
+: ${RRQDAEMON:=/usr/local/sbin/rrqnet}
+: ${NAME:=rrqnet-${IFACE}}
+
+#function
+configure_tap_bridge() {
+ [ -z "$IF_RRQNET_BRIDGE" ] && return 0
+ brctl show $IF_RRQNET_BRIDGE | grep -wq $IFACE && return 0
+ brctl addif $IF_RRQNET_BRIDGE $IFACE
+}
+
+#function
+configure_tap_up() {
+ ( ip link show $IFACE 2>/dev/null || ip tuntap add $IFACE mode tap ) | \
+ grep -q "state UP" || ip link set dev $IFACE up
+}
+
+#function
+start_cable_pre_up() {
+ configure_tap_up || return 1
+ configure_tap_bridge || return 1
+ if [ -z "$IF_RRQNET_LOG" ] ; then
+ daemon -U -r -n $NAME -- \
+ $RRQDAEMON $IF_RRQNET_OPTIONS \
+ -t $IFACE $IF_RRQNET_PORT $IF_RRQNET_REMOTE
+ else
+ daemon -U -r -n $NAME -E "${IF_RRQNET_LOG#* }" -- \
+ $RRQDAEMON ${IF_RRQNET_LOG%% *} $IF_RRQNET_OPTIONS \
+ -t $IFACE $IF_RRQNET_PORT $IF_RRQNET_REMOTE
+ fi
+}
+
+#function
+stop_cable_post_down() {
+ daemon -n $NAME --stop
+}
+
+# main script body
+
+case "$MODE-$PHASE" in
+ start-pre-up) start_cable_pre_up ;;
+ start-post-up) : ;;
+ stop-pre-down) : ;;
+ stop-post-down) stop_cable_post_down ;;
+esac
--- /dev/null
+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>
projects / rrq / rrqnet.git / commitdiff