interfaces: use common toc and chapter style

docs/interfaces/advanced-index.rst

@@ -1,8 +1,8 @@
 .. _advanced_network-interfaces:
 
-###########################
+##################
-Advanced Network Interfaces
+Network Interfaces
-###########################
+##################
 
 .. toctree::
    :maxdepth: 1
@@ -15,6 +15,7 @@ Advanced Network Interfaces
    loopback
    l2tpv3
    macsec
+   pppoe
    pseudo-ethernet
    qinq
    tunnel

docs/interfaces/bond.rst

@@ -10,32 +10,35 @@ or port-channel. The behavior of the bonded interfaces depends upon the mode;
 generally speaking, modes provide either hot standby or load balancing services.
 Additionally, link integrity monitoring may be performed.
 
+*************
 Configuration
-#############
+*************
 
 Common interface configuration
-------------------------------
+==============================
 
 .. cmdinclude:: ../_include/interface-common-with-dhcp.txt
    :var0: bond
    :var1: bond0
 
 Member Interfaces
------------------
+=================
 
 .. cfgcmd:: set interfaces bonding <interface> member interface <member>
 
    Enslave `<member>` interface to bond `<interface>`.
 
 Bond options
-------------
+============
 
-.. cfgcmd:: set interfaces bonding <interface> mode <mode>
+.. cfgcmd:: set interfaces bonding <interface> mode <802.3ad | active-backup |
+  broadcast | round-robin | transmit-load-balance | adaptive-load-balance |
+  xor-hash>
 
    Specifies one of the bonding policies. The default is 802.3ad. Possible
    values are:
 
-   * **802.3ad** - IEEE 802.3ad Dynamic link aggregation. Creates aggregation
+   * ``802.3ad`` - IEEE 802.3ad Dynamic link aggregation. Creates aggregation
      groups that share the same speed and duplex settings. Utilizes all slaves
      in the active aggregator according to the 802.3ad specification.
 
@@ -47,7 +50,7 @@ Bond options
         in regards to the packet mis-ordering requirements of section 43.2.4
         of the 802.3ad standard.
 
-   * **active-backup** - Active-backup policy: Only one slave in the bond is
+   * ``active-backup`` - Active-backup policy: Only one slave in the bond is
      active. A different slave becomes active if, and only if, the active slave
      fails. The bond's MAC address is externally visible on only one port
      (network adapter) to avoid confusing the switch.
@@ -62,24 +65,24 @@ Bond options
      This mode provides fault tolerance. The :cfgcmd:`primary` option,
      documented below, affects the behavior of this mode.
 
-   * **broadcast** - Broadcast policy: transmits everything on all slave
+   * ``broadcast`` - Broadcast policy: transmits everything on all slave
      interfaces.
 
      This mode provides fault tolerance.
 
-   * **round-robin** - Round-robin policy: Transmit packets in sequential
+   * ``round-robin`` - Round-robin policy: Transmit packets in sequential
      order from the first available slave through the last.
 
      This mode provides load balancing and fault tolerance.
 
-   * **transmit-load-balance** - Adaptive transmit load balancing: channel
+   * ``transmit-load-balance`` - Adaptive transmit load balancing: channel
      bonding that does not require any special switch support.
 
      Incoming traffic is received by the current slave. If the receiving slave
      fails, another slave takes over the MAC address of the failed receiving
      slave.
 
-   * **adaptive-load-balance** - Adaptive load balancing: includes
+   * ``adaptive-load-balance`` - Adaptive load balancing: includes
      transmit-load-balance plus receive load balancing for IPV4 traffic, and
      does not require any special switch support. The receive load balancing
      is achieved by ARP negotiation. The bonding driver intercepts the ARP
@@ -111,7 +114,7 @@ Bond options
      than the switch's forwarding delay so that the ARP Replies sent to the
      peers will not be blocked by the switch.
 
-   * **xor-hash** - XOR policy: Transmit based on the selected transmit
+   * ``xor-hash`` - XOR policy: Transmit based on the selected transmit
      hash policy.  The default policy is a simple [(source MAC address XOR'd
      with destination MAC address XOR packet type ID) modulo slave count].
      Alternate transmit policies may be selected via the :cfgcmd:`hash-policy`
