Merge pull request #92 from BarbarossaTM/doc/manpage-update

Man pages for B.A.T.M.A.N. adv., bridges, ethtool, VRFs

Makefile

@@ -136,19 +136,25 @@ install: all
 .scd.1 .scd.2 .scd.3 .scd.4 .scd.5 .scd.6 .scd.7 .scd.8:
 	${SCDOC} < $< > $@
 
+MANPAGES_5 = \
+	doc/interfaces.5 \
+	doc/interfaces-bond.5 \
+	doc/interfaces-batman.5 \
+	doc/interfaces-bridge.5 \
+	doc/interfaces-ppp.5 \
+	doc/interfaces-vrf.5 \
+	doc/interfaces-vxlan.5 \
+	doc/interfaces-wireguard.5
+
+MANPAGES_7 = \
+	doc/ifupdown-executor.7
+
 MANPAGES_8 = \
 	doc/ifquery.8 \
 	doc/ifup.8 \
 	doc/ifdown.8 \
 	doc/ifctrstat.8
 
-MANPAGES_5 = \
-	doc/interfaces.5 \
-	doc/interfaces-bond.5
-
-MANPAGES_7 = \
-	doc/ifupdown-executor.7
-
 MANPAGES = ${MANPAGES_5} ${MANPAGES_7} ${MANPAGES_8}
 
 docs: ${MANPAGES}

doc/interfaces-batman.scd

@@ -0,0 +1,87 @@
+interfaces-batman(5)
+
+# NAME
+
+*interfaces-batman* - B.A.T.M.A.N. adv. extensions for the interfaces(5)
+file format
+
+# DESCRIPTION
+
+Better Approach To Mobile Ad-Hoc Networking (B.A.T.M.A.N.) advanced is
+a mesh protocol which provides an Ethernet overlay network over an
+Ethernet underlay. The overlay interface is called _meshif_ whereas
+underlay interfaces are called _hardif_.
+
+It's supported in the Linux kernel and thus available in many Linux
+environments. The ifupdown-ng exectuor relies on the *batctl* tool
+being installed. Support for setting interface based hop-penalties
+required Linux Kernel 5.8 or later.
+
+B.A.T.M.A.N. adv. adds 30-60 bytes of encapsulation overhead depending
+on wether netword coding is activated or not. This should be taken into
+consideration when setting up overlay networks, particularly on underlay
+networks with a conventional 1500 byte MTU.
+
+See https://www.open-mesh.org/projects/open-mesh/wiki for more details
+and updates.
+
+The following options allow to set up B.A.T.M.A.N. adv. interfaces.
+
+# BATMAN-RELATED OPTIONS
+
+*batman-ifaces* _list of interfaces_
+	Specifies the underlay interfaces (hardifs) which should be
+	configured for the B.A.T.M.A.N. adv. meshif defined within
+	the iface stanza.
+
+*batman-hop-penalty* _hop-penalty_
+	The _hop-penalty_ defines the cost of traversing a node or an
+	interface. The _hop-penalty_ is a numeric value between 0 and
+	255. Historically a _hop-penalty_ could only be set on a meshif,
+	since B.A.T.M.A.N adv. v2020.3 (included in Kernel 5.8) it can
+	also be set on a per-interfaces (hardif) basis.
+
+*batman-gw-mode* _gw-mode_
+	Denotes the gateway mode which controls the role this node will
+	play within this B.A.T.M.A.N. adv. instance. The mode can be
+	_off_, _client_, or _server_.
+
+*batman-distributed-arp-table* _mode_
+	Activates or deactivates the Distributed ARP table (DAT) within
+	this B.A.T.M.A.N. adv. instance. Valid values are _enable_ and
+	_disable_.
+
+*batman-multicast-mode* _mode_
+	Activates or deactivates the multicast mode of this B.A.T.M.A.N.
+	adv. instance. Valid values are _enable_ and _disable_.
+
+# EXAMPLES
+
+A B.A.T.M.A.N. adv. _meshif_:
+
+```
+auto bat-pad-cty
+iface bat-pad-cty
+	batman-ifaces dummy-pad-cty vlan1234
+	batman-hop-penalty 5
+	#
+	hwaddress f2:00:c1:01:00:00
+	mtu 1500
+```
+
+A B.A.T.M.A.N. adv. member interfaces (_hardif_):
+
+```
+auto vlan1234
+iface vlan1234
+	mtu 1560
+	batman-hop-penalty 10
+```
+
+# SEE ALSO
+
+*batctl*(8)
+
+# AUTHORS
+
+Maximilian Wilhelm <max@sdn.clinic>

