From 4abded8025a47990e58cd0a5fe9b96e38f4a3715 Mon Sep 17 00:00:00 2001
From: rebortg <github@ghlr.de>
Date: Sun, 29 Nov 2020 21:52:28 +0100
Subject: arrange: interfaces

---
 docs/configuration/interfaces/bridge.rst | 270 +++++++++++++++++++++++++++++++
 1 file changed, 270 insertions(+)
 create mode 100644 docs/configuration/interfaces/bridge.rst

(limited to 'docs/configuration/interfaces/bridge.rst')

diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst
new file mode 100644
index 00000000..dc94a761
--- /dev/null
+++ b/docs/configuration/interfaces/bridge.rst
@@ -0,0 +1,270 @@
+.. _bridge-interface:
+
+######
+Bridge
+######
+
+A Bridge is a way to connect two Ethernet segments together in a
+protocol independent way. Packets are forwarded based on Ethernet
+address, rather than IP address (like a router). Since forwarding is
+done at Layer 2, all protocols can go transparently through a bridge.
+The Linux bridge code implements a subset of the ANSI/IEEE 802.1d
+standard.
+
+.. note:: Spanning Tree Protocol is not enabled by default in VyOS.
+   :ref:`stp` can be easily enabled if needed.
+
+*************
+Configuration
+*************
+
+Common interface configuration
+==============================
+
+.. cmdinclude:: ../_include/interface-common-with-dhcp.txt
+   :var0: bridge
+   :var1: br0
+
+Member Interfaces
+=================
+
+.. cfgcmd:: set interfaces bridge <interface> member interface <member>
+
+   Assign `<member>` interface to bridge `<interface>`. A completion
+   helper will help you with all allowed interfaces which can be
+   bridged. This includes :ref:`ethernet-interface`,
+   :ref:`bond-interface`, :ref:`l2tpv3-interface`, :ref:`openvpn`,
+   :ref:`vxlan-interface`, :ref:`wireless-interface`,
+   :ref:`tunnel-interface` and :ref:`geneve-interface`.
+
+
+.. cfgcmd:: set interfaces bridge <interface> member interface <member>
+   priority <priority>
+
+   Configure individual bridge port `<priority>`.
+
+   Each bridge has a relative priority and cost. Each interface is
+   associated with a port (number) in the STP code. Each has a priority
+   and a cost, that is used to decide which is the shortest path to
+   forward a packet. The lowest cost path is always used unless the
+   other path is down. If you have multiple bridges and interfaces then
+   you may need to adjust the priorities to achieve optimium
+   performance.
+
+
+.. cfgcmd:: set interfaces bridge <interface> member interface <member>
+   cost <cost>
+
+   Path `<cost>` value for Spanning Tree Protocol. Each interface in a
+   bridge could have a different speed and this value is used when
+   deciding which link to use. Faster interfaces should have lower
+   costs.
+
+Bridge Options
+==============
+
+.. cfgcmd:: set interfaces bridge <interface> aging <time>
+
+   MAC address aging `<time`> in seconds (default: 300).
+
+.. cfgcmd:: set interfaces bridge <interface> max-age <time>
+
+   Bridge maximum aging `<time>` in seconds (default: 20).
+
+   If a another bridge in the spanning tree does not send out a hello
+   packet for a long period of time, it is assumed to be dead.
+
+.. cfgcmd:: set interfaces bridge <interface> igmp querier
+
+   Enable IGMP querier
+
+.. _stp:
+
+STP Parameter
+-------------
+
+:abbr:`STP (Spanning Tree Protocol)` is a network protocol that builds a
+loop-free logical topology for Ethernet networks. The basic function of
+STP is to prevent bridge loops and the broadcast radiation that results
+from them. Spanning tree also allows a network design to include backup
+links providing fault tolerance if an active link fails.
+
+.. cfgcmd:: set interfaces bridge <interface> stp
+
+   Enable spanning tree protocol. STP is disabled by default.
+
+
+.. cfgcmd:: set interfaces bridge <interface> forwarding-delay <delay>
+
+   Spanning Tree Protocol forwarding `<delay>` in seconds (default: 15).
+
+   Forwarding delay time is the time spent in each of the Listening and
+   Learning states before the Forwarding state is entered. This delay is
+   so that when a new bridge comes onto a busy network it looks at some
+   traffic before participating.
+
+
+.. cfgcmd:: set interfaces bridge <interface> hello-time <interval>
+
+   Spanning Tree Protocol hello advertisement `<interval>` in seconds
+   (default: 2).
+
+   Periodically, a hello packet is sent out by the Root Bridge and the
+   Designated Bridges. Hello packets are used to communicate information
+   about the topology throughout the entire Bridged Local Area Network.
+
+VLAN
+====
+
+.. cmdinclude:: ../_include/interface-vlan-8021q.txt
+   :var0: bridge
+   :var1: br0
+
+.. cfgcmd:: set interfaces bridge <interface> member interface <member>
+   native-vlan <vlan-id>
+
+   Set the native VLAN ID flag of the interface. When a data packet without a
+   VLAN tag enters the port, the data packet will be forced to add a tag of a
+   specific vlan id. When the vlan id flag flows out, the tag of the vlan id
+   will be stripped
+
+.. cfgcmd:: set interfaces bridge <interface> member interface <member>
+   allowed-vlan <vlan-id>
+
+   Allows specific VLAN IDs to pass through the bridge member interface. This
+   can either be an individual VLAN id or a range of VLAN ids delimited by a
+   hyphen.
+
+*******
+Example
+*******
+
+Creating a bridge interface is very simple. In this example we will
+have:
+
+* A bridge named `br100`
+* Member interfaces `eth1` and VLAN 10 on interface `eth2`
+* Enable STP
+* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64
+
+.. code-block:: none
+
+  set interfaces bridge br100 address 192.0.2.1/24
+  set interfaces bridge br100 address 2001:db8::ffff/64
+  set interfaces bridge br100 member interface eth1
+  set interfaces bridge br100 member interface eth2.10
+  set interfaces bridge br100 stp
+
+This results in the active configuration:
+
+.. code-block:: none
+
+   vyos@vyos# show interfaces bridge br100
+    address 192.0.2.1/24
+    address 2001:db8::ffff/64
+    member {
+        interface eth1 {
+        }
+        interface eth2.10 {
+        }
+    }
+    stp
+
+*******
+Example
+*******
+
+An example of creating a VLAN-aware bridge is as follows:
+
+* A bridge named `br100`
+* The member interface `eth1` is a trunk that allows VLAN 10 to pass
+* VLAN 10 on member interface `eth2` (ACCESS mode)
+* Enable STP
+* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64
+
+.. code-block:: none
+
+  set interfaces bridge br100 member interface eth1 allowed-vlan 10
+  set interfaces bridge br100 member interface eth2 native-vlan 10
+  set interfaces bridge br100 vif 10 address 192.0.2.1/24
+  set interfaces bridge br100 vif 10 address 2001:db8::ffff/64
+  set interfaces bridge br100 stp
+
+This results in the active configuration:
+
+.. code-block:: none
+
+   vyos@vyos# show interfaces bridge br100
+    member {
+        interface eth1 {
+            allowed-vlan 10
+        }
+        interface eth2 {
+            native-vlan 10
+        }
+    }
+    stp
+    vif 10 {
+        address 192.0.2.1/24
+        address 2001:db8::ffff/64
+    }
+
+*******
+Example
+*******
+
+.. opcmd:: show bridge
+
+   The `show bridge` operational command can be used to display
+   configured bridges:
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show bridge
+     bridge name     bridge id               STP enabled     interfaces
+     br100           8000.0050569d11df       yes             eth1
+                                                           eth2.10
+
+.. opcmd:: show bridge <name> spanning-tree
+
+   Show bridge `<name>` STP configuration.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show bridge br100 spanning-tree
+     br100
+      bridge id              8000.0050569d11df
+      designated root        8000.0050569d11df
+      root port                 0                    path cost                  0
+      max age                  20.00                 bridge max age            20.00
+      hello time                2.00                 bridge hello time          2.00
+      forward delay            14.00                 bridge forward delay      14.00
+      ageing time             300.00
+      hello timer               0.06                 tcn timer                  0.00
+      topology change timer     0.00                 gc timer                 242.02
+      flags
+
+     eth1 (1)
+      port id                8001                    state                  disabled
+      designated root        8000.0050569d11df       path cost                100
+      designated bridge      8000.0050569d11df       message age timer          0.00
+      designated port        8001                    forward delay timer        0.00
+      designated cost           0                    hold timer                 0.00
+      flags
+
+     eth2.10 (2)
+      port id                8002                    state                  disabled
+      designated root        8000.0050569d11df       path cost                100
+      designated bridge      8000.0050569d11df       message age timer          0.00
+      designated port        8002                    forward delay timer        0.00
+      designated cost           0                    hold timer                 0.00
+
+.. opcmd: show bridge <name> macs
+
+   Show bridge Media Access Control (MAC) address table
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show bridge br100 macs
+     port no mac addr                is local?       ageing timer
+       1     00:53:29:44:3b:19       yes                0.00
-- 
cgit v1.2.3


