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 - an ifupdown script to uphold rrqnet cables with
   9 iup 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 upholding +rrqnet+
  20 virtual cables via +/etc/network/interfaces+. The script is set up
  21 as both "pre-up" and "post-down" scripts for handling the associated
  22 +rrqnet+ configurations to bring up and tear down virtual cable plugs
  23 over +tap+ interfaces.
  24
  25 An +rrqnet+ virtual cable uses +tap+ interfaces at each cable end
  26 host, which also have the service processes, aptly named +rrqnet+, to
  27 forward network traffic over UDP. Each +rrqnet+ process acts as a
  28 networking switch that facilitates level 2 connectivity among all its
  29 end points according to the Ethernet machine addresses of the packets.
  30
  31 This script implements additional option codes for the IFACE stanzas
  32 for declaring the configuration of the +rrqnet+ daemon that should use
  33 a +tap+ interface for its virtual cabling. The list of options are:
  34
  35 *rrqnet_port* _port_::
  36
  37 This IFACE option is required both as way of identifying the stanza as
  38 an +rrqnet+ virtual cable +tap+, and to declare which UDP port to use
  39 for incomming cabling.
  40
  41 *rrqnet_remote* _remote_::
  42
  43 This IFACE option is used for declaring the remote connection details.
  44 Refer to +rrqnet+ man page for the full specification. Multiple
  45 remotes for a single +rrqnet+ process are declared by using multiple
  46 +rrqnet_remote+ lines.
  47
  48 *rrqnet_options* _options_::
  49
  50 This IFACE option is used for declaring any additional rrqnet
  51 configuration options ([-4] [-B n] [-T n] [-m mcast]). Refer to the
  52 +rrqnet+ man page for the full specification.
  53
  54 *rrqnet_log* _level_ _pathname_::
  55
  56 This IFACE option is used for declaring the log level as one of +-v+,
  57 +-vv+ or +-vvv+, and to nominate the log file. If omitted, all the
  58 +rrqnet+ process output will be directed to +/dev/null+. If
  59 __pathname_ is of the form "facility.priority", then stderr is sent to
  60 +syslog+. Otherwise, stderr is appended to the nominated file.
  61
  62 *rrqnet_bridge* _bridge_::
  63
  64 This IFACE option is used if needed, to make the +tap+ once created to
  65 be mad a "port" of the nominated preceding +bridge+ interface [3].
  66
  67 EXAMPLES
  68 --------
  69
  70 The virtual cabling requires configurations for all +rrqnet+ processes
  71 This script handles the particular configuration
  72 The following is a configuration example:
  73
  74 ----
  75 iface mynet0 inet static
  76     address 10.0.0.2/24
  77     broadcast 10.0.0.255
  78     rrqnet_port 3636
  79     rrqnet_options -4 -B 10 -T 1
  80     rrqnet_remote 111.222.333.444:3636=/sec/mynet.key
  81     rrqnet_log -v /var/log/mynet0.log
  82 ----
  83
  84 The illustration example is of a virtual cable plug using port +3636+
  85 for UDP tunneling through host +111.222.333.444+, port +3636+, where
  86 the local +tap+, named +mynet0+, has ipv4 address +10.0.0.2+. The
  87 +rrqnet_port+ option is understood to identify the stanza as a virtual
  88 cabling set up which then is duly handled by +rrqnet-ifupdown.sh+, and
  89 all its options are used for declaring that tunneling. The
  90 +rrqnet_options+ in the example tells the +rrqnet+ process to use an
  91 ipv4-only socket, 10 packet buffers and a single delivery thread.
  92
  93 NOTES
  94 -----
  95
  96 The script creates a +tap+ interface if needed, and brings it up as
  97 needed. Then if so configured, the +tap+ is added to the +bridge+, and
  98 then the +rrqnet+ virtual cable process is started under a +daemon+
  99 supervision.
 100
 101 Note that the +rrqnet+ virtual cable requires real networking for its
 102 UDP tunnel traffic. The real packets will have a UDP header in
 103 addition to the orignal packet, which means that it grows packets with
 104 some 28/48 (ipv4/6) bytes. This may cause packet fragmentation of the
 105 tunneling packets which might be mitigated by configuring the
 106 associated +tap+ that much smaller MTU.
 107
 108 SEE ALSO
 109 --------
 110
 111  *brctl(8)* - ethernet bridge administration
 112  *daemon(1)* - turns other processes into daemons
 113  *interfaces(5)* - network interface configuration for ifup and ifdown
 114  *rrqnet(8)* - packet tunneling over UDP, multiple channels
 115
 116 AUTHOR
 117 ------
 118 Ralph Rönnquist <ralph.ronnquist@gmail.com>