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 by
   9 configuration in +/etc/network/interfaces+.
  10
  11 SYNOPSIS
  12 --------
  13 /etc/network/if-post-down.d/rrqnet -> /etc/rrqnet/ifupdown.sh
  14 /etc/network/if-pre-up.d/rrqnet -> /etc/rrqnet/ifupdown.sh
  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 both as "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+.
  59
  60 *rrqnet_bridge* _bridge_::
  61
  62 This IFACE option is used if needed, to make the +tap+ once created to
  63 be mad a "port" of the nominated preceding +bridge+ interface [3].
  64
  65 EXAMPLES
  66 --------
  67
  68 The virtual cabling requires configurations for all +rrqnet+ processes
  69 This script handles the particular configuration
  70 The following is a configuration example:
  71
  72 ----
  73 iface mynet0 inet static
  74     address 10.0.0.2/24
  75     broadcast 10.0.0.255
  76     rrqnet_port 3636
  77     rrqnet_options -4
  78     rrqnet_remote 111.222.333.444:3636=/sec/mynet.key
  79     rrqnet_log -v /var/log/mynet0.log
  80 ----
  81
  82 The illustration example is of a virtual cable plug using port +3636+
  83 for UDP tunneling through host +111.222.333.444+, port +3636+, where
  84 the local +tap+, named +mynet0+, has ipv4 address +10.0.0.2+. The
  85 +rrqnet_port+ option is understood to identify the stanza as a virtual
  86 cabling set up which then is duly handled by +rrqnet-ifupdown.sh+, and
  87 all its options are used for declaring that tunneling.
  88
  89 NOTES
  90 -----
  91
  92 The script creates a +tap+ interface if needed, and brings it up as
  93 needed. Then if so configured, the +tap+ is added to the +bridge+, and
  94 then the +rrqnet+ virtual cable process is started under a +daemon+
  95 supervision.
  96
  97 Note that the +rrqnet+ virtual cable requires real networking for its
  98 UDP tunnel traffic. The real packets will have a UDP header in
  99 addition to the orignal packet, which means that it grows packets with
 100 24 or 48 bytes (for ipv4 and ipv6 respectively). This may cause packet
 101 fragmentation of the tunneling packets unless the associated +tap+ is
 102 configured with that much smaller MTU than the real traffic.
 103
 104 SEE ALSO
 105 --------
 106
 107 *interfaces(5)* - network interface configuration for ifup and ifdown
 108 *rrqnet(8)* - packet tunneling over UDP, multiple channels
 109 *brctl(8)* - ethernet bridge administration
 110 *daemon(1)* - turns other processes into daemons
 111
 112 AUTHOR
 113 ------
 114 Ralph Rönnquist <ralph.ronnquist@gmail.com>