From 3d1d384a6bef6a24cfadb7b6289f25b7b6157b33 Mon Sep 17 00:00:00 2001
From: Maximilian Wilhelm <max@sdn.clinic>
Date: Tue, 6 Oct 2020 03:55:09 +0200
Subject: [PATCH 1/8] doc: Add man page for VRF related parameters

Signed-off-by: Maximilian Wilhelm <max@sdn.clinic>
---
 doc/interfaces-vrf.scd | 58 ++++++++++++++++++++++++++++++++++++++++++
 doc/interfaces.scd     |  6 ++++-
 2 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100644 doc/interfaces-vrf.scd

diff --git a/doc/interfaces-vrf.scd b/doc/interfaces-vrf.scd
new file mode 100644
index 0000000..c808cf0
--- /dev/null
+++ b/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>
diff --git a/doc/interfaces.scd b/doc/interfaces.scd
index c8be881..9cf9dfe 100644
--- a/doc/interfaces.scd
+++ b/doc/interfaces.scd
@@ -155,6 +155,9 @@ most common options are:
 	The interface is a Virtual Extensible LAN (VXLAN) 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,
@@ -188,9 +191,10 @@ iface eth0
 # SEE ALSO
 
 *interfaces-bond*(5)
+*interfaces-vrf*(5)
 *interfaces-vxlan*(5)
 
 # AUTHORS
 
-Ariadne Conill <ariadne@dereferenced.org>
+Ariadne Conill <ariadne@dereferenced.org>++
 Maximilian Wilhelm <max@sdn.clinic>

From adf0f9dd46a60266a289d499a8d11d77b2524c3e Mon Sep 17 00:00:00 2001
From: Maximilian Wilhelm <max@sdn.clinic>
Date: Tue, 6 Oct 2020 03:55:55 +0200
Subject: [PATCH 2/8] doc: Add a man page for B.A.T.M.A.N. adv. interfaces

Signed-off-by: Maximilian Wilhelm <max@sdn.clinic>
---
 doc/interfaces-batman.scd | 87 +++++++++++++++++++++++++++++++++++++++
 doc/interfaces.scd        |  6 +++
 2 files changed, 93 insertions(+)
 create mode 100644 doc/interfaces-batman.scd

diff --git a/doc/interfaces-batman.scd b/doc/interfaces-batman.scd
new file mode 100644
index 0000000..87c75d9
--- /dev/null
+++ b/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>
diff --git a/doc/interfaces.scd b/doc/interfaces.scd
index 9cf9dfe..c540728 100644
--- a/doc/interfaces.scd
+++ b/doc/interfaces.scd
@@ -126,6 +126,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
@@ -191,6 +196,7 @@ iface eth0
 # SEE ALSO
 
 *interfaces-bond*(5)
+*interfaces-batman*(5)
 *interfaces-vrf*(5)
 *interfaces-vxlan*(5)
 

From 05711db6ceaa9d7e490ec24ac1270de4870b2180 Mon Sep 17 00:00:00 2001
From: Maximilian Wilhelm <max@sdn.clinic>
Date: Sat, 3 Oct 2020 02:35:29 +0200
Subject: [PATCH 3/8] doc: Add a man page for bridge interfaces

Signed-off-by: Maximilian Wilhelm <max@sdn.clinic>
---
 doc/interfaces-bridge.scd | 87 +++++++++++++++++++++++++++++++++++++++
 doc/interfaces.scd        |  1 +
 2 files changed, 88 insertions(+)
 create mode 100644 doc/interfaces-bridge.scd

diff --git a/doc/interfaces-bridge.scd b/doc/interfaces-bridge.scd
new file mode 100644
index 0000000..15aff2e
--- /dev/null
+++ b/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>
diff --git a/doc/interfaces.scd b/doc/interfaces.scd
index c540728..8264644 100644
--- a/doc/interfaces.scd
+++ b/doc/interfaces.scd
@@ -197,6 +197,7 @@ iface eth0
 
 *interfaces-bond*(5)
 *interfaces-batman*(5)
+*interfaces-bridge*(5)
 *interfaces-vrf*(5)
 *interfaces-vxlan*(5)
 

From 596dd8165b0dd1144c8218a14511fee7f110a538 Mon Sep 17 00:00:00 2001
From: Maximilian Wilhelm <max@sdn.clinic>
Date: Sat, 3 Oct 2020 02:47:17 +0200
Subject: [PATCH 4/8] doc: Reference CLI tool man pages in interfaces(5)

Signed-off-by: Maximilian Wilhelm <max@sdn.clinic>
---
 doc/interfaces.scd | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/doc/interfaces.scd b/doc/interfaces.scd
index 8264644..1f93050 100644
--- a/doc/interfaces.scd
+++ b/doc/interfaces.scd
@@ -195,8 +195,12 @@ iface eth0
 
 # SEE ALSO
 
-*interfaces-bond*(5)
+*ifup*(8)
+*ifdown*(8)
+*ifquery*(8)
+*ifctrstat*(8)
 *interfaces-batman*(5)
+*interfaces-bond*(5)
 *interfaces-bridge*(5)
 *interfaces-vrf*(5)
 *interfaces-vxlan*(5)

From 584f0634ed14c7f2f29793e012d1f6eeed5720f1 Mon Sep 17 00:00:00 2001
From: Maximilian Wilhelm <max@sdn.clinic>
Date: Tue, 6 Oct 2020 04:01:22 +0200
Subject: [PATCH 5/8] Add new interfaces-*(5) man pages to Makefile

Signed-off-by: Maximilian Wilhelm <max@sdn.clinic>
---
 Makefile | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 81172d2..d5fd007 100644
