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