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