From e33e1268f944be445b5a771df0e97e913487512f Mon Sep 17 00:00:00 2001
From: rebortg <github@ghlr.de>
Date: Mon, 30 Nov 2020 19:46:59 +0100
Subject: change include to absolute path

---
 docs/_ext/vyos.py                                 |  9 ++++++--
 docs/_include/interface-common-with-dhcp.txt      |  8 +++----
 docs/_include/interface-common-without-dhcp.txt   |  4 ++--
 docs/_include/interface-common.txt                | 18 ++++++++--------
 docs/_include/interface-dhcpv6-options.txt        |  2 +-
 docs/_include/interface-vlan-8021ad.txt           | 26 +++++++++++------------
 docs/_include/interface-vlan-8021q.txt            | 24 ++++++++++-----------
 docs/configuration/firewall/index.rst             |  1 +
 docs/configuration/interfaces/bonding.rst         |  4 ++--
 docs/configuration/interfaces/bridge.rst          |  4 ++--
 docs/configuration/interfaces/dummy.rst           |  8 +++----
 docs/configuration/interfaces/ethernet.rst        |  6 +++---
 docs/configuration/interfaces/geneve.rst          |  2 +-
 docs/configuration/interfaces/l2tpv3.rst          |  4 ++--
 docs/configuration/interfaces/loopback.rst        |  4 ++--
 docs/configuration/interfaces/macsec.rst          |  2 +-
 docs/configuration/interfaces/openvpn.rst         |  2 +-
 docs/configuration/interfaces/pppoe.rst           |  8 +++----
 docs/configuration/interfaces/pseudo-ethernet.rst |  4 ++--
 docs/configuration/interfaces/tunnel.rst          |  2 +-
 docs/configuration/interfaces/vxlan.rst           |  2 +-
 docs/configuration/interfaces/wireless.rst        |  6 +++---
 docs/configuration/interfaces/wirelessmodem.rst   |  6 +++---
 docs/configuration/nat/nptv6.rst                  |  2 +-
 docs/configuration/policy/index.rst               |  4 ++--
 docs/contributing/debugging.rst                   |  2 +-
 docs/contributing/development.rst                 |  2 +-
 docs/contributing/documentation.rst               |  2 +-
 docs/contributing/issues-features.rst             |  2 +-
 docs/interfaces/advanced-index.rst                | 23 --------------------
 docs/interfaces/basic-index.rst                   | 12 -----------
 docs/routing/bfd.rst                              |  2 +-
 docs/routing/ospf.rst                             |  2 +-
 docs/routing/rip.rst                              |  2 +-
 docs/services/conntrack.rst                       |  2 +-
 docs/services/ipoe-server.rst                     |  4 ++--
 docs/services/pppoe-server.rst                    |  2 +-
 docs/system/lcd.rst                               |  2 +-
 docs/vpn/sstp.rst                                 |  2 +-
 39 files changed, 97 insertions(+), 126 deletions(-)
 delete mode 100644 docs/interfaces/advanced-index.rst
 delete mode 100644 docs/interfaces/basic-index.rst