@@ -253,8 +256,9 @@ Bond options
    The maximum number of targets that can be specified is 16. The default value
    is no IP addresses.
 
+*******
 Example
--------
+*******
 
 The following configuration on VyOS applies to all following 3rd party vendors.
 It creates a bond with two links and VLAN 10, 100 on the bonded interfaces with
@@ -275,7 +279,7 @@ a per VIF IPv4 address.
   set interfaces bonding bond0 member interface eth2
 
 Cisco Catalyst
-^^^^^^^^^^^^^^
+==============
 
 Assign member interfaces to PortChannel
 
@@ -305,7 +309,7 @@ allowed VLAN interfaces, STP will happen here.
 
 
 Juniper EX Switch
-^^^^^^^^^^^^^^^^^
+=================
 
 For a headstart you can use the below example on how to build a bond with two
 interfaces from VyOS to a Juniper EX Switch system.
@@ -334,7 +338,7 @@ interfaces from VyOS to a Juniper EX Switch system.
   set interfaces xe-1/1/0 ether-options 802.3ad ae0
 
 Aruba/HP
-^^^^^^^^
+========
 
 For a headstart you can use the below example on how to build a bond,port-channel
 with two interfaces from VyOS to a Aruba/HP 2510G switch.
@@ -349,7 +353,7 @@ with two interfaces from VyOS to a Aruba/HP 2510G switch.
   vlan 100 tagged Trk1
 
 Arista EOS
-^^^^^^^^^^
+==========
 
 When utilizing VyOS in an environment with Arista gear you can use this blue
 print as an initial setup to get an LACP bond / port-channel operational between
@@ -463,8 +467,9 @@ Lets assume the following topology:
    virtio network driver no LACP PDUs will be sent by VyOS thus the port-channel
    will never become active!
 
+*********
 Operation
-#########
+*********
 
 .. opcmd:: show interfaces bonding
 

docs/interfaces/bridge.rst

@@ -14,18 +14,19 @@ 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>
 
@@ -59,6 +60,24 @@ Member Interfaces
    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
@@ -94,26 +113,9 @@ links providing fault tolerance if an active link fails.
    Designated Bridges. Hello packets are used to communicate information
    about the topology throughout the entire Bridged Local Area Network.
 
-Additional 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
-
 Example
-#######
+*******
 
 Creating a bridge interface is very simple. In this example we will
 have:
@@ -146,9 +148,9 @@ This results in the active configuration:
     }
     stp
 
-
+*******
-Operation
+Example
-#########
+*******
 
 .. opcmd:: show bridge
 

docs/interfaces/dummy.rst

@@ -18,12 +18,12 @@ you can have as many as you want.
    destination. A :ref:`dummy-interface` Interface should always be preferred
    over a :ref:`loopback-interface` interface.
 
-
+*************
 Configuration
-#############
+*************
 
 Common interface configuration
-------------------------------
+==============================
 
 .. cmdinclude:: ../_include/interface-address.txt
    :var0: dummy
@@ -41,8 +41,9 @@ Common interface configuration
    :var0: dummy
    :var1: dum0
 
+*********
 Operation
-=========
+*********
 
 .. opcmd:: show interfaces dummy
 

docs/interfaces/ethernet.rst

@@ -4,18 +4,22 @@
 Ethernet
 ########
 
+This will be the most widely used interface on a router carrying traffic to the
+real world.
+
+*************
 Configuration
-#############
+*************
 
 Common interface configuration
-------------------------------
+==============================
 
 .. cmdinclude:: ../_include/interface-common-with-dhcp.txt
    :var0: ethernet
    :var1: eth0
 
-Speed/Duplex
+Ethernet options
-------------
+================
 
 .. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half>
 
@@ -45,15 +49,9 @@ Speed/Duplex
 
    VyOS default will be `auto`.
 
-VLAN (802.1q) configuration
+*********
----------------------------
-
-.. cmdinclude:: ../_include/interface-vlan.txt
-   :var0: ethernet
-   :var1: eth0
-
 Operation
-=========
+*********
 
 .. opcmd:: show interfaces ethernet
 

docs/interfaces/geneve.rst

@@ -32,18 +32,19 @@ Geneve Header:
   |                    Variable Length Options                    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 
