rrqnet-ifupdown.sh.8.adoc

   1 rrqnet-ifupdown.sh(8)
   2 =====================
   3 :doctype: manpage
   4 :revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
   5
   6 NAME
   7 ----
   8 rrqnet-ifupdown.sh - script for managing rrqnet virtual cables with
   9 ifup and ifdown
  10
  11 SYNOPSIS
  12 --------
  13  for HOOKD in down post-down pre-up up ; do
  14      ln -s /etc/rrqnet/ifupdown.sh /etc/network/if-$HOOKD.d/rrqnet
  15  done
  16
  17 DESCRIPTION
  18 -----------
  19
  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 "pre-up" and "post-down" scripts by means
  23 of links from +/etc/network/if-pre-up.d/rrqnet+ and from
  24 +/etc/network/if-post-down.d/rrqnet+. It will then be invoked by
  25 +ifup+ and +ifdown+ for handling the +rrqnet+ declarations and bring
  26 up or tear down +rrqnet+ virtual cable plugs over +tap+ interfaces.
  27
  28 An +rrqnet+ virtual cable uses a +tap+ interface at each cable end
  29 host, and a service process (aptly named +rrqnet+) to tunnel the +tap+
  30 network traffic over UDP. Each +rrqnet+ process acts as a networking
  31 switch that facilitates level 2 connectivity among all its end points
  32 with packet routing according to the destination Ethernet machine
  33 addresses.
  34
  35 This script handles the special purpose "option codes" for the IFACE
  36 stanzas that are used for declaring the +rrqnet+ daemon configuration
  37 to for the +tap+ interface for its virtual cabling. I.e., the IFACE
  38 stanza is made for the tap interface and it includes one or more of
  39 these +rrqnet+ options.
  40
  41 The list of IFACE options for +rrqnet+ are:
  42
  43 *rrqnet_port* _port_::
  44
  45 This IFACE option is required both as way of marking that the stanza
  46 is for an +rrqnet+ virtual cable +tap+, and to declare which UDP port
  47 the +rrqnet+ daemon should listen on for incoming cabling.
  48
  49 *rrqnet_nice* _nice_::
  50
  51 This IFACE option is used for adjusting the +rrqnet+ process
  52 scheduling priority. Refer the +nice+ man page for full details.
  53
  54 *rrqnet_remote* _remote_::
  55
  56 This IFACE option is used for declaring the remote connection details.
  57 Refer to +rrqnet+ man page for the full specification. Multiple
  58 remotes for a single +rrqnet+ daemon are declared by using multiple
  59 +rrqnet_remote+ lines.
  60
  61 *rrqnet_options* _options_::
  62
  63 This IFACE option is used for declaring any additional +rrqnet+ daemon
  64 settings ([-4] [-B n] [-T n] [-m mcast]). Refer to the +rrqnet+ man
  65 page for the full specification.
  66
  67 *rrqnet_log* _level_ _pathname_::
  68
  69 This IFACE option is used for declaring the log level as one of +-v+,
  70 +-vv+ or +-vvv+, and to nominate the log file. If omitted, all the
  71 +rrqnet+ daemon output will be directed to +/dev/null+. If __pathname_
  72 is of the form "facility.priority", then stderr is sent to +syslog+.
  73 Otherwise, stderr is appended to the nominated file.
  74
  75 *rrqnet_bridge* _bridge_::
  76
  77 This IFACE option is only used to make the +tap+ (once created) to be
  78 made a "port" of the nominated preceding +bridge+ interface. The same
  79 things is achieved by including the +tap+ in the +bridge_ports+ list
  80 of the bridge, provided that the +tap+ is created before the bridge.
  81
  82 *rrqnet_dhcp* _method args_::
  83
  84 This IFACE option is used for attaching a DHCP client to the
  85 interface. The +method+ identifies the DHCP client method, and
  86 currently only the +dhclient+ method is defined, which is run as
  87 follows:
  88 +
  89 ----
  90 dhclient -pf $PIDFILE $DHCPARGS -lf $LEASES $IFACE
  91 ----
  92 +
  93 The given +args+ if non-empty replaces +$DHCPARGS+, which by default
  94 are "-4 -cf /dev/null". Refer to the +dhclient+ man page for details.
  95
  96 EXAMPLES
  97 --------
  98
  99 The following is a configuration example:
 100
 101 ----
 102 iface mynet0 inet static
 103     address 10.0.0.2/24
 104     broadcast 10.0.0.255
 105     rrqnet_port 3636
 106     rrqnet_options -4 -B 10 -T 1
 107     rrqnet_remote 111.222.333.444:3636=/sec/mynet.key
 108     rrqnet_log -v /var/log/mynet0.log
 109 ----
 110
 111 The above example declares a virtual cable plug for UDP port +3636+
 112 tunneling through host +111.222.333.444+ port +3636+ where the local
 113 +tap+ +mynet0+ has ipv4 address +10.0.0.2+. The +rrqnet_port+ option
 114 marks the stanza as an ++rrqnet+ virtual cabling set up which then is
 115 duly handled by +rrqnet-ifupdown.sh+.
 116
 117 The +rrqnet_options+ in the example tells the +rrqnet+ process to use
 118 an ipv4-only socket, 10 packet buffers and a single delivery thread.
 119 If left out, the default is to use an ipv6 socket, 10 bufffers and 5
 120 threads.
 121
 122 NOTES
 123 -----
 124
 125 This script creates the +tap+ interface if needed, and brings it up.
 126 Thereafter, if so configured the +tap+ is added to the +bridge+, and
 127 then the +rrqnet+ virtual cable process is started under a +daemon+
 128 supervision.
 129
 130 Note that the +rrqnet+ virtual cable requires UDP networking for its
 131 tunnel traffic. The tunnel packets will have a UDP header in addition
 132 to the orignal packet, which means that packets grow with some 28/48
 133 (ipv4/6) bytes.
 134
 135
 136 SEE ALSO
 137 --------
 138
 139 *brctl(8)* - ethernet bridge administration
 140
 141 *daemon(1)* - turns other processes into daemons
 142
 143 *dhclient(8)* - Dynamic Host Configuration Protocol Client
 144
 145 *interfaces(5)* - network interface configuration for ifup and ifdown
 146
 147 *rrqnet(8)* - packet tunneling over UDP, multiple channels
 148
 149 AUTHOR
 150 ------
 151 Ralph Rönnquist <ralph.ronnquist@gmail.com>