(limited to 'docs/configuration/interfaces/bridge.rst')

diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py
index 89cc8ab7..4a974b46 100644
--- a/docs/_ext/vyos.py
+++ b/docs/_ext/vyos.py
@@ -3,7 +3,7 @@ import json
 import os
 from docutils import io, nodes, utils, statemachine
 from docutils.parsers.rst.roles import set_classes
-from docutils.parsers.rst import Directive, directives
+from docutils.parsers.rst import Directive, directives, states
 
 from sphinx.util.docutils import SphinxDirective
 
@@ -173,7 +173,7 @@ class inlinecmd(nodes.inline):
         #self.literal_whitespace -= 1
 
 
-class CfgInclude(Directive):
+class CfgInclude(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
@@ -189,10 +189,15 @@ class CfgInclude(Directive):
         'var8': str,
         'var9': str
     }
+    standard_include_path = os.path.join(os.path.dirname(states.__file__),
+                                         'include')
 
     def run(self):
         ### Copy from include directive docutils 
         """Include a file as part of the content of this reST file."""
+        rel_filename, filename = self.env.relfn2path(self.arguments[0])
+        self.arguments[0] = filename
+        self.env.note_included(filename)
         if not self.state.document.settings.file_insertion_enabled:
             raise self.warning('"%s" directive disabled.' % self.name)
         source = self.state_machine.input_lines.source(
diff --git a/docs/_include/interface-common-with-dhcp.txt b/docs/_include/interface-common-with-dhcp.txt
index 3e1394a3..1cacdd53 100644
--- a/docs/_include/interface-common-with-dhcp.txt
+++ b/docs/_include/interface-common-with-dhcp.txt
@@ -1,17 +1,17 @@
-.. cmdinclude:: ../_include/interface-address-with-dhcp.txt
+.. cmdinclude:: /_include/interface-address-with-dhcp.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
 
-.. cmdinclude:: ../_include/interface-common.txt
+.. cmdinclude:: /_include/interface-common.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
 
 **DHCP(v6)**
 
-.. cmdinclude:: ../_include/interface-dhcp-options.txt
+.. cmdinclude:: /_include/interface-dhcp-options.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
 
-.. cmdinclude:: ../_include/interface-dhcpv6-options.txt
+.. cmdinclude:: /_include/interface-dhcpv6-options.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
diff --git a/docs/_include/interface-common-without-dhcp.txt b/docs/_include/interface-common-without-dhcp.txt
index d861f003..73d39dd0 100644
--- a/docs/_include/interface-common-without-dhcp.txt
+++ b/docs/_include/interface-common-without-dhcp.txt
@@ -1,7 +1,7 @@
-.. cmdinclude:: ../_include/interface-address.txt
+.. cmdinclude:: /_include/interface-address.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
 
-.. cmdinclude:: ../_include/interface-common.txt
+.. cmdinclude:: /_include/interface-common.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
diff --git a/docs/_include/interface-common.txt b/docs/_include/interface-common.txt
index de29356f..68c9c448 100644
--- a/docs/_include/interface-common.txt
+++ b/docs/_include/interface-common.txt
@@ -1,36 +1,36 @@
-.. cmdinclude:: ../_include/interface-description.txt
+.. cmdinclude:: /_include/interface-description.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
 
-.. cmdinclude:: ../_include/interface-disable.txt
+.. cmdinclude:: /_include/interface-disable.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
 
-.. cmdinclude:: ../_include/interface-disable-flow-control.txt
+.. cmdinclude:: /_include/interface-disable-flow-control.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
 
-.. cmdinclude:: ../_include/interface-disable-link-detect.txt
+.. cmdinclude:: /_include/interface-disable-link-detect.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
 
-.. cmdinclude:: ../_include/interface-mac.txt
+.. cmdinclude:: /_include/interface-mac.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
 
-.. cmdinclude:: ../_include/interface-mtu.txt
+.. cmdinclude:: /_include/interface-mtu.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
 
-.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt
+.. cmdinclude:: /_include/interface-ipv6-addr-autoconf.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
 
-.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt
+.. cmdinclude:: /_include/interface-ipv6-addr-eui64.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
 
-.. cmdinclude:: ../_include/interface-vrf.txt
+.. cmdinclude:: /_include/interface-vrf.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
 
diff --git a/docs/_include/interface-dhcpv6-options.txt b/docs/_include/interface-dhcpv6-options.txt
index a54a7dce..a47d9f32 100644
--- a/docs/_include/interface-dhcpv6-options.txt
+++ b/docs/_include/interface-dhcpv6-options.txt
@@ -30,7 +30,7 @@
 
     set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options temporary
 
-.. cmdinclude:: ../_include/interface-dhcpv6-prefix-delegation.txt
+.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt
   :var0: {{ var0 }}
   :var1: {{ var1 }}
   :var2: {{ var2 }}
diff --git a/docs/_include/interface-vlan-8021ad.txt b/docs/_include/interface-vlan-8021ad.txt
index a1e971be..12925ad4 100644
--- a/docs/_include/interface-vlan-8021ad.txt
+++ b/docs/_include/interface-vlan-8021ad.txt
@@ -1,4 +1,4 @@
-.. include:: ../_include/need_improvement.txt
+.. include:: /_include/need_improvement.txt
 
 IEEE 802.1ad_ was an Ethernet networking standard informally known as QinQ as
 an amendment to IEEE standard 802.1q VLAN interfaces as described above.
@@ -28,7 +28,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG
 (service tag with Ethernet Type = 0x88a8).
 
 
-.. cmdinclude:: ../_include/interface-address-with-dhcp.txt
+.. cmdinclude:: /_include/interface-address-with-dhcp.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif-s
@@ -38,7 +38,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG
    :var6: <vlan-id>
    :var7: 20
 
-.. cmdinclude:: ../_include/interface-description.txt
+.. cmdinclude:: /_include/interface-description.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif-s
@@ -48,7 +48,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG
    :var6: <vlan-id>
    :var7: 20
 
-.. cmdinclude:: ../_include/interface-disable.txt
+.. cmdinclude:: /_include/interface-disable.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif-s
@@ -58,7 +58,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG
    :var6: <vlan-id>
    :var7: 20
 
-.. cmdinclude:: ../_include/interface-disable-link-detect.txt
+.. cmdinclude:: /_include/interface-disable-link-detect.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif-s
@@ -68,7 +68,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG
    :var6: <vlan-id>
    :var7: 20
 
-.. cmdinclude:: ../_include/interface-mac.txt
+.. cmdinclude:: /_include/interface-mac.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif-s
@@ -78,7 +78,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG
    :var6: <vlan-id>
    :var7: 20
 
-.. cmdinclude:: ../_include/interface-mtu.txt
+.. cmdinclude:: /_include/interface-mtu.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif-s
@@ -88,7 +88,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG
    :var6: <vlan-id>
    :var7: 20
 
-.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt
+.. cmdinclude:: /_include/interface-ipv6-addr-autoconf.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif-s
@@ -98,7 +98,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG
    :var6: <vlan-id>
    :var7: 20
 
-.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt
+.. cmdinclude:: /_include/interface-ipv6-addr-eui64.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif-s
@@ -108,7 +108,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG
    :var6: <vlan-id>
    :var7: 20
 
-.. cmdinclude:: ../_include/interface-vrf.txt
+.. cmdinclude:: /_include/interface-vrf.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif-s
@@ -120,7 +120,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG
 
 **DHCP(v6)**
 
-.. cmdinclude:: ../_include/interface-dhcp-options.txt
+.. cmdinclude:: /_include/interface-dhcp-options.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif-s
@@ -130,7 +130,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG
    :var6: <vlan-id>
    :var7: 20
 
-.. cmdinclude:: ../_include/interface-dhcpv6-options.txt
+.. cmdinclude:: /_include/interface-dhcpv6-options.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif-s
@@ -140,4 +140,4 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG
    :var6: <vlan-id>
    :var7: 20
 
-.. include:: ../common-references.rst
+.. include:: /common-references.rst
diff --git a/docs/_include/interface-vlan-8021q.txt b/docs/_include/interface-vlan-8021q.txt
index 2c7e58f7..37f652f3 100644
--- a/docs/_include/interface-vlan-8021q.txt
+++ b/docs/_include/interface-vlan-8021q.txt
@@ -29,63 +29,63 @@ term used for this is ``vif``.
 
   .. note:: Only 802.1Q-tagged packets are accepted on Ethernet vifs.
 
-.. cmdinclude:: ../_include/interface-address-with-dhcp.txt
+.. cmdinclude:: /_include/interface-address-with-dhcp.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif
    :var3: <vlan-id>
    :var4: 10
 
-.. cmdinclude:: ../_include/interface-description.txt
+.. cmdinclude:: /_include/interface-description.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif
    :var3: <vlan-id>
    :var4: 10
 
-.. cmdinclude:: ../_include/interface-disable.txt
+.. cmdinclude:: /_include/interface-disable.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif
    :var3: <vlan-id>
    :var4: 10
 
-.. cmdinclude:: ../_include/interface-disable-link-detect.txt
+.. cmdinclude:: /_include/interface-disable-link-detect.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif
    :var3: <vlan-id>
    :var4: 10
 
-.. cmdinclude:: ../_include/interface-mac.txt
+.. cmdinclude:: /_include/interface-mac.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif
    :var3: <vlan-id>
    :var4: 10
 
-.. cmdinclude:: ../_include/interface-mtu.txt
+.. cmdinclude:: /_include/interface-mtu.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif
    :var3: <vlan-id>
    :var4: 10
 
-.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt
+.. cmdinclude:: /_include/interface-ipv6-addr-autoconf.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif
    :var3: <vlan-id>
    :var4: 10
 
-.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt
+.. cmdinclude:: /_include/interface-ipv6-addr-eui64.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif
    :var3: <vlan-id>
    :var4: 10
 
-.. cmdinclude:: ../_include/interface-vrf.txt
+.. cmdinclude:: /_include/interface-vrf.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif
@@ -94,18 +94,18 @@ term used for this is ``vif``.
 
 **DHCP(v6)**
 
-.. cmdinclude:: ../_include/interface-dhcp-options.txt
+.. cmdinclude:: /_include/interface-dhcp-options.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif
    :var3: <vlan-id>
    :var4: 10
 
-.. cmdinclude:: ../_include/interface-dhcpv6-options.txt
+.. cmdinclude:: /_include/interface-dhcpv6-options.txt
    :var0: {{ var0 }}
    :var1: {{ var1 }}
    :var2: vif
    :var3: <vlan-id>
    :var4: 10
 
-.. include:: ../common-references.rst
\ No newline at end of file
+.. include:: /common-references.rst
\ No newline at end of file
diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst
index 870e9a08..d9a3ebe3 100644
--- a/docs/configuration/firewall/index.rst
+++ b/docs/configuration/firewall/index.rst
@@ -3,6 +3,7 @@
 Firewall
 ========
 
+
 Overview
 --------
 
diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst
index 7faddd6f..8ec8f34d 100644
--- a/docs/configuration/interfaces/bonding.rst
+++ b/docs/configuration/interfaces/bonding.rst
@@ -17,7 +17,7 @@ Configuration
 Common interface configuration
 ==============================
 
-.. cmdinclude:: ../_include/interface-common-with-dhcp.txt
+.. cmdinclude:: /_include/interface-common-with-dhcp.txt
    :var0: bond
    :var1: bond0
 
@@ -259,7 +259,7 @@ Bond options
 VLAN
 ====
 
-.. cmdinclude:: ../_include/interface-vlan-8021q.txt
+.. cmdinclude:: /_include/interface-vlan-8021q.txt
    :var0: bond
    :var1: bond0
 
diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst
index dc94a761..766d2aa5 100644
--- a/docs/configuration/interfaces/bridge.rst
+++ b/docs/configuration/interfaces/bridge.rst
@@ -21,7 +21,7 @@ Configuration
 Common interface configuration
 ==============================
 
-.. cmdinclude:: ../_include/interface-common-with-dhcp.txt
+.. cmdinclude:: /_include/interface-common-with-dhcp.txt
    :var0: bridge
    :var1: br0
 
@@ -116,7 +116,7 @@ links providing fault tolerance if an active link fails.
 VLAN
 ====
 
-.. cmdinclude:: ../_include/interface-vlan-8021q.txt
+.. cmdinclude:: /_include/interface-vlan-8021q.txt
    :var0: bridge
    :var1: br0
 
diff --git a/docs/configuration/interfaces/dummy.rst b/docs/configuration/interfaces/dummy.rst
index c36d0024..c9845230 100644
--- a/docs/configuration/interfaces/dummy.rst
+++ b/docs/configuration/interfaces/dummy.rst
@@ -25,19 +25,19 @@ Configuration
 Common interface configuration
 ==============================
 
-.. cmdinclude:: ../_include/interface-address.txt
+.. cmdinclude:: /_include/interface-address.txt
    :var0: dummy
    :var1: dum0
 
-.. cmdinclude:: ../_include/interface-description.txt
+.. cmdinclude:: /_include/interface-description.txt
    :var0: dummy
    :var1: dum0
 
-.. cmdinclude:: ../_include/interface-disable.txt
+.. cmdinclude:: /_include/interface-disable.txt
    :var0: dummy
    :var1: dum0
 
-.. cmdinclude:: ../_include/interface-vrf.txt
+.. cmdinclude:: /_include/interface-vrf.txt
    :var0: dummy
    :var1: dum0
 
diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst
index f2ab3f67..9311c947 100644
--- a/docs/configuration/interfaces/ethernet.rst
+++ b/docs/configuration/interfaces/ethernet.rst
@@ -14,7 +14,7 @@ Configuration
 Common interface configuration
 ==============================
 
-.. cmdinclude:: ../_include/interface-common-with-dhcp.txt
+.. cmdinclude:: /_include/interface-common-with-dhcp.txt
    :var0: ethernet
    :var1: eth0
 
@@ -72,14 +72,14 @@ VLAN
 Regular VLANs (802.1q)
 ----------------------
 
-.. cmdinclude:: ../_include/interface-vlan-8021q.txt
+.. cmdinclude:: /_include/interface-vlan-8021q.txt
    :var0: ethernet
    :var1: eth0
 
 QinQ (802.1ad)
 --------------
 
-.. cmdinclude:: ../_include/interface-vlan-8021ad.txt
+.. cmdinclude:: /_include/interface-vlan-8021ad.txt
    :var0: ethernet
    :var1: eth0
 
diff --git a/docs/configuration/interfaces/geneve.rst b/docs/configuration/interfaces/geneve.rst
index 47068687..9e00d621 100644
--- a/docs/configuration/interfaces/geneve.rst
+++ b/docs/configuration/interfaces/geneve.rst
@@ -39,7 +39,7 @@ Configuration
 Common interface configuration
 ==============================
 
-.. cmdinclude:: ../_include/interface-common-without-dhcp.txt
+.. cmdinclude:: /_include/interface-common-without-dhcp.txt
    :var0: geneve
    :var1: gnv0
 
diff --git a/docs/configuration/interfaces/l2tpv3.rst b/docs/configuration/interfaces/l2tpv3.rst
index 4c9cbf9b..a4b7be36 100644
--- a/docs/configuration/interfaces/l2tpv3.rst
+++ b/docs/configuration/interfaces/l2tpv3.rst
@@ -1,4 +1,4 @@
-.. include:: ../_include/need_improvement.txt
+.. include:: /_include/need_improvement.txt
 
 .. _l2tpv3-interface:
 
@@ -31,7 +31,7 @@ Configuration
 Common interface configuration
 ==============================
 
-.. cmdinclude:: ../_include/interface-common-without-dhcp.txt
+.. cmdinclude:: /_include/interface-common-without-dhcp.txt
    :var0: l2tpv3
    :var1: l2tpeth0
 
diff --git a/docs/configuration/interfaces/loopback.rst b/docs/configuration/interfaces/loopback.rst
index a6d659b5..f7386c62 100644
--- a/docs/configuration/interfaces/loopback.rst
+++ b/docs/configuration/interfaces/loopback.rst
@@ -26,11 +26,11 @@ Configuration
 Common interface configuration
 ==============================
 
-.. cmdinclude:: ../_include/interface-address.txt
+.. cmdinclude:: /_include/interface-address.txt
    :var0: loopback
    :var1: lo
 
-.. cmdinclude:: ../_include/interface-description.txt
+.. cmdinclude:: /_include/interface-description.txt
    :var0: loopback
    :var1: lo
 
diff --git a/docs/configuration/interfaces/macsec.rst b/docs/configuration/interfaces/macsec.rst
index ebc8f151..2bf643aa 100644
--- a/docs/configuration/interfaces/macsec.rst
+++ b/docs/configuration/interfaces/macsec.rst
@@ -20,7 +20,7 @@ Configuration
 Common interface configuration
 ==============================
 
-.. cmdinclude:: ../_include/interface-common-with-dhcp.txt
+.. cmdinclude:: /_include/interface-common-with-dhcp.txt
    :var0: macsec
    :var1: macsec0
 
diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst
index c6934335..7646959c 100644
--- a/docs/configuration/interfaces/openvpn.rst
+++ b/docs/configuration/interfaces/openvpn.rst
@@ -581,4 +581,4 @@ The following commands let you reset OpenVPN.
 
 
 
-.. include:: ../common-references.rst
+.. include:: /common-references.rst
diff --git a/docs/configuration/interfaces/pppoe.rst b/docs/configuration/interfaces/pppoe.rst
index 313edd84..decfd348 100644
--- a/docs/configuration/interfaces/pppoe.rst
+++ b/docs/configuration/interfaces/pppoe.rst
@@ -59,15 +59,15 @@ Configuration
 Common interface configuration
 ==============================
 
-.. cmdinclude:: ../_include/interface-description.txt
+.. cmdinclude:: /_include/interface-description.txt
    :var0: pppoe
    :var1: pppoe0
 
-.. cmdinclude:: ../_include/interface-disable.txt
+.. cmdinclude:: /_include/interface-disable.txt
    :var0: pppoe
    :var1: pppoe0
 
-.. cmdinclude:: ../_include/interface-vrf.txt
+.. cmdinclude:: /_include/interface-vrf.txt
    :var0: pppoe
    :var1: pppoe0
 
@@ -177,7 +177,7 @@ IPv6
    Use this command to enable acquisition of IPv6 address using stateless
    autoconfig (SLAAC).
 
-.. cmdinclude:: ../_include/interface-dhcpv6-prefix-delegation.txt
+.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt
   :var0: pppoe
   :var1: pppoe0
 
diff --git a/docs/configuration/interfaces/pseudo-ethernet.rst b/docs/configuration/interfaces/pseudo-ethernet.rst
index c2baca39..0471d2e1 100644
--- a/docs/configuration/interfaces/pseudo-ethernet.rst
+++ b/docs/configuration/interfaces/pseudo-ethernet.rst
@@ -45,7 +45,7 @@ Configuration
 Common interface configuration
 ==============================
 
-.. cmdinclude:: ../_include/interface-common-with-dhcp.txt
+.. cmdinclude:: /_include/interface-common-with-dhcp.txt
    :var0: pseudo-ethernet
    :var1: peth0
 
@@ -60,6 +60,6 @@ Pseudo Ethernet/MACVLAN options
 VLAN
 ====
 
-.. cmdinclude:: ../_include/interface-vlan-8021q.txt
+.. cmdinclude:: /_include/interface-vlan-8021q.txt
    :var0: pseudo-ethernet
    :var1: peth0
diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst
index 4b9da26b..7b1502f8 100644
--- a/docs/configuration/interfaces/tunnel.rst
+++ b/docs/configuration/interfaces/tunnel.rst
@@ -16,7 +16,7 @@ a closer look at the protocols and options currently supported by VyOS.
 Common interface configuration
 ------------------------------
 
-.. cmdinclude:: ../_include/interface-common-without-dhcp.txt
+.. cmdinclude:: /_include/interface-common-without-dhcp.txt
    :var0: tunnel
    :var1: tun0
 
diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst
index 40dc5400..95f8de35 100644
--- a/docs/configuration/interfaces/vxlan.rst
+++ b/docs/configuration/interfaces/vxlan.rst
@@ -39,7 +39,7 @@ Configuration
 Common interface configuration
 ------------------------------
 
-.. cmdinclude:: ../_include/interface-common-without-dhcp.txt
+.. cmdinclude:: /_include/interface-common-without-dhcp.txt
   :var0: vxlan
   :var1: vxlan0
 
diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst
index 2de3b126..82f66cf4 100644
--- a/docs/configuration/interfaces/wireless.rst
+++ b/docs/configuration/interfaces/wireless.rst
@@ -30,7 +30,7 @@ Configuration
 Common interface configuration
 ==============================
 
-.. cmdinclude:: ../_include/interface-common-with-dhcp.txt
+.. cmdinclude:: /_include/interface-common-with-dhcp.txt
    :var0: wireless
    :var1: wlan0
 
@@ -378,14 +378,14 @@ VLAN
 Regular VLANs (802.1q)
 ----------------------
 
-.. cmdinclude:: ../_include/interface-vlan-8021q.txt
+.. cmdinclude:: /_include/interface-vlan-8021q.txt
    :var0: wireless
    :var1: wlan0
 
 QinQ (802.1ad)
 --------------
 
-.. cmdinclude:: ../_include/interface-vlan-8021ad.txt
+.. cmdinclude:: /_include/interface-vlan-8021ad.txt
    :var0: wireless
    :var1: wlan0
 
diff --git a/docs/configuration/interfaces/wirelessmodem.rst b/docs/configuration/interfaces/wirelessmodem.rst
index f9dfa228..a65a47f4 100644
--- a/docs/configuration/interfaces/wirelessmodem.rst
+++ b/docs/configuration/interfaces/wirelessmodem.rst
@@ -15,15 +15,15 @@ Configuration
 Common interface configuration
 ==============================
 
-.. cmdinclude:: ../_include/interface-description.txt
+.. cmdinclude:: /_include/interface-description.txt
    :var0: wirelessmodem
    :var1: wlm0
 
-.. cmdinclude:: ../_include/interface-disable.txt
+.. cmdinclude:: /_include/interface-disable.txt
    :var0: wirelessmodem
    :var1: wlm0
 
-.. cmdinclude:: ../_include/interface-vrf.txt
+.. cmdinclude:: /_include/interface-vrf.txt
    :var0: wirelessmodem
    :var1: wlm0
 
diff --git a/docs/configuration/nat/nptv6.rst b/docs/configuration/nat/nptv6.rst
index f4e08325..c09c8336 100644
--- a/docs/configuration/nat/nptv6.rst
+++ b/docs/configuration/nat/nptv6.rst
@@ -1,4 +1,4 @@
-.. include:: _include/need_improvement.txt
+.. include:: /_include/need_improvement.txt
 
 .. _nptv6:
 
diff --git a/docs/configuration/policy/index.rst b/docs/configuration/policy/index.rst
index 4be494e5..557911d9 100644
--- a/docs/configuration/policy/index.rst
+++ b/docs/configuration/policy/index.rst
@@ -1,4 +1,4 @@
-.. include:: ../_include/need_improvement.txt
+.. include:: /_include/need_improvement.txt
 
 ######
 Policy
@@ -65,7 +65,7 @@ neighbor.
 You now see the longer AS path.
 
 
-.. include:: ../_include/need_improvement.txt
+.. include:: /_include/need_improvement.txt
 
 .. _routing-pbr:
 
diff --git a/docs/contributing/debugging.rst b/docs/contributing/debugging.rst
index ac2e0510..fcd62c89 100644
--- a/docs/contributing/debugging.rst
+++ b/docs/contributing/debugging.rst
@@ -143,4 +143,4 @@ order of the scripts.
 .. _vyatta-cfg: https://github.com/vyos/vyatta-cfg
 .. _bootchart.conf: https://github.com/vyos/vyos-build/blob/current/data/live-build-config/includes.chroot/etc/systemd/bootchart.conf
 
-.. include:: ../common-references.rst
+.. include:: /common-references.rst
diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst
index 86371845..0a7fecb5 100644
--- a/docs/contributing/development.rst
+++ b/docs/contributing/development.rst
@@ -711,4 +711,4 @@ http://dev.packages.vyos.net/repositories/.
 .. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/vif.xml.i
 .. _`MAC address`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/interface-mac.xml.i
 
-.. include:: ../common-references.rst
+.. include:: /common-references.rst
diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst
index 9dd0c495..0276a7d2 100644
--- a/docs/contributing/documentation.rst
+++ b/docs/contributing/documentation.rst
@@ -325,4 +325,4 @@ predefined structure.
 .. _reStructuredTextDirectives: https://docutils.sourceforge.io/docs/ref/rst/directives.html
 .. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md
 
-.. include:: ../common-references.rst
+.. include:: /common-references.rst
diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst
index 60e49974..473d49d9 100644
--- a/docs/contributing/issues-features.rst
+++ b/docs/contributing/issues-features.rst
@@ -77,4 +77,4 @@ the left side under the specific project.
 .. _Slack: https://slack.vyos.io
 .. _Forum: https://forum.vyos.io
 
-.. include:: ../common-references.rst
+.. include:: /common-references.rst
diff --git a/docs/interfaces/advanced-index.rst b/docs/interfaces/advanced-index.rst
deleted file mode 100644
index 7b9bde1e..00000000
--- a/docs/interfaces/advanced-index.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-.. _advanced_network-interfaces:
-
-##################
-Network Interfaces
-##################
-
-.. toctree::
-   :maxdepth: 1
-
-   bond
-   bridge
-   dummy
-   ethernet
-   geneve
-   loopback
-   l2tpv3
-   macsec
-   pppoe
-   pseudo-ethernet
-   tunnel
-   vxlan
-   wireless
-   wirelessmodem
diff --git a/docs/interfaces/basic-index.rst b/docs/interfaces/basic-index.rst
deleted file mode 100644
index 425792a2..00000000
--- a/docs/interfaces/basic-index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. _basic_network-interfaces:
-
-########################
-Basic Network Interfaces
-########################
-
-.. toctree::
-   :maxdepth: 1
-
-   ethernet
-   loopback
-   pppoe
diff --git a/docs/routing/bfd.rst b/docs/routing/bfd.rst
index 1d494332..b8fdf489 100644
--- a/docs/routing/bfd.rst
+++ b/docs/routing/bfd.rst
@@ -1,4 +1,4 @@
-.. include:: ../_include/need_improvement.txt
+.. include:: /_include/need_improvement.txt
 
 .. _routing-bfd:
 
diff --git a/docs/routing/ospf.rst b/docs/routing/ospf.rst
index fe05178b..19787b11 100644
--- a/docs/routing/ospf.rst
+++ b/docs/routing/ospf.rst
@@ -1,4 +1,4 @@
-.. include:: ../_include/need_improvement.txt
+.. include:: /_include/need_improvement.txt
 
 .. _routing-ospf:
 
diff --git a/docs/routing/rip.rst b/docs/routing/rip.rst
index 68868e37..0d73ad34 100644
--- a/docs/routing/rip.rst
+++ b/docs/routing/rip.rst
@@ -1,4 +1,4 @@
-.. include:: ../_include/need_improvement.txt
+.. include:: /_include/need_improvement.txt
 
 .. _rip:
 
diff --git a/docs/services/conntrack.rst b/docs/services/conntrack.rst
index c361d293..55cd088e 100644
--- a/docs/services/conntrack.rst
+++ b/docs/services/conntrack.rst
@@ -1,4 +1,4 @@
-.. include:: ../_include/need_improvement.txt
+.. include:: /_include/need_improvement.txt
 
 Conntrack
 ---------
diff --git a/docs/services/ipoe-server.rst b/docs/services/ipoe-server.rst
index 3aedf966..279f0c6d 100644
--- a/docs/services/ipoe-server.rst
+++ b/docs/services/ipoe-server.rst
@@ -1,4 +1,4 @@
-.. include:: ../_include/need_improvement.txt
+.. include:: /_include/need_improvement.txt
 
 .. _ipoe_server:
 
@@ -146,4 +146,4 @@ The rate-limit is set in kbit/sec.
   -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------
   ipoe0  | eth2       | 08:00:27:2f:d8:06 | 192.168.0.2 |     |        | 500/500    | active | 00:00:05 | dccc870fd31349fb
 
-.. include:: ../common-references.rst
+.. include:: /common-references.rst
diff --git a/docs/services/pppoe-server.rst b/docs/services/pppoe-server.rst
index e710ba6a..4deb6c7e 100644
--- a/docs/services/pppoe-server.rst
+++ b/docs/services/pppoe-server.rst
@@ -394,4 +394,4 @@ a /56 subnet for the clients internal use.
   --------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+----------
    ppp0   | test     | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb |            | active | 00:00:49 | 875 B    | 2.1 KiB
 
-.. include:: ../common-references.rst
+.. include:: /common-references.rst
diff --git a/docs/system/lcd.rst b/docs/system/lcd.rst
index 441becf5..2509946e 100644
--- a/docs/system/lcd.rst
+++ b/docs/system/lcd.rst
@@ -41,5 +41,5 @@ Configuration
    .. note:: We can't support all displays from the beginning. If your display
       type is missing, please create a feature request via Phabricator_.
 
-.. include:: ../common-references.rst
+.. include:: /common-references.rst
 
diff --git a/docs/vpn/sstp.rst b/docs/vpn/sstp.rst
index e5567cb6..f5e4ad05 100644
--- a/docs/vpn/sstp.rst
+++ b/docs/vpn/sstp.rst
@@ -344,4 +344,4 @@ A connection attempt will be shown as:
 
 .. _sstpc: https://github.com/reliablehosting/sstp-client
 
-.. include:: ../common-references.rst
+.. include:: /common-references.rst
-- 
cgit v1.2.3