X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=rrqnet-ifupdown.sh.8.adoc;h=3bca61683f4b3f683d7a3b65dd0357cf5393e5df;hb=a6238294b80a2d98d3768131a457d00f4b2b9578;hp=1b83f841455b17f2edfd424aa83a15c37bb2aa7a;hpb=9e5edbcfd86721168d8f3dcde603d42323e875e1;p=rrq%2Frrqnet.git diff --git a/rrqnet-ifupdown.sh.8.adoc b/rrqnet-ifupdown.sh.8.adoc index 1b83f84..3bca616 100644 --- a/rrqnet-ifupdown.sh.8.adoc +++ b/rrqnet-ifupdown.sh.8.adoc @@ -5,68 +5,98 @@ rrqnet-ifupdown.sh(8) 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+. ++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: ---- @@ -74,42 +104,48 @@ iface mynet0 inet static address 10.0.0.2/24 broadcast 10.0.0.255 rrqnet_port 3636 - rrqnet_options -4 + 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. +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 -24 or 48 bytes (for ipv4 and ipv6 respectively). This may cause packet -fragmentation of the tunneling packets unless the associated +tap+ is -configured with that much smaller MTU than the real traffic. +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 -------- - *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 +*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 ------