doc/interfaces-bridge.scd

@@ -0,0 +1,87 @@
+interfaces-bridge(5)
+
+# NAME
+
+*interfaces-bridge* - Bridge extensions for the interfaces(5) file format
+
+# DESCRIPTION
+
+Linux has support for Ethernet bridging interfaces which act like an
+Ethernet switch within the Linux Kernel. The following options allow
+to set up Ethernet bridges and adding configured interfaces to bridges.
+
+See *ip-link*(8) for more details about the options listed below.
+
+# BRIDGE-RELATED OPTIONS
+
+*bridge-ports* _list of interfaces_
+	A space separated list of interfaces which should be configured
+	as member interfaces of this bridge. This option must be set
+	for the bridge to be configured.
+
+*bridge-hw* _MAC address_
+	Denotes the _MAC address_ the bridge should use.
+
+*bridge-ageing* _seconds_
+	Denotes the time in seconds after which a MAC address will be
+	removed from the Forwarding DataBase (FDB) after not having
+	seen a frame with this source address.
+
+# SPANNING TREE RELATED BRIDGE OPTIONS
+
+*bridge-stp* _state_
+	Activates or deactivates IEEE 802.1d Spanning Tree Protocol
+	(STP) support of the bridge. Valid values are _on_/_off_.
+
+*bridge-bridgeprio* _priority_
+	Sets the bridge's priority to _priority_. The priority value is
+	a number between 0 and 65535. Lower priority values are better.
+	The bridge with the lowest priority will be elected _root
+	bridge_.
+
+*bridge-fd* _seconds_
+	Denotes the bridge forward delay in seconds. Valid values are
+	between 2 and 30.
+
+*bridge-hello* _seconds_
+	Denotes the bridge hello time in seconds. Valid values are
+	between 1 and 10.
+
+*bridge-maxage* _seconds_
+	Denotes the seconds until another bridge is considerd dead
+	after reception of its last STP hello message. Valid values
+	are between 6 and 40.
+
+# EXAMPLES
+
+A simple layer 2 only bridge:
+
+```
+auto br0
+iface br0
+	bridge-ports eth0 veth-vm1 tap0
+	bridge-fd 0
+	bridge-stp off
+```
+
+A bridge with layer 3 configuration:
+
+```
+auto br0
+iface br0
+	bridge-ports eth0 veth-vm1 tap0
+	bridge-fd 0
+	bridge-stp off
+	#
+	address 192.0.2.42/24
+	address 2001:db8::42/64
+```
+
+# SEE ALSO
+
+*ip-link*(8)
+*interfaces*(5)
+
+# AUTHORS
+
+Maximilian Wilhelm <max@sdn.clinic>

doc/interfaces-ppp.scd

@@ -0,0 +1,37 @@
+interfaces-ppp(5)
+
+# NAME
+
+*interfaces-ppp* - PPP extensions for the interfaces(5) file format
+
+# DESCRIPTION
+
+The Point-to-Point Protocol (PPP) usually is used for dial-up lines,
+most common for over Digital Subscriber Lines (DSL) to connect to an
+Internet Service Provider (ISP). The following options allow to set
+up PPP dial-up connections.
+
+# PPP-RELATED OPTIONS
+
+*ppp-provider* _provider_
+	Denotes the file name of the _provider_ configuration file
+	within the _/etc/ppp/peers/_ directory which should be used
+	to set up the PPP connection.
+
+*ppp-physdev* _interfaces_
+	Denotes the physical (underlay) interface which is used to
+	set up the PPP connection.
+
+# EXAMPLES
+
+A PPP connection to _local-ISP_:
+
+```
+auto ppp0
+iface ppp0
+	ppp-provider local-ISP
+```
+
+# AUTHORS
+
+Maximilian Wilhelm <max@sdn.clinic>

doc/interfaces-vrf.scd

