Merge pull request #92 from BarbarossaTM/doc/manpage-update
Man pages for B.A.T.M.A.N. adv., bridges, ethtool, VRFs
This commit is contained in:
Ariadne Conill
GitHub
commit
6f588a01d5
7 changed files with 355 additions and 8 deletions
20
Makefile
20
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}
|
||||
|
|
|
|||
87
doc/interfaces-batman.scd
Normal file
87
doc/interfaces-batman.scd
Normal file
|
|
@ -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>
|
||||
87
doc/interfaces-bridge.scd
Normal file
87
doc/interfaces-bridge.scd
Normal file
|
|
@ -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>
|
||||
37
doc/interfaces-ppp.scd
Normal file
37
doc/interfaces-ppp.scd
Normal file
|
|
@ -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>
|
||||
58
doc/interfaces-vrf.scd
Normal file
58
doc/interfaces-vrf.scd
Normal file
|
|
@ -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>
|
||||
47
doc/interfaces-wireguard.scd
Normal file
47
doc/interfaces-wireguard.scd
Normal file
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue