diff --git a/Makefile b/Makefile index 81172d2..f181288 100644 --- a/Makefile +++ b/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} 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 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 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 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 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/.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 diff --git a/doc/interfaces.scd b/doc/interfaces.scd index 9d51481..ceafcab 100644 --- a/doc/interfaces.scd +++ b/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-