+*************
 Configuration
-=============
+*************
 
 Common interface configuration
-------------------------------
+==============================
 
 .. cmdinclude:: ../_include/interface-common-without-dhcp.txt
    :var0: geneve
    :var1: gnv0
 
-GENEVE specific options
+GENEVE options
------------------------
+==============
 
 .. cfgcmd:: set interfaces geneve gnv0 remote <address>
 

docs/interfaces/l2tpv3.rst

@@ -6,22 +6,83 @@
 L2TPv3
 ######
 
-L2TPv3 is a pseudowire protocol, you can read more about on `Wikipedia L2TPv3`_
+Layer 2 Tunnelling Protocol Version 3 is an IETF standard related to L2TP that
-or in :rfc:`3921`
+can be used as an alternative protocol to :ref:`mpls` for encapsulation of
+multiprotocol Layer 2 communications traffic over IP networks. Like L2TP,
+L2TPv3 provides a pseudo-wire service, but scaled to fit carrier requirements.
 
-L2TPv3 can transport any traffic including ethernet frames. L2TPv2 is limited
+L2TPv3 can be regarded as being to MPLS what IP is to ATM: a simplified version
-to PPP.
+of the same concept, with much of the same benefit achieved at a fraction of the
+effort, at the cost of losing some technical features considered less important
+in the market.
 
+In the case of L2TPv3, the features lost are teletraffic engineering features
+considered important in MPLS. However, there is no reason these features could
+not be re-engineered in or on top of L2TPv3 in later products.
+
+The protocol overhead of L2TPv3 is also significantly bigger than MPLS.
+
+L2TPv3 is described in :rfc:`3921`.
+
+*************
 Configuration
-#############
+*************
 
 Common interface configuration
-------------------------------
+==============================
 
 .. cmdinclude:: ../_include/interface-common-without-dhcp.txt
    :var0: l2tpv3
    :var1: l2tpeth0
 
+L2TPv3 options
+==============
+
+.. cfgcmd:: set interfaces l2tpv3 <interface> encapsulation <udp | ip>
+
+  Set the encapsulation type of the tunnel. Valid values for encapsulation are:
+  udp, ip.
+
+  This defaults to UDP
+
+.. cfgcmd:: set interfaces l2tpv3 <interface> local-ip <address>
+
+  set the IP address of the local interface to be used for the tunnel.
+
+  This address must be the address of a local interface. May be specified as an
+  IPv4 address or an IPv6 address.
+
+.. cfgcmd:: set interfaces l2tpv3 <interface> remote-ip <address>
+
+  Set the IP address of the remote peer. May be specified as an IPv4 address or
+  an IPv6 address.
+
+.. cfgcmd:: set interfaces l2tpv3 <interface> session-id <id>
+
+  Set the session id, which is a 32-bit integer value. Uniquely identifies the
+  session being created. The value used must match the peer_session_id value
+  being used at the peer.
+
+.. cfgcmd:: set interfaces l2tpv3 <interface> peer-session-id <id>
+
+  Set the peer session id, which is a 32-bit integer value assigned to the
+  session by the peer. The value used must match the session_id value being
+  used at the peer.
+
+.. cfgcmd:: set interfaces l2tpv3 <interface> tunnel-id <id>
+
+  Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the
+  tunnel into which the session will be created.
+
+.. cfgcmd:: set interfaces l2tpv3 <interface> peer-tunnel-id <id>
+
+  Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the
+  tunnel into which the session will be created.
+
+*******
+Example
+*******
+
 Over IP
 ^^^^^^^
 
@@ -129,5 +190,3 @@ L2TPv3:
   set interfaces l2tpv3 l2tpeth0 session-id '110'
   set interfaces l2tpv3 l2tpeth0 source-port '5000'
   set interfaces l2tpv3 l2tpeth0 tunnel-id '10'
-
-.. _`Wikipedia L2TPv3`: https://en.wikipedia.org/wiki/L2TPv3

docs/interfaces/loopback.rst

@@ -19,11 +19,12 @@ services on your local machine.
    destination. A :ref:`dummy-interface` Interface should always be preferred
    over a :ref:`loopback-interface` interface.
 
+*************
 Configuration
