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+.
  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. The
  88 +rrqnet_options+ in the example tells the +rrqnet+ process to use an
  89 ipv4-only socket.
  90
  91 NOTES
  92 -----
  93
  94 The script creates a +tap+ interface if needed, and brings it up as
  95 needed. Then if so configured, the +tap+ is added to the +bridge+, and
  96 then the +rrqnet+ virtual cable process is started under a +daemon+
  97 supervision.
  98
  99 Note that the +rrqnet+ virtual cable requires real networking for its
 100 UDP tunnel traffic. The real packets will have a UDP header in
 101 addition to the orignal packet, which means that it grows packets with
 102 24 or 48 bytes (for ipv4 and ipv6 respectively). This may cause packet
 103 fragmentation of the tunneling packets unless the associated +tap+ is
 104 configured with that much smaller MTU than the real traffic.
 105
 106 SEE ALSO
 107 --------
 108
 109  *interfaces(5)* - network interface configuration for ifup and ifdown
 110  *rrqnet(8)* - packet tunneling over UDP, multiple channels
 111  *brctl(8)* - ethernet bridge administration
 112  *daemon(1)* - turns other processes into daemons
 113
 114 AUTHOR
 115 ------
 116 Ralph Rönnquist <ralph.ronnquist@gmail.com>