--- a/Makefile
+++ b/Makefile
@@ -144,7 +144,11 @@ MANPAGES_8 = \
 
 MANPAGES_5 = \
 	doc/interfaces.5 \
-	doc/interfaces-bond.5
+	doc/interfaces-bond.5 \
+	doc/interfaces-batman.5 \
+	doc/interfaces-bridge.5 \
+	doc/interfaces-vrf.5 \
+	doc/interfaces-vxlan.5
 
 MANPAGES_7 = \
 	doc/ifupdown-executor.7

From 87fa1760be317351437a8b156e99e066b90ff9c6 Mon Sep 17 00:00:00 2001
From: Maximilian Wilhelm <max@sdn.clinic>
Date: Sat, 3 Oct 2020 02:58:22 +0200
Subject: [PATCH 6/8] doc: Add a man page for Wireguard VPN tunnel interfaces

Signed-off-by: Maximilian Wilhelm <max@sdn.clinic>
---
 Makefile                     |  3 ++-
 doc/interfaces-wireguard.scd | 47 ++++++++++++++++++++++++++++++++++++
 doc/interfaces.scd           |  4 +++
 3 files changed, 53 insertions(+), 1 deletion(-)
 create mode 100644 doc/interfaces-wireguard.scd

diff --git a/Makefile b/Makefile
index d5fd007..cf7fbe5 100644
--- a/Makefile
+++ b/Makefile
@@ -148,7 +148,8 @@ MANPAGES_5 = \
 	doc/interfaces-batman.5 \
 	doc/interfaces-bridge.5 \
 	doc/interfaces-vrf.5 \
-	doc/interfaces-vxlan.5
+	doc/interfaces-vxlan.5 \
+	doc/interfaces-wireguard.5
 
 MANPAGES_7 = \
 	doc/ifupdown-executor.7
diff --git a/doc/interfaces-wireguard.scd b/doc/interfaces-wireguard.scd
new file mode 100644
index 0000000..900b900
--- /dev/null
+++ b/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>
diff --git a/doc/interfaces.scd b/doc/interfaces.scd
index 1f93050..674c97b 100644
--- a/doc/interfaces.scd
+++ b/doc/interfaces.scd
@@ -160,6 +160,9 @@ 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.
 
@@ -204,6 +207,7 @@ iface eth0
 *interfaces-bridge*(5)
 *interfaces-vrf*(5)
 *interfaces-vxlan*(5)
+*interfaces-wireguard*(5)
 
 # AUTHORS
 

From 63a55031856cf201dc84826ca8dcdc0c22cf1546 Mon Sep 17 00:00:00 2001
From: Maximilian Wilhelm <max@sdn.clinic>
Date: Sat, 3 Oct 2020 03:25:53 +0200
Subject: [PATCH 7/8] doc: Add a man page for PPP dial-up interfaces

Signed-off-by: Maximilian Wilhelm <max@sdn.clinic>
---
 Makefile               |  1 +
 doc/interfaces-ppp.scd | 37 +++++++++++++++++++++++++++++++++++++
 doc/interfaces.scd     |  6 ++++++
 3 files changed, 44 insertions(+)
 create mode 100644 doc/interfaces-ppp.scd

diff --git a/Makefile b/Makefile
index cf7fbe5..a2999db 100644
--- a/Makefile
+++ b/Makefile
@@ -147,6 +147,7 @@ MANPAGES_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
diff --git a/doc/interfaces-ppp.scd b/doc/interfaces-ppp.scd
new file mode 100644
index 0000000..5d12555
--- /dev/null
+++ b/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>
diff --git a/doc/interfaces.scd b/doc/interfaces.scd
index 674c97b..da10ee8 100644
--- a/doc/interfaces.scd
+++ b/doc/interfaces.scd
@@ -148,6 +148,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.
@@ -205,6 +210,7 @@ iface eth0
 *interfaces-batman*(5)
 *interfaces-bond*(5)
 *interfaces-bridge*(5)
+*interfaces-ppp*(5)
 *interfaces-vrf*(5)
 *interfaces-vxlan*(5)
 *interfaces-wireguard*(5)

From 98328655391f9fb34f51265f5aa4b5710135173c Mon Sep 17 00:00:00 2001
From: Maximilian Wilhelm <max@sdn.clinic>
Date: Tue, 6 Oct 2020 04:02:24 +0200
Subject: [PATCH 8/8] Makefile: Order manpages by section number

Signed-off-by: Maximilian Wilhelm <max@sdn.clinic>
---
 Makefile | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Makefile b/Makefile
index a2999db..f181288 100644
--- a/Makefile
+++ b/Makefile
@@ -136,12 +136,6 @@ install: all
 .scd.1 .scd.2 .scd.3 .scd.4 .scd.5 .scd.6 .scd.7 .scd.8:
 	${SCDOC} < $< > $@
 
-MANPAGES_8 = \
-	doc/ifquery.8 \
-	doc/ifup.8 \
-	doc/ifdown.8 \
-	doc/ifctrstat.8
-
 MANPAGES_5 = \
 	doc/interfaces.5 \
 	doc/interfaces-bond.5 \
@@ -155,6 +149,12 @@ MANPAGES_5 = \
 MANPAGES_7 = \
 	doc/ifupdown-executor.7
 
+MANPAGES_8 = \
+	doc/ifquery.8 \
+	doc/ifup.8 \
+	doc/ifdown.8 \
+	doc/ifctrstat.8
+
 MANPAGES = ${MANPAGES_5} ${MANPAGES_7} ${MANPAGES_8}
 
 docs: ${MANPAGES}