From 02fde814980ce7bb0b5210cd93f2aaf89efeeef1 Mon Sep 17 00:00:00 2001 From: Ralph Ronnquist Date: Mon, 5 Oct 2020 23:50:50 +1100 Subject: [PATCH] added man page for the ifupdown script --- Makefile | 2 +- rrqnet-ifupdown.sh.8.adoc | 114 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 rrqnet-ifupdown.sh.8.adoc diff --git a/Makefile b/Makefile index a1d7d0c..e589863 100644 --- 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 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 -- 2.39.2