-=============
+*************
 
 Common interface configuration
-------------------------------
+==============================
 
 .. cmdinclude:: ../_include/interface-address.txt
    :var0: loopback
@@ -33,8 +34,9 @@ Common interface configuration
    :var0: loopback
    :var1: lo
 
+*********
 Operation
-=========
+*********
 
 .. opcmd:: show interfaces loopback
 

docs/interfaces/macsec.rst

@@ -13,18 +13,19 @@ including DHCP or ARP requests. It does not compete with other security
 solutions such as IPsec (layer 3) or TLS (layer 4), as all those solutions are
 used for their own specific use cases.
 
+*************
 Configuration
-#############
+*************
 
 Common interface configuration
-------------------------------
+==============================
 
 .. cmdinclude:: ../_include/interface-common-with-dhcp.txt
    :var0: macsec
    :var1: macsec0
 
-MACsec specific options
+MACsec options
------------------------
+==============
 
 .. cfgcmd:: set interfaces macsec <interface> security cipher [gcm-aes-128]
 
@@ -45,7 +46,7 @@ MACsec specific options
   leaving this interfac will now be authenticated/encrypted.
 
 Key Management
-^^^^^^^^^^^^^^
+--------------
 
 :abbr:`MKA (MACsec Key Agreement protocol)` is used to synchronize keys between
 individual peers.
@@ -65,7 +66,7 @@ individual peers.
   distributing SAKs.
 
 Replay protection
-^^^^^^^^^^^^^^^^^
+-----------------
 
 .. cfgcmd:: set interfaces macsec <interface> security replay-window <window>
 
@@ -76,8 +77,9 @@ Replay protection
   - ``0``: No replay window, strict check
   - ``1-4294967295``: Number of packets that could be misordered
 
+*********
 Operation
-#########
+*********
 
 .. opcmd:: run generate macsec mka-cak
 
@@ -123,8 +125,9 @@ Operation
         cipher suite: GCM-AES-128, using ICV length 16
         TXSC: 005056bfefaa0001 on SA 0
 
+********
 Examples
-########
+********
 
 * Two routers connected both via eth1 through an untrusted switch
 * R1 has 192.0.2.1/24 & 2001:db8::1/64

docs/interfaces/pppoe.rst

@@ -14,15 +14,16 @@ encryption, and compression." Typical use of PPPoE involves leveraging the
 PPP facilities for authenticating the user with a username and password,
 predominately via the PAP protocol and less often via CHAP.
 
+***************
 Operating Modes
-===============
+***************
 
 VyOS supports setting up PPPoE in two different ways to a PPPoE internet
 connection. This is due to most ISPs provide a modem that is also a wireless
 router.
 
 Home Users
-----------
+==========
 
 In this method, the DSL Modem/Router connects to the ISP for you with your
 credentials preprogrammed into the device. This gives you an :rfc:`1918`
@@ -35,7 +36,7 @@ few extra layers of complexity, particularly if you use some NAT or
 tunnel features.
 
 Business Users
---------------
+==============
 
 In order to have full control and make use of multiple static public IP
 addresses, your VyOS will have to initiate the PPPoE connection and control
@@ -51,11 +52,12 @@ configure it to open the PPPoE session for you and your DSL Transceiver
 (Modem/Router) just acts to translate your messages in a way that
 vDSL/aDSL understands.
 
+*************
 Configuration
-=============
+*************
 
 Common interface configuration
-------------------------------
+==============================
 
 .. cmdinclude:: ../_include/interface-description.txt
    :var0: pppoe
@@ -69,8 +71,8 @@ Common interface configuration
    :var0: pppoe
    :var1: pppoe0
 
-PPPoE specific configuration
+PPPoE options
-----------------------------
+=============
 
 .. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name>
 
@@ -179,8 +181,9 @@ IPv6
   :var0: pppoe
   :var1: pppoe0
 
+*********
 Operation
-=========
+*********
 
 .. opcmd:: show interfaces pppoe <interface>
 
@@ -211,7 +214,7 @@ Operation
       backlog 0b 0p requeues 0
 
 Connect/Disconnect
-------------------
+==================
 
 .. opcmd:: disconnect interface <interface>
 
