4 :revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
8 rrqnet-ifupdown.sh - script for managing rrqnet virtual cables with
13 for HOOKD in down post-down pre-up up ; do
14 ln -s /etc/rrqnet/ifupdown.sh /etc/network/if-$HOOKD.d/rrqnet
20 */etc/rrqnet/ifupdown.sh* is a utility script for managing +rrqnet+
21 virtual cables via +/etc/network/interfaces+ declarations. In normal
22 use the script is set up as hook script by means of links from all
23 +/etc/network/if-*.d/rrqnet+ for automatic invocation with the
24 commands +ifup+ and +ifdown+.
26 A +rrqnet+ virtual cable uses a +tap+ interface at each cable end
27 host, and a service process (aptly named +rrqnet+) to tunnel the +tap+
28 network traffic over UDP. Each +rrqnet+ process acts as a networking
29 switch that facilitates level 2 connectivity among all its end points
30 with packet routing according to the destination Ethernet machine
33 This script handles the special purpose "option codes" for the IFACE
34 blocks that are used for declaring the +rrqnet+ daemon configuration
35 to for the +tap+ interface for its virtual cabling. I.e., the IFACE
36 stanza is made for the tap interface and it includes one or more of
37 these +rrqnet+ options.
39 The list of IFACE options for +rrqnet+ are:
41 *rrqnet_port* _port_::
43 This IFACE option is required both as way of marking that the stanza
44 is for an +rrqnet+ virtual cable +tap+, and to declare which UDP port
45 the +rrqnet+ daemon should listen on for incoming cabling.
47 *rrqnet_nice* _nice_::
49 This IFACE option is used for adjusting the +rrqnet+ process
50 scheduling priority. Refer the +nice+ man page for full details.
52 *rrqnet_remote* _remote_::
54 This IFACE option is used for declaring the remote connection details.
55 Refer to +rrqnet+ man page for the full specification. Multiple
56 remotes for a single +rrqnet+ daemon are declared by using multiple
57 +rrqnet_remote+ lines.
59 *rrqnet_options* _options_::
61 This IFACE option is used for declaring any additional +rrqnet+ daemon
62 settings ([-4] [-B n] [-T n] [-m mcast]). Refer to the +rrqnet+ man
63 page for the full specification.
65 *rrqnet_log* _level_ _pathname_::
67 This IFACE option is used for declaring the log level as one of +-v+,
68 +-vv+ or +-vvv+, and to nominate the log file. If omitted, all the
69 +rrqnet+ daemon output will be directed to +/dev/null+. If __pathname_
70 is of the form "facility.priority", then stderr is sent to +syslog+.
71 Otherwise, stderr is appended to the nominated file.
73 *rrqnet_bridge* _bridge_::
75 This IFACE option is only used to make the +tap+ (once created) to be
76 made a "port" of the nominated preceding +bridge+ interface. The same
77 things is achieved by including the +tap+ in the +bridge_ports+ list
78 of the bridge, provided that the +tap+ is created before the bridge.
80 *rrqnet_dhcp* _method args_::
82 This IFACE option is used for attaching a DHCP client to the
83 interface. The +method+ identifies the DHCP client method, and
84 currently only the +dhclient+ method is defined, which is run as
88 dhclient -pf $PIDFILE $DHCPARGS -lf $LEASES $IFACE
91 The given +args+ if non-empty replaces +$DHCPARGS+, which by default
92 are "-4 -cf /dev/null". Refer to the +dhclient+ man page for details.
97 The following is a configuration example:
100 iface mynet0 inet static
104 rrqnet_options -4 -B 10 -T 1
105 rrqnet_remote 111.222.333.444:3636=/sec/mynet.key
106 rrqnet_log -v /var/log/mynet0.log
109 The above example declares a virtual cable plug for UDP port +3636+
110 tunneling through host +111.222.333.444+ port +3636+ where the local
111 +tap+ +mynet0+ has ipv4 address +10.0.0.2+. The +rrqnet_port+ option
112 marks the stanza as an ++rrqnet+ virtual cabling set up which then is
113 duly handled by +rrqnet-ifupdown.sh+.
115 The +rrqnet_options+ in the example tells the +rrqnet+ process to use
116 an ipv4-only socket, 10 packet buffers and a single delivery thread,
117 in addition to the socket reader threads. The default is to use an
118 ipv6 socket, 10 bufffers and 5 delivery threads.
123 This script creates the +tap+ interface if needed, and brings it up.
124 Thereafter, if so configured the +tap+ is added to the +bridge+, and
125 then the +rrqnet+ virtual cable process is started under a +daemon+
128 Note that the +rrqnet+ virtual cable requires UDP networking for its
129 tunnel traffic. The tunnel packets will have a UDP header in addition
130 to the orignal packet, which means that packets grow with some 28/48
137 *brctl(8)* - ethernet bridge administration
139 *daemon(1)* - turns other processes into daemons
141 *dhclient(8)* - Dynamic Host Configuration Protocol Client
143 *interfaces(5)* - network interface configuration for ifup and ifdown
145 *rrqnet(8)* - packet tunneling over UDP, multiple channels
149 Ralph Rönnquist <ralph.ronnquist@gmail.com>