NAME
----
-rrqnet-ifupdown.sh - an ifupdown script to uphold rrqnet cables with
-iup and ifdown
+rrqnet-ifupdown.sh - script for managing rrqnet virtual cables with
+ifup 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
+ for HOOKD in down post-down pre-up up ; do
+ ln -s /etc/rrqnet/ifupdown.sh /etc/network/if-$HOOKD.d/rrqnet
+ done
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.
+*/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 hook script by means of links from all
++/etc/network/if-*.d/rrqnet+ for automatic invocation with the
+commands +ifup+ and +ifdown+.
-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.
+A +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 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:
+This script handles the special purpose "option codes" for the IFACE
+blocks that are used for declaring the +rrqnet+ daemon configuration
+to for the +tap+ interface for its virtual cabling. I.e., the IFACE
+block is made for the tap interface and it includes one or more of
+these +rrqnet+ options.
-*rrqnet_port* _port_::
+The list of IFACE options for +rrqnet+ are:
-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_port* [ notap ] _port_::
+
+This IFACE option is required both as way of marking that the
+configuration block is for an +rrqnet+ virtual cable +tap+, and to
+declare which UDP port the +rrqnet+ daemon should listen on for
+incoming cabling. The port number may be preceded by +notap+ to
+indcate that this +rrqnet+ should not have an actual tap interface on
+the host but rather only serve to interconnect remote connections.
+
+*rrqnet_nice* _nice_::
+
+This IFACE option is used for adjusting the +rrqnet+ process
+scheduling priority. Refer the +nice+ man page for full details.
*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 ([-tpg] [-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.
+
+*rrqnet_dhcp* _method args_::
+
+This IFACE option is used for attaching a DHCP client to the
+interface. The +method+ identifies the DHCP client method, and
+currently only the +dhclient+ method is defined, which is run as
+follows:
++
+----
+dhclient -pf $PIDFILE $DHCPARGS -lf $LEASES $IFACE
+----
++
+The given +args+ if non-empty replaces +$DHCPARGS+, which by default
+are "-4 -cf /dev/null". Refer to the +dhclient+ man page for details.
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 IFACE block 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,
+in addition to the socket reader threads. The default is to use an
+ipv6 socket, 10 bufffers and 5 delivery 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
--------
- *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
-
+*brctl(8)* - ethernet bridge administration
+
+*daemon(1)* - turns other processes into daemons
+
+*dhclient(8)* - Dynamic Host Configuration Protocol Client
+
+*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 / blobdiff