@@ -223,8 +226,9 @@ Connect/Disconnect
    Test connecting given connection-oriented interface. `<interface>` can be
    ``pppoe0`` as example.
 
+*******
 Example
-=======
+*******
 
 Requirements:
 

docs/interfaces/pseudo-ethernet.rst

@@ -38,18 +38,19 @@ Ethernet interfaces:
   - Network switches with security settings allowing only a single MAC address
   - xDSL modems that try to lear the MAC address of the NIC
 
+*************
 Configuration
-=============
+*************
 
 Common interface configuration
-------------------------------
+==============================
 
 .. cmdinclude:: ../_include/interface-common-with-dhcp.txt
    :var0: pseudo-ethernet
    :var1: peth0
 
-Pseudo Ethernet/MACVLAN specific options
+Pseudo Ethernet/MACVLAN options
-----------------------------------------
+===============================
 
 .. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX>
 

docs/interfaces/wirelessmodem.rst

@@ -4,15 +4,16 @@
 WirelessModem (WWAN)
 ####################
 
-Configuration
+The wirelessmodem interface provides access (through a wireless modem/wwan)
-#############
+to wireless networks provided by various cellular providers. VyOS uses the
-
-The wirelessmodem interface provides access (through a wireless modem/wwan) to
-wireless networks provided by various cellular providers. VyOS uses the
 interfaces wirelessmodem subsystem for configuration.
 
+*************
+Configuration
+*************
+
 Common interface configuration
-------------------------------
+==============================
 
 .. cmdinclude:: ../_include/interface-description.txt
    :var0: wirelessmodem
@@ -26,8 +27,8 @@ Common interface configuration
    :var0: wirelessmodem
    :var1: wlm0
 
-WWAN specific options
+WirelessModem (WWAN) options
----------------------
+============================
 
 .. cfgcmd:: set interfaces wirelessmodem <interface> apn <apn>
 
@@ -59,23 +60,9 @@ WWAN specific options
    connection is established at boot time and remains up. If the link fails for
    any reason, the link is brought back up immediately.
 
-Example
+*********
-=======
-
-The following example is based on a Sierra Wireless MC7710 miniPCIe card (only
-the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card
-is assembled into a :ref:`pc-engines-apu4`.
-
-.. code-block:: none
-
-  set interfaces wirelessmodem wlm0 apn 'internet.telekom'
-  set interfaces wirelessmodem wlm0 backup distance '100'
-  set interfaces wirelessmodem wlm0 device 'ttyUSB2'
-  set interfaces wirelessmodem wlm0 disable
-  set interfaces wirelessmodem wlm0 no-peer-dns
-
 Operation
-=========
+*********
 
 .. opcmd:: show interfaces wirelessmodem <interface>
 
@@ -109,8 +96,26 @@ Operation
 
    Displays log information for a WWAN interface.
 
+
+*******
+Example
+*******
+
+The following example is based on a Sierra Wireless MC7710 miniPCIe card (only
+the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card
+is assembled into a :ref:`pc-engines-apu4`.
+
+.. code-block:: none
+
+  set interfaces wirelessmodem wlm0 apn 'internet.telekom'
+  set interfaces wirelessmodem wlm0 backup distance '100'
+  set interfaces wirelessmodem wlm0 device 'ttyUSB2'
+  set interfaces wirelessmodem wlm0 disable
+  set interfaces wirelessmodem wlm0 no-peer-dns
+
+*****************
 Supported Modules
-#################
+*****************
 
 The following hardware modules have been tested successfully in an
 :ref:`pc-engines-apu4` board:
@@ -120,4 +125,4 @@ The following hardware modules have been tested successfully in an
 * Sierra Wireless AirPrime MC7455 miniPCIe card (LTE)
 * Sierra Wireless AirPrime MC7710 miniPCIe card (LTE)
 * Huawei ME909u-521 miniPCIe card (LTE)
-
+* Huawei ME909s-120 miniPCIe card (LTE)

docs/routing/mpls.rst

@@ -1,8 +1,8 @@
 .. _mpls:
 
-####
+####################################
-MPLS
+MPLS (Multiprotocol Label Switching)
-####
+####################################
 
 :abbr:`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm
 which differs from regular IP forwarding. Instead of IP addresses being used to