added man page for the ifupdown script

diff --git a/Makefile b/Makefile
index a1d7d0c2e5dbc37e74a96c888ff8db4ed52a1d51..e589863f02ec41186f4909305dee8bf04f80c5de 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -6,7 +6,7 @@ MAN8DIR = $(DESTDIR)/usr/local/share/man/man8
 SBINFILES = rrqnet rrqnet-cron.sh
 ETCFILES = set-source-route.sh ifupdown.sh
 MAN1FILES = 
-MAN8FILES = rrqnet.8 rrqnet-cron.sh.8
+MAN8FILES = rrqnet.8 rrqnet-cron.sh.8 rrqnet-ifupdown.sh.8
 HTMLDOC = $(MAN8FILES:%=%.html)
 
 .PHONY: ifupdown.sh

diff --git a/rrqnet-ifupdown.sh.8.adoc b/rrqnet-ifupdown.sh.8.adoc
new file mode 100644 (file)
index 0000000..bcca6a0
--- /dev/null
+++ b/rrqnet-ifupdown.sh.8.adoc
@@ -0,0 +1,114 @@
+rrqnet-ifupdown.sh(8)
+=====================
+:doctype: manpage
+:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
+
+NAME
+----
+rrqnet-ifupdown.sh - an ifupdown script to uphold *rrqnet* cables by
+configuration in +/etc/network/interfaces+.
+
+SYNOPSIS
+--------
+/etc/network/if-post-down.d/rrqnet -> /etc/rrqnet/ifupdown.sh
+/etc/network/if-pre-up.d/rrqnet -> /etc/rrqnet/ifupdown.sh
+
+DESCRIPTION
+-----------
+
+*/etc/rrqnet/ifupdown.sh* is a utility script for upholding +rrqnet+
+virtual cables via +/etc/network/interfaces+. The script is set up
+both as "pre-up" and "post-down" scripts for handling the associated
++rrqnet+ configurations to bring up and tear down virtual cable plugs
+over +tap+ interfaces.
+
+An +rrqnet+ virtual cable uses +tap+ interfaces at each cable end
+host, which also have the service processes, aptly named +rrqnet+, to
+forward network traffic over UDP. Each +rrqnet+ process acts as a
+networking switch that facilitates level 2 connectivity among all its
+end points according to the Ethernet machine addresses of the packets.
+
+This script implements additional option codes for the IFACE stanzas
+for declaring the configuration of the +rrqnet+ daemon that should use
+a +tap+ interface for its virtual cabling. The list of options are:
+
+*rrqnet_port* _port_::
+
+This IFACE option is required both as way of identifying the stanza as
+an +rrqnet+ virtual cable +tap+, and to declare which UDP port to use
+for incomming cabling.
+
+*rrqnet_remote* _remote_::
+
+This IFACE option is used for declaring the remote connection details.
+Refer to +rrqnet+ man page for the full specification. Multiple
+remotes for a single +rrqnet+ process are declared by using multiple
++rrqnet_remote+ lines.
+
+*rrqnet_options* _options_::
+
+This IFACE option is used for declaring any additional rrqnet
+configuration options ([-4] [-B n] [-T n] [-m mcast]). Refer to the
++rrqnet+ man page for the full specification.
+
+*rrqnet_log* _level_ _pathname_::
+
+This IFACE option is used for declaring the log level as one of +-v+,
++-vv+ or +-vvv+, and to nominate the log file. If omitted, all the
++rrqnet+ process output will be directed to +/dev/null+.
+
+*rrqnet_bridge* _bridge_::
+
+This IFACE option is used if needed, to make the +tap+ once created to
+be mad a "port" of the nominated preceding +bridge+ interface [3].
+
+EXAMPLES
+--------
+
+The virtual cabling requires configurations for all +rrqnet+ processes
+This script handles the particular configuration 
+The following is a configuration example:
+
+----
+iface mynet0 inet static
+    address 10.0.0.2/24
+    broadcast 10.0.0.255
+    rrqnet_port 3636
+    rrqnet_options -4
+    rrqnet_remote 111.222.333.444:3636=/sec/mynet.key
+    rrqnet_log -v /var/log/mynet0.log
+----
+
+The illustration example is of a virtual cable plug using port +3636+
+for UDP tunneling through host +111.222.333.444+, port +3636+, where
+the local +tap+, named +mynet0+, has ipv4 address +10.0.0.2+. The
++rrqnet_port+ option is understood to identify the stanza as a virtual
+cabling set up which then is duly handled by +rrqnet-ifupdown.sh+, and
+all its options are used for declaring that tunneling.
+
+NOTES
+-----
+
+The script creates a +tap+ interface if needed, and brings it up as
+needed. Then if so configured, the +tap+ is added to the +bridge+, and
+then the +rrqnet+ virtual cable process is started under a +daemon+
+supervision.
+
+Note that the +rrqnet+ virtual cable requires real networking for its
+UDP tunnel traffic. The real packets will have a UDP header in
+addition to the orignal packet, which means that it grows packets with
+24 or 48 bytes (for ipv4 and ipv6 respectively). This may cause packet
+fragmentation of the tunneling packets unless the associated +tap+ is
+configured with that much smaller MTU than the real traffic.
+
+SEE ALSO
+--------
+
+*interfaces(5)* - network interface configuration for ifup and ifdown
+*rrqnet(8)* - packet tunneling over UDP, multiple channels
+*brctl(8)* - ethernet bridge administration
+*daemon(1)* - turns other processes into daemons
+
+AUTHOR
+------
+Ralph Rönnquist <ralph.ronnquist@gmail.com>