@@ -0,0 +1,58 @@
+interfaces-vrf(5)
+
+# NAME
+
+*interfaces-vrf* - VRF extensions for the interfaces(5) file format
+
+# DESCRIPTION
+
+Linux has support for Virtual Routing and Forwarding (VRF) instances
+since Kernel >= 4.4. The following options allow to set up VRFs and
+adding configured interfaces to VRFs.
+
+Note that in the Linux Kernel VRFs are represented as network interfaces,
+too. See https://www.kernel.org/doc/Documentation/networking/vrf.rst for
+more details.
+
+# VRF-RELATED OPTIONS
+
+*vrf-table* _table id_
+	The _id_ of the kernel routing table associated with this
+	VRF interface. This parameter indicates that the interface
+	where it is specified shall be a VRF.
+
+*vrf* _vrf interface_
+	The _vrf_ the interface should be assigned to. This parameter
+	is specified on regular interfaces which should be within the
+	given _vrf_.
+
+# EXAMPLES
+
+A VRF interface:
+
+```
+auto vrf_external
+iface vrf_external
+	vrf-table 1023
+```
+
+A regular interface which should be within a VRF:
+
+```
+auto eth0
+iface eth0
+	address 192.2.0.42/24
+	address 2001:db8::42/64
+	gateway 192.2.0.1
+	gateway 2001:db::1
+	vrf vrf_external
+```
+
+# SEE ALSO
+
+*ip-vrf*(8)
+*ip-link*(8)
+
+# AUTHORS
+
+Maximilian Wilhelm <max@sdn.clinic>

doc/interfaces-wireguard.scd

@@ -0,0 +1,47 @@
+interfaces-wireguard(5)
+
+# NAME
+
+*interfaces-wireguard* - Wireguard extensions for the interfaces(5) file format
+
+# DESCRIPTION
+
+Wireguard is a comtemporary in-Kernel layer 3 VPN protocol implementation
+which aims to provide fast and secure tunnels. The following options
+allow to set up Wireguard VPN tunnels.
+
+# WIREGUARD-RELATED OPTIONS
+
+*wireguard-config-path* _path_
+	Denotes the absolute _path_ to the Wireguard configuration file.
+	If no path is given, _/etc/wireguard/<interface>.conf_ will be
+	used. In the latter case _use wireguard_ has to be explicitly
+	set to the interface configuration.
+
+# EXAMPLES
+
+A Wireguard VPN tunnel with explicit configuration file specified
+
+```
+auto wg-foo
+iface wg-foo
+	wireguard-config-path /etc/wireguard/foo.conf
+	#
+	address 192.0.2.23/42
+	address 2001:db8::23/64
+```
+
+A Wireguard VPN tunnel with implicit configuration file:
+
+```
+auto wg-bar
+iface wg-bar
+	use wireguard
+	#
+	address 192.0.2.23/42
+	address 2001:db8::23/64
+```
+
+# AUTHORS
+
+Maximilian Wilhelm <max@sdn.clinic>

doc/interfaces.scd

@@ -133,6 +133,11 @@ The *use* keyword designates that an _option_ should be used.
 This system is extendable by additional packages, but the
 most common options are:
 
+*batman*
+	The interface is a B.A.T.M.A.N. adv. mesh interface.
+	Configuration of B.A.T.M.A.N. adv. interfaces requires the
+	*batctl* untiliy to be installed.
+
 *bond*
 	The interface is a bonded interface.  Configuration
 	of bonded interfaces requires the *bonding* package
@@ -150,6 +155,11 @@ most common options are:
 *loopback*
 	Designates the interface as a loopback device.
 
+*ppp*
+	Designates the interface as a PPP device.  Configuration
+	of PPP interfaces require the *ppp* and probably the *pppoe*
+	packages to be installed.
+
 *tunnel*
 	The interface is a tunnel.  Configuration of tunnels
 	requires the *tunnel* package to be installed.
@@ -162,6 +172,12 @@ most common options are:
 	The interface is a Virtual Extensible LAN (VXLAN) tunnel
 	endpoint.
 
+*wireguard*
+	The interface is a Wireguard VPN tunnel endpoint.
+
+Check *interfaces-<option>(5)* for further informaton about a given
+option and available configuration parameters.
+
 # EXAMPLES
 
 Configure a bridge interface *br0* with *bond0* attached to it,
@@ -194,10 +210,19 @@ iface eth0
 
 # SEE ALSO
 
+*ifup*(8)
+*ifdown*(8)
+*ifquery*(8)
+*ifctrstat*(8)
+*interfaces-batman*(5)
 *interfaces-bond*(5)
+*interfaces-bridge*(5)
+*interfaces-ppp*(5)
+*interfaces-vrf*(5)
 *interfaces-vxlan*(5)
+*interfaces-wireguard*(5)
 
 # AUTHORS
 
-Ariadne Conill <ariadne@dereferenced.org>
+Ariadne Conill <ariadne@dereferenced.org>++
 Maximilian Wilhelm <max@sdn.clinic>