Merge remote-tracking branch 'origin/sagitta' into fix/docs-html-title-sagitta

# Conflicts:
#	docs/conf.py

40 files changed, 6028 insertions, 0 deletions

diff --git a/docs/configuration/interfaces/bonding.md b/docs/configuration/interfaces/bonding.md
new file mode 100644
index 00000000..ef6988e5
--- /dev/null
+++ b/docs/configuration/interfaces/bonding.md
@@ -0,0 +1,671 @@
+---
+lastproofread: '2021-06-30'
+---
+
+(bond-interface)=
+
+# Bond / Link Aggregation
+
+The bonding interface provides a method for aggregating multiple network
+interfaces into a single logical "bonded" interface, or LAG, or ether-channel,
+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
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: bonding
+   :var1: bond0
+```
+
+### Member Interfaces
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> member interface <member>
+
+   Enslave `<member>` interface to bond `<interface>`.
+```
+
+### Bond options
+
+```{eval-rst}
+.. 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
+     groups that share the same speed and duplex settings. Utilizes all slaves
+     in the active aggregator according to the 802.3ad specification.
+
+     Slave selection for outgoing traffic is done according to the transmit
+     hash policy, which may be changed from the default simple XOR policy via
+     the {cfgcmd}`hash-policy` option, documented below.
+
+     .. note:: Not all transmit policies may be 802.3ad compliant, particularly
+        in regards to the packet misordering requirements of section 43.2.4
+        of the 802.3ad standard.
+
+   * ``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.
+
+     When a failover occurs in active-backup mode, bonding will issue one or
+     more gratuitous ARPs on the newly active slave. One gratuitous ARP is
+     issued for the bonding master interface and each VLAN interfaces
+     configured above it, provided that the interface has at least one IP
+     address configured. Gratuitous ARPs issued for VLAN interfaces are tagged
+     with the appropriate VLAN id.
+
+     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
+     interfaces.
+
+     This mode provides fault tolerance.
+
+   * ``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
+     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
+     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
+     Replies sent by the local system on their way out and overwrites the
+     source hardware address with the unique hardware address of one of the
+     slaves in the bond such that different peers use different hardware
+     addresses for the server.
+
+     Receive traffic from connections created by the server is also balanced.
+     When the local system sends an ARP Request the bonding driver copies and
+     saves the peer's IP information from the ARP packet. When the ARP Reply
+     arrives from the peer, its hardware address is retrieved and the bonding
+     driver initiates an ARP reply to this peer assigning it to one of the
+     slaves in the bond. A problematic outcome of using ARP negotiation for
+     balancing is that each time that an ARP request is broadcast it uses the
+     hardware address of the bond. Hence, peers learn the hardware address
+     of the bond and the balancing of receive traffic collapses to the current
+     slave. This is handled by sending updates (ARP Replies) to all the peers
+     with their individually assigned hardware address such that the traffic
+     is redistributed. Receive traffic is also redistributed when a new slave
+     is added to the bond and when an inactive slave is re-activated. The
+     receive load is distributed sequentially (round robin) among the group
+     of highest speed slaves in the bond.
+
+     When a link is reconnected or a new slave joins the bond the receive
+     traffic is redistributed among all active slaves in the bond by initiating
+     ARP Replies with the selected MAC address to each of the clients. The
+     updelay parameter (detailed below) must be set to a value equal or greater
+     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
+     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`
+     option, described below.
+
+     This mode provides load balancing and fault tolerance.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> min-links <0-16>
+
+   Specifies the minimum number of links that must be active before asserting
+   carrier. It is similar to the Cisco EtherChannel min-links feature. This
+   allows setting the minimum number of member ports that must be up (link-up
+   state) before marking the bond device as up (carrier on). This is useful for
+   situations where higher level services such as clustering want to ensure a
+   minimum number of low bandwidth links are active before switchover.
+
+   This option only affects 802.3ad mode.
+
+   The default value is 0. This will cause the carrier to be asserted
+   (for 802.3ad mode) whenever there is an active aggregator,
+   regardless of the number of available links in that aggregator.
+
+   .. note:: Because an aggregator cannot be active without at least one
+      available link, setting this option to 0 or to 1 has the exact same
+      effect.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> lacp-rate <slow|fast>
+
+   Option specifying the rate in which we'll ask our link partner to transmit
+   LACPDU packets in 802.3ad mode.
+
+   This option only affects 802.3ad mode.
+
+   * slow: Request partner to transmit LACPDUs every 30 seconds
+
+   * fast: Request partner to transmit LACPDUs every 1 second
+
+   The default value is slow.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> system-mac <mac address>
+
+   This option allow to specifies the 802.3ad system MAC address.You can set a
+   random mac-address that can be used for these LACPDU exchanges.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> hash-policy <policy>
+
+   * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field
+     to generate the hash. The formula is
+
+     .. code-block:: none
+
+       hash = source MAC XOR destination MAC XOR packet type ID
+       slave number = hash modulo slave count
+
+     This algorithm will place all traffic to a particular network peer on
+     the same slave.
+
+     This algorithm is 802.3ad compliant.
+
+   * **layer2+3** - This policy uses a combination of layer2 and layer3
+     protocol information to generate the hash. Uses XOR of hardware MAC
+     addresses and IP addresses to generate the hash. The formula is:
+
+     .. code-block:: none
+
+       hash = source MAC XOR destination MAC XOR packet type ID
+       hash = hash XOR source IP XOR destination IP
+       hash = hash XOR (hash RSHIFT 16)
+       hash = hash XOR (hash RSHIFT 8)
+
+     And then hash is reduced modulo slave count.
+
+     If the protocol is IPv6 then the source and destination addresses are
+     first hashed using ipv6_addr_hash.
+
+     This algorithm will place all traffic to a particular network peer on the
+     same slave. For non-IP traffic, the formula is the same as for the layer2
+     transmit hash policy.
+
+     This policy is intended to provide a more balanced distribution of traffic
+     than layer2 alone, especially in environments where a layer3 gateway
+     device is required to reach most destinations.
+
+     This algorithm is 802.3ad compliant.
+
+   * **layer3+4** - This policy uses upper layer protocol information, when
+     available, to generate the hash. This allows for traffic to a particular
+     network peer to span multiple slaves, although a single connection will
+     not span multiple slaves.
+
+     The formula for unfragmented TCP and UDP packets is
+
+     .. code-block:: none
+
+       hash = source port, destination port (as in the header)
+       hash = hash XOR source IP XOR destination IP
+       hash = hash XOR (hash RSHIFT 16)
+       hash = hash XOR (hash RSHIFT 8)
+
+     And then hash is reduced modulo slave count.
+
+     If the protocol is IPv6 then the source and destination addresses are
+     first hashed using ipv6_addr_hash.
+
+     For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol
+     traffic, the source and destination port information is omitted. For
+     non-IP traffic, the formula is the same as for the layer2 transmit hash
+     policy.
+
+     This algorithm is not fully 802.3ad compliant. A single TCP or UDP
+     conversation containing both fragmented and unfragmented packets will see
+     packets striped across two interfaces. This may result in out of order
+     delivery. Most traffic types will not meet these criteria, as TCP rarely
+     fragments traffic, and most UDP traffic is not involved in extended
+     conversations. Other implementations of 802.3ad may or may not tolerate
+     this noncompliance.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> primary <interface>
+
+    An `<interface>` specifying which slave is the primary device. The specified
+    device will always be the active slave while it is available. Only when the
+    primary is off-line will alternate devices be used. This is useful when one
+    slave is preferred over another, e.g., when one slave has higher throughput
+    than another.
+
+    The primary option is only valid for active-backup, transmit-load-balance,
+    and adaptive-load-balance mode.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> arp-monitor interval <time>
+
+   Specifies the ARP link monitoring `<time>` in seconds.
+
+   The ARP monitor works by periodically checking the slave devices to determine
+   whether they have sent or received traffic recently (the precise criteria
+   depends upon the bonding mode, and the state of the slave). Regular traffic
+   is generated via ARP probes issued for the addresses specified by the
+   {cfgcmd}`arp-monitor target` option.
+
+   If ARP monitoring is used in an etherchannel compatible mode (modes
+   round-robin and xor-hash), the switch should be configured in a mode that
+   evenly distributes packets across all links. If the switch is configured to
+   distribute the packets in an XOR fashion, all replies from the ARP targets
+   will be received on the same link which could cause the other team members
+   to fail.
+
+   A value of 0 disables ARP monitoring. The default value is 0.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> arp-monitor target <address>
+
+   Specifies the IP addresses to use as ARP monitoring peers when
+   {cfgcmd}`arp-monitor interval` option is > 0. These are the targets of the
+   ARP request sent to determine the health of the link to the targets.
+
+   Multiple target IP addresses can be specified. At least one IP address must
+   be given for ARP monitoring to function.
+
+   The maximum number of targets that can be specified is 16. The default value
+   is no IP address.
+```
+
+### VLAN
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: bonding
+   :var1: bond0
+```
+
+### Port Mirror (SPAN)
+
+```{eval-rst}
+.. cmdincludemd:: ../../_include/interface-mirror.txt
+   :var0: bondinging
+   :var1: bond1
+   :var2: eth3
+```
+
+#### EVPN Multihoming
+
+All-Active Multihoming is used for redundancy and load sharing. Servers are
+attached to two or more PEs and the links are bonded (link-aggregation).
+This group of server links is referred to as an {abbr}`ES (Ethernet Segment)`.
+
+An Ethernet Segment can be configured by specifying a system-MAC and a local
+discriminator or a complete ESINAME against the bond interface on the PE.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> evpn es-id <<1-16777215|10-byte ID>
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> evpn es-sys-mac <xx:xx:xx:xx:xx:xx>
+
+  The sys-mac and local discriminator are used for generating a 10-byte, Type-3
+  Ethernet Segment ID. ESINAME is a 10-byte, Type-0 Ethernet Segment ID -
+  "00:AA:BB:CC:DD:EE:FF:GG:HH:II".
+
+  Type-1 (EAD-per-ES and EAD-per-EVI) routes are used to advertise the locally
+  attached ESs and to learn off remote ESs in the network. Local Type-2/MAC-IP
+  routes are also advertised with a destination ESI allowing for MAC-IP syncing
+  between Ethernet Segment peers. Reference: RFC 7432, RFC 8365
+
+  EVPN-MH is intended as a replacement for MLAG or Anycast VTEPs. In multihoming
+  each PE has an unique VTEP address which requires the introduction of a new
+  dataplane construct, MAC-ECMP. Here a MAC/FDB entry can point to a list of
+  remote PEs/VTEPs.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> evpn es-df-pref <1-65535>
+
+  Type-4 (ESR) routes are used for Designated Forwarder (DF) election.
+  DFs forward BUM traffic received via the overlay network. This
+  implementation uses a preference based DF election specified by
+  draft-ietf-bess-evpn-pref-df.
+
+  The DF preference is configurable per-ES.
+
+  BUM traffic is rxed via the overlay by all PEs attached to a server but
+  only the DF can forward the de-capsulated traffic to the access port.
+  To accommodate that non-DF filters are installed in the dataplane to drop
+  the traffic.
+
+  Similarly traffic received from ES peers via the overlay cannot be forwarded
+  to the server. This is split-horizon-filtering with local bias.
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-evpn-uplink.txt
+   :var0: bonding
+   :var1: bond0
+```
+
+## 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
+a per VIF IPv4 address.
+
+```none
+# Create bonding interface bond0 with 802.3ad LACP
+set interfaces bonding bond0 hash-policy 'layer2'
+set interfaces bonding bond0 mode '802.3ad'
+
+# Add the required vlans and IPv4 addresses on them
+set interfaces bonding bond0 vif 10 address 192.168.0.1/24
+set interfaces bonding bond0 vif 100 address 10.10.10.1/24
+
+# Add the member interfaces to the bonding interface
+set interfaces bonding bond0 member interface eth1
+set interfaces bonding bond0 member interface eth2
+```
+
+:::{note}
+If you happen to run this in a virtual environment like by EVE-NG
+you need to ensure your VyOS NIC is set to use the e1000 driver. Using the
+default `virtio-net-pci` or the `vmxnet3` driver will not work. ICMP
+messages will not be properly processed. They are visible on the virtual wire
+but will not make it fully up the networking stack.
+
+You can check your NIC driver by issuing {opcmd}`show interfaces ethernet
+eth0 physical | grep -i driver`
+:::
+
+### Cisco Catalyst
+
+Assign member interfaces to PortChannel
+
+```none
+interface GigabitEthernet1/0/23
+ description VyOS eth1
+ channel-group 1 mode active
+!
+interface GigabitEthernet1/0/24
+ description VyOS eth2
+ channel-group 1 mode active
+!
+```
+
+A new interface becomes present `Port-channel1`, all configuration like
+allowed VLAN interfaces, STP will happen here.
+
+```none
+interface Port-channel1
+ description LACP Channel for VyOS
+ switchport trunk encapsulation dot1q
+ switchport trunk allowed vlan 10,100
+ switchport mode trunk
+ spanning-tree portfast trunk
+!
+```
+
+### 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.
+
+```none
+# Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s
+set interfaces ae0 aggregated-ether-options link-speed 10g
+set interfaces ae0 aggregated-ether-options lacp active
+
+# Create layer 2 on the aggregated ethernet device with trunking for our vlans
+set interfaces ae0 unit 0 family ethernet-switching port-mode trunk
+
+# Add the required vlans to the device
+set interfaces ae0 unit 0 family ethernet-switching vlan members 10
+set interfaces ae0 unit 0 family ethernet-switching vlan members 100
+
+# Add the two interfaces to the aggregated ethernet device, in this setup both
+# ports are on the same switch (switch 0, module 1, port 0 and 1)
+set interfaces xe-0/1/0 ether-options 802.3ad ae0
+set interfaces xe-0/1/1 ether-options 802.3ad ae0
+
+# But this can also be done with multiple switches in a stack, a virtual
+# chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches)
+set interfaces xe-0/1/0 ether-options 802.3ad ae0
+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.
+
+```none
+# Create trunk with 2 member interfaces (interface 1 and 2) and LACP
+trunk 1-2 Trk1 LACP
+
+# Add the required vlans to the trunk
+vlan 10 tagged Trk1
+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
+those two devices.
+
+Lets assume the following topology:
+
+:::{figure} /_static/images/vyos_arista_bond_lacp.png
+:alt: VyOS Arista EOS setup
+:::
+
+**R1**
+
+> ```none
+> interfaces {
+>     bonding bond10 {
+>         hash-policy layer3+4
+>         member {
+>             interface eth1
+>             interface eth2
+>         }
+>         mode 802.3ad
+>         vif 100 {
+>             address 192.0.2.1/30
+>             address 2001:db8::1/64
+>         }
+>     }
+> ```
+
+**R2**
+
+> ```none
+> interfaces {
+>     bonding bond10 {
+>         hash-policy layer3+4
+>         member {
+>             interface eth1
+>             interface eth2
+>         }
+>         mode 802.3ad
+>         vif 100 {
+>             address 192.0.2.2/30
+>             address 2001:db8::2/64
+>         }
+>     }
+> ```
+
+**SW1**
+
+> ```none
+> !
+> vlan 100
+>    name FOO
+> !
+> interface Port-Channel10
+>    switchport trunk allowed vlan 100
+>    switchport mode trunk
+>    spanning-tree portfast
+> !
+> interface Port-Channel20
+>    switchport mode trunk
+>    no spanning-tree portfast auto
+>    spanning-tree portfast network
+> !
+> interface Ethernet1
+>    channel-group 10 mode active
+> !
+> interface Ethernet2
+>    channel-group 10 mode active
+> !
+> interface Ethernet3
+>    channel-group 20 mode active
+> !
+> interface Ethernet4
+>    channel-group 20 mode active
+> !
+> ```
+
+**SW2**
+
+> ```none
+> !
+> vlan 100
+>    name FOO
+> !
+> interface Port-Channel10
+>    switchport trunk allowed vlan 100
+>    switchport mode trunk
+>    spanning-tree portfast
+> !
+> interface Port-Channel20
+>    switchport mode trunk
+>    no spanning-tree portfast auto
+>    spanning-tree portfast network
+> !
+> interface Ethernet1
+>    channel-group 10 mode active
+> !
+> interface Ethernet2
+>    channel-group 10 mode active
+> !
+> interface Ethernet3
+>    channel-group 20 mode active
+> !
+> interface Ethernet4
+>    channel-group 20 mode active
+> !
+> ```
+
+:::{note}
+When using EVE-NG to lab this environment ensure you are using e1000
+as the desired driver for your VyOS network interfaces. When using the
+regular virtio network driver no LACP PDUs will be sent by VyOS thus the
+port-channel will never become active!
+:::
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces bonding
+
+   Show brief interface information.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces bonding
+     Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+     Interface        IP Address                        S/L  Description
+     ---------        ----------                        ---  -----------
+     bond0            -                                 u/u  my-sw1 int 23 and 24
+     bond0.10         192.168.0.1/24                    u/u  office-net
+     bond0.100        10.10.10.1/24                     u/u  management-net
+
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces bonding <interface>
+
+   Show detailed information on given `<interface>`
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces bonding bond5
+     bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000
+         link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff
+         inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative
+            valid_lft forever preferred_lft forever
+
+         RX:  bytes  packets  errors  dropped  overrun       mcast
+                  0        0       0        0        0           0
+         TX:  bytes  packets  errors  dropped  carrier  collisions
+                  0        0       0        0        0           0
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces bonding <interface> detail
+
+   Show detailed information about the underlaying physical links on given
+   bond `<interface>`.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces bonding bond5 detail
+     Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011)
+
+     Bonding Mode: IEEE 802.3ad Dynamic link aggregation
+     Transmit Hash Policy: layer2 (0)
+     MII Status: down
+     MII Polling Interval (ms): 100
+     Up Delay (ms): 0
+     Down Delay (ms): 0
+
+     802.3ad info
+     LACP rate: slow
+     Min links: 0
+     Aggregator selection policy (ad_select): stable
+
+     Slave Interface: eth1
+     MII Status: down
+     Speed: Unknown
+     Duplex: Unknown
+     Link Failure Count: 0
+     Permanent HW addr: 00:50:56:bf:ef:aa
+     Slave queue ID: 0
+     Aggregator ID: 1
+     Actor Churn State: churned
+     Partner Churn State: churned
+     Actor Churned Count: 1
+     Partner Churned Count: 1
+
+     Slave Interface: eth2
+     MII Status: down
+     Speed: Unknown
+     Duplex: Unknown
+     Link Failure Count: 0
+     Permanent HW addr: 00:50:56:bf:19:26
+     Slave queue ID: 0
+     Aggregator ID: 2
+     Actor Churn State: churned
+     Partner Churn State: churned
+     Actor Churned Count: 1
+     Partner Churned Count: 1
+```
diff --git a/docs/configuration/interfaces/bridge.md b/docs/configuration/interfaces/bridge.md
new file mode 100644
index 00000000..409412c1
--- /dev/null
+++ b/docs/configuration/interfaces/bridge.md
@@ -0,0 +1,367 @@
+---
+lastproofread: '2021-06-30'
+---
+
+(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
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: bridge
+   :var1: br0
+```
+
+### Member Interfaces
+
+```{eval-rst}
+.. 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`.
+
+```
+
+```{eval-rst}
+.. 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 optimum
+   performance.
+
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> aging <time>
+
+   MAC address aging `<time`> in seconds (default: 300).
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> max-age <time>
+
+   Bridge maximum aging `<time>` in seconds (default: 20).
+
+   If an 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> igmp querier
+
+   Enable IGMP and MLD querier.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> igmp snooping
+
+   Enable IGMP and MLD snooping.
+```
+
+(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.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> stp
+
+   Enable spanning tree protocol. STP is disabled by default.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> forwarding-delay <delay>
+
+   Spanning Tree Protocol forwarding `<delay>` in seconds (default: 15).
+
+   The 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.
+
+```
+
+```{eval-rst}
+.. 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
+
+#### Enable VLAN-Aware Bridge
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> enable-vlan
+
+   To activate the VLAN aware bridge, you must activate this setting to use VLAN
+   settings for the bridge
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> protocol <802.1ad|802.1q>
+
+   Define used ethertype of bridge interface.
+
+   Ethertype ``0x8100`` is used for ``802.1q`` and ethertype ``0x88a8`` is used
+   for ``802.1ad``.
+
+   The default is ``802.1q``.
+```
+
+#### VLAN Options
+
+:::{note}
+It is not valid to use the `vif 1` option for VLAN aware bridges
+because VLAN aware bridges assume that all unlabeled packets belong to
+the default VLAN 1 member and that the VLAN ID of the bridge's parent
+interface is always 1
+:::
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: bridge
+   :var1: br0
+```
+
+```{eval-rst}
+.. 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
+
+   Example: Set `eth0` member port to be native VLAN 2
+
+   .. code-block:: none
+
+     set interfaces bridge br1 member interface eth0 native-vlan 2
+```
+
+```{eval-rst}
+.. 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: Set `eth0` member port to be allowed VLAN 4
+
+   .. code-block:: none
+
+     set interfaces bridge br1 member interface eth0 allowed-vlan 4
+
+   Example: Set `eth0` member port to be allowed VLAN 6-8
+
+   .. code-block:: none
+
+     set interfaces bridge br1 member interface eth0 allowed-vlan 6-8
+```
+
+### Port Mirror (SPAN)
+
+```{eval-rst}
+.. cmdincludemd:: ../../_include/interface-mirror.txt
+   :var0: bridge
+   :var1: br1
+   :var2: eth3
+```
+
+## Examples
+
+### Create a basic bridge
+
+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
+
+```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:
+
+```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
+```
+
+### Using VLAN aware Bridge
+
+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
+
+```none
+set interfaces bridge br100 enable-vlan
+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:
+
+```none
+vyos@vyos# show interfaces bridge br100
+ enable-vlan
+ 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
+ }
+```
+
+### Using the operation mode command to view Bridge Information
+
+```{eval-rst}
+.. opcmd:: show bridge
+
+   The `show bridge` operational command can be used to display
+   configured bridges:
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show bridge
+     3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding
+     priority 32 cost 100
+     4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding
+     priority 32 cost 100
+```
+
+```{eval-rst}
+.. opcmd:: show bridge <name> fdb
+
+   Show bridge `<name>` fdb displays the current forwarding table:
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show bridge br0 fdb
+     50:00:00:08:00:01 dev eth1 vlan 20 master br0 permanent
+     50:00:00:08:00:01 dev eth1 vlan 10 master br0 permanent
+     50:00:00:08:00:01 dev eth1 master br0 permanent
+     33:33:00:00:00:01 dev eth1 self permanent
+     33:33:00:00:00:02 dev eth1 self permanent
+     01:00:5e:00:00:01 dev eth1 self permanent
+     50:00:00:08:00:02 dev eth2 vlan 20 master br0 permanent
+     50:00:00:08:00:02 dev eth2 vlan 10 master br0 permanent
+     50:00:00:08:00:02 dev eth2 master br0 permanent
+     33:33:00:00:00:01 dev eth2 self permanent
+     33:33:00:00:00:02 dev eth2 self permanent
+     01:00:5e:00:00:01 dev eth2 self permanent
+     33:33:00:00:00:01 dev br0 self permanent
+     33:33:00:00:00:02 dev br0 self permanent
+     33:33:ff:08:00:01 dev br0 self permanent
+     01:00:5e:00:00:6a dev br0 self permanent
+     33:33:00:00:00:6a dev br0 self permanent
+     01:00:5e:00:00:01 dev br0 self permanent
+     33:33:ff:00:00:00 dev br0 self permanent
+```
+
+```{eval-rst}
+.. opcmd:: show bridge <name> mdb
+
+   Show bridge `<name>` mdb displays the current multicast group membership
+   table.The table is populated by IGMP and MLD snooping in the bridge driver
+   automatically.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show bridge br0 mdb
+     dev br0 port br0 grp ff02::1:ff00:0 temp vid 1
+     dev br0 port br0 grp ff02::2 temp vid 1
+     dev br0 port br0 grp ff02::1:ff08:1 temp vid 1
+     dev br0 port br0 grp ff02::6a temp vid 1
+```
+
+% 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
diff --git a/docs/configuration/interfaces/dummy.md b/docs/configuration/interfaces/dummy.md
new file mode 100644
index 00000000..246c3e7d
--- /dev/null
+++ b/docs/configuration/interfaces/dummy.md
@@ -0,0 +1,94 @@
+---
+lastproofread: '2023-01-20'
+---
+
+(dummy-interface)=
+
+# Dummy
+
+The dummy interface is really a little exotic, but rather useful nevertheless.
+Dummy interfaces are much like the {ref}`loopback-interface` interface, except
+you can have as many as you want.
+
+:::{note}
+Dummy interfaces can be used as interfaces that always stay up (in
+the same fashion to loopbacks in Cisco IOS), or for testing purposes.
+:::
+
+:::{hint}
+On systems with multiple redundant uplinks and routes,
+it's a good idea to use a dedicated address for management and dynamic routing protocols.
+However, assigning that address to a physical link is risky:
+if that link goes down, that address will become inaccessible.
+A common solution is to assign the management address to a loopback or a dummy interface
+and advertise that address via all physical links, so that it's reachable
+through any of them. Since in Linux-based systems, there can be only one loopback interface,
+it's better to use a dummy interface for that purpose, since they can be added, removed,
+and taken up and down independently.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-address.txt
+   :var0: dummy
+   :var1: dum0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+   :var0: dummy
+   :var1: dum0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable.txt
+   :var0: dummy
+   :var1: dum0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vrf.txt
+   :var0: dummy
+   :var1: dum0
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces dummy
+
+   Show brief interface information.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces dummy
+     Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+     Interface        IP Address                        S/L  Description
+     ---------        ----------                        ---  -----------
+     dum0             172.18.254.201/32                 u/u
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces dummy <interface>
+
+   Show detailed information on given `<interface>`
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces dummy dum0
+     dum0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000
+         link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff
+         inet 172.18.254.201/32 scope global dum0
+            valid_lft forever preferred_lft forever
+         inet6 fe80::247c:8eff:febc:fcf5/64 scope link
+            valid_lft forever preferred_lft forever
+
+         RX:  bytes    packets     errors    dropped    overrun      mcast
+                  0          0          0          0          0          0
+         TX:  bytes    packets     errors    dropped    carrier collisions
+            1369707       4267          0          0          0          0
+
+```
diff --git a/docs/configuration/interfaces/ethernet.md b/docs/configuration/interfaces/ethernet.md
new file mode 100644
index 00000000..66d388ea
--- /dev/null
+++ b/docs/configuration/interfaces/ethernet.md
@@ -0,0 +1,324 @@
+---
+lastproofread: '2023-01-20'
+---
+
+(ethernet-interface)=
+
+# Ethernet
+
+This will be the most widely used interface on a router carrying traffic to the
+real world.
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: ethernet
+   :var1: eth0
+```
+
+### Ethernet options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half>
+
+   Configure physical interface duplex setting.
+
+   * auto - interface duplex setting is auto-negotiated
+   * full - always use full-duplex
+   * half - always use half-duplex
+
+   VyOS default will be `auto`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 |
+  2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000>
+
+   Configure physical interface speed setting.
+
+   * auto - interface speed is auto-negotiated
+   * 10 - 10 MBit/s
+   * 100 - 100 MBit/s
+   * 1000 - 1 GBit/s
+   * 2500 - 2.5 GBit/s
+   * 5000 - 5 GBit/s
+   * 10000 - 10 GBit/s
+   * 25000 - 25 GBit/s
+   * 40000 - 40 GBit/s
+   * 50000 - 50 GBit/s
+   * 100000 - 100 GBit/s
+
+   VyOS default will be `auto`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interface ethernet <interface> ring-buffer rx <value>
+```
+
+```{eval-rst}
+.. cfgcmd:: set interface ethernet <interface> ring-buffer tx <value>
+
+  Configures the ring buffer size of the interface.
+
+  The supported values for a specific interface can be obtained
+  with: `ethtool -g <interface>`
+
+```
+
+#### Offloading
+
+```{eval-rst}
+.. cfgcmd:: set interfaces ethernet <interface> offload <gro | gso | lro | rps |
+  sg | tso>
+
+  Enable different types of hardware offloading on the given NIC.
+
+  {abbr}`LRO (Large Receive Offload)` is a technique designed to boost the
+  efficiency of how your computer's network interface card (NIC) processes
+  incoming network traffic. Typically, network data arrives in smaller chunks
+  called packets. Processing each packet individually consumes CPU (central
+  processing unit) resources. Lots of small packets can lead to a performance
+  bottleneck. Instead of handing the CPU each packet as it comes in, LRO
+  instructs the NIC to combine multiple incoming packets into a single, larger
+  packet. This larger packet is then passed to the CPU for processing.
+
+  .. note:: Under some circumstances, LRO is known to modify the packet headers
+     of forwarded traffic, which breaks the end-to-end principle of computer
+     networking. LRO is also only able to offload TCP segments encapsulated in
+     IPv4 packets. Due to these limitations, it is recommended to use GRO
+     (Generic Receive Offload) where possible. More information on the
+     limitations of LRO can be found here: https://lwn.net/Articles/358910/
+
+  {abbr}`GSO (Generic Segmentation Offload)` is a pure software offload that is
+  meant to deal with cases where device drivers cannot perform the offloads
+  described above. What occurs in GSO is that a given skbuff will have its data
+  broken out over multiple skbuffs that have been resized to match the MSS
+  provided via skb_shinfo()->gso_size.
+
+  Before enabling any hardware segmentation offload a corresponding software
+  offload is required in GSO. Otherwise it becomes possible for a frame to be
+  re-routed between devices and end up being unable to be transmitted.
+
+  {abbr}`GRO (Generic receive offload)` is the complement to GSO. Ideally any
+  frame assembled by GRO should be segmented to create an identical sequence of
+  frames using GSO, and any sequence of frames segmented by GSO should be able
+  to be reassembled back to the original by GRO. The only exception to this is
+  IPv4 ID in the case that the DF bit is set for a given IP header. If the
+  value of the IPv4 ID is not sequentially incrementing it will be altered so
+  that it is when a frame assembled via GRO is segmented via GSO.
+
+  {abbr}`RPS (Receive Packet Steering)` is logically a software implementation
+  of {abbr}`RSS (Receive Side Scaling)`. Being in software, it is necessarily
+  called later in the datapath. Whereas RSS selects the queue and hence CPU that
+  will run the hardware interrupt handler, RPS selects the CPU to perform
+  protocol processing above the interrupt handler. This is accomplished by
+  placing the packet on the desired CPU's backlog queue and waking up the CPU
+  for processing. RPS has some advantages over RSS:
+
+  - it can be used with any NIC
+  - software filters can easily be added to hash over new protocols
+  - it does not increase hardware device interrupt rate, although it does
+    introduce inter-processor interrupts (IPIs)
+
+  .. note:: In order to use TSO/LRO with VMXNET3 adapters, the SG offloading
+     option must also be enabled.
+```
+
+#### Authentication (EAPoL)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-eapol.txt
+   :var0: ethernet
+   :var1: eth0
+```
+
+#### EVPN Multihoming
+
+Uplink/Core tracking.
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-evpn-uplink.txt
+   :var0: ethernet
+   :var1: eth0
+```
+
+### VLAN
+
+#### Regular VLANs (802.1q)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: ethernet
+   :var1: eth0
+```
+
+#### QinQ (802.1ad)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021ad.txt
+   :var0: ethernet
+   :var1: eth0
+```
+
+### Port Mirror (SPAN)
+
+```{eval-rst}
+.. cmdincludemd:: ../../_include/interface-mirror.txt
+   :var0: ethernet
+   :var1: eth1
+   :var2: eth3
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces ethernet
+
+   Show brief interface information.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces ethernet
+     Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+     Interface        IP Address                        S/L  Description
+     ---------        ----------                        ---  -----------
+     eth0             172.18.201.10/24                  u/u  LAN
+     eth1             172.18.202.11/24                  u/u  WAN
+     eth2             -                                 u/D
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces ethernet <interface>
+
+   Show detailed information on given `<interface>`
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces ethernet eth0
+     eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
+         link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff
+         inet6 fe80::250:44ff:fe00:f5c9/64 scope link
+            valid_lft forever preferred_lft forever
+
+         RX:  bytes    packets     errors    dropped    overrun      mcast
+           56735451     179841          0          0          0     142380
+         TX:  bytes    packets     errors    dropped    carrier collisions
+            5601460      62595          0          0          0          0
+```
+
+
+```{eval-rst}
+.. opcmd:: show interfaces ethernet <interface> physical
+
+   Show information about physical `<interface>`
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces ethernet eth0 physical
+     Settings for eth0:
+             Supported ports: [ TP ]
+             Supported link modes:   1000baseT/Full
+                                     10000baseT/Full
+             Supported pause frame use: No
+             Supports auto-negotiation: No
+             Supported FEC modes: Not reported
+             Advertised link modes:  Not reported
+             Advertised pause frame use: No
+             Advertised auto-negotiation: No
+             Advertised FEC modes: Not reported
+             Speed: 10000Mb/s
+             Duplex: Full
+             Port: Twisted Pair
+             PHYAD: 0
+             Transceiver: internal
+             Auto-negotiation: off
+             MDI-X: Unknown
+             Supports Wake-on: uag
+             Wake-on: d
+             Link detected: yes
+     driver: vmxnet3
+     version: 1.4.16.0-k-NAPI
+     firmware-version:
+     expansion-rom-version:
+     bus-info: 0000:0b:00.0
+     supports-statistics: yes
+     supports-test: no
+     supports-eeprom-access: no
+     supports-register-dump: yes
+     supports-priv-flags: no
+```
+
+
+```{eval-rst}
+.. opcmd:: show interfaces ethernet <interface> physical offload
+
+   Show available offloading functions on given `<interface>`
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces ethernet eth0 physical offload
+     rx-checksumming               on
+     tx-checksumming               on
+     tx-checksum-ip-generic        on
+     scatter-gather                off
+     tx-scatter-gather             off
+     tcp-segmentation-offload      off
+     tx-tcp-segmentation           off
+     tx-tcp-mangleid-segmentation  off
+     tx-tcp6-segmentation          off
+     udp-fragmentation-offload     off
+     generic-segmentation-offload  off
+     generic-receive-offload       off
+     large-receive-offload         off
+     rx-vlan-offload               on
+     tx-vlan-offload               on
+     ntuple-filters                off
+     receive-hashing               on
+     tx-gre-segmentation           on
+     tx-gre-csum-segmentation      on
+     tx-udp_tnl-segmentation       on
+     tx-udp_tnl-csum-segmentation  on
+     tx-gso-partial                on
+     tx-nocache-copy               off
+     rx-all                        off
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces ethernet <interface> transceiver
+
+   Show transceiver information from plugin modules, e.g SFP+, QSFP
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces ethernet eth5 transceiver
+        Identifier              : 0x03 (SFP)
+        Extended identifier     : 0x04 (GBIC/SFP defined by 2-wire interface ID)
+        Connector               : 0x07 (LC)
+        Transceiver codes       : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00
+        Transceiver type        : Ethernet: 1000BASE-SX
+        Encoding                : 0x01 (8B/10B)
+        BR, Nominal             : 1300MBd
+        Rate identifier         : 0x00 (unspecified)
+        Length (SMF,km)         : 0km
+        Length (SMF)            : 0m
+        Length (50um)           : 550m
+        Length (62.5um)         : 270m
+        Length (Copper)         : 0m
+        Length (OM3)            : 0m
+        Laser wavelength        : 850nm
+        Vendor name             : CISCO-FINISAR
+        Vendor OUI              : 00:90:65
+        Vendor PN               : FTRJ-8519-7D-CS4
+        Vendor rev              : A
+        Option values           : 0x00 0x1a
+        Option                  : RX_LOS implemented
+        Option                  : TX_FAULT implemented
+        Option                  : TX_DISABLE implemented
+        BR margin, max          : 0%
+        BR margin, min          : 0%
+        Vendor SN               : FNS092xxxxx
+        Date code               : 0506xx
+```
diff --git a/docs/configuration/interfaces/geneve.md b/docs/configuration/interfaces/geneve.md
new file mode 100644
index 00000000..5c561fb8
--- /dev/null
+++ b/docs/configuration/interfaces/geneve.md
@@ -0,0 +1,101 @@
+---
+lastproofread: '2023-01-20'
+---
+
+(geneve-interface)=
+
+# GENEVE
+
+{abbr}`GENEVE (Generic Network Virtualization Encapsulation)` supports all of
+the capabilities of {abbr}`VXLAN (Virtual Extensible LAN)`, {abbr}`NVGRE
+(Network Virtualization using Generic Routing Encapsulation)`, and {abbr}`STT
+(Stateless Transport Tunneling)` and was designed to overcome their perceived
+limitations. Many believe GENEVE could eventually replace these earlier formats
+entirely.
+
+GENEVE is designed to support network virtualization use cases, where tunnels
+are typically established to act as a backplane between the virtual switches
+residing in hypervisors, physical switches, or middleboxes or other appliances.
+An arbitrary IP network can be used as an underlay although Clos networks - A
+technique for composing network fabrics larger than a single switch while
+maintaining non-blocking bandwidth across connection points. ECMP is used to
+divide traffic across the multiple links and switches that constitute the
+fabric. Sometimes termed "leaf and spine" or "fat tree" topologies.
+
+Geneve Header:
+
+```none
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|Ver|  Opt Len  |O|C|    Rsvd.  |          Protocol Type        |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|        Virtual Network Identifier (VNI)       |    Reserved   |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                    Variable Length Options                    |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-address.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-mac.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-mtu.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-ip.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-ipv6.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+### GENEVE options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces geneve gnv0 remote <address>
+
+   Configure GENEVE tunnel far end/remote tunnel endpoint.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces geneve gnv0 vni <vni>
+
+   {abbr}`VNI (Virtual Network Identifier)` is an identifier for a unique
+   element of a virtual network.  In many situations this may represent an L2
+   segment, however, the control plane defines the forwarding semantics of
+   decapsulated packets. The VNI MAY be used as part of ECMP forwarding
+   decisions or MAY be used as a mechanism to distinguish between overlapping
+   address spaces contained in the encapsulated packet when load balancing
+   across CPUs.
+```
diff --git a/docs/configuration/interfaces/index.md b/docs/configuration/interfaces/index.md
new file mode 100644
index 00000000..39546bae
--- /dev/null
+++ b/docs/configuration/interfaces/index.md
@@ -0,0 +1,28 @@
+# Interfaces
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   bonding
+   bridge
+   dummy
+   ethernet
+   geneve
+   l2tpv3
+   loopback
+   macsec
+   openvpn
+   wireguard
+   pppoe
+   pseudo-ethernet
+   sstp-client
+   tunnel
+   virtual-ethernet
+   vti
+   vxlan
+   wireless
+   wwan
+
+```
diff --git a/docs/configuration/interfaces/l2tpv3.md b/docs/configuration/interfaces/l2tpv3.md
new file mode 100644
index 00000000..4a4acd91
--- /dev/null
+++ b/docs/configuration/interfaces/l2tpv3.md
@@ -0,0 +1,198 @@
+---
+lastproofread: '2023-01-20'
+---
+
+```{include} /_include/need_improvement.txt
+```
+
+(l2tpv3-interface)=
+
+# L2TPv3
+
+Layer 2 Tunnelling Protocol Version 3 is an IETF standard related to L2TP that
+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 is scaled to fit carrier requirements.
+
+L2TPv3 can be regarded as being to MPLS what IP is to ATM: a simplified version
+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}`3931`.
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-without-dhcp.txt
+   :var0: l2tpv3
+   :var1: l2tpeth0
+```
+
+### L2TPv3 options
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces l2tpv3 <interface> source-address <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. It may be specified as
+  an IPv4 address or an IPv6 address.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces l2tpv3 <interface> remote <address>
+
+  Set the IP address of the remote peer. It may be specified as
+  an IPv4 address or an IPv6 address.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```none
+# show interfaces l2tpv3
+l2tpv3 l2tpeth10 {
+    address 192.168.37.1/27
+    encapsulation ip
+    source-address 192.0.2.1
+    peer-session-id 100
+    peer-tunnel-id 200
+    remote 203.0.113.24
+    session-id 100
+    tunnel-id 200
+}
+```
+
+The inverse configuration has to be applied to the remote side.
+
+### Over UDP
+
+UDP mode works better with NAT:
+
+- Set source-address to your local IP (LAN).
+- Add a forwarding rule matching UDP port on your internet router.
+
+```none
+# show interfaces l2tpv3
+l2tpv3 l2tpeth10 {
+    address 192.168.37.1/27
+    destination-port 9001
+    encapsulation udp
+    source-address 192.0.2.1
+    peer-session-id 100
+    peer-tunnel-id 200
+    remote 203.0.113.24
+    session-id 100
+    source-port 9000
+    tunnel-id 200
+}
+```
+
+To create more than one tunnel, use distinct UDP ports.
+
+### Over IPSec, L2 VPN (bridge)
+
+This is the LAN extension use case. The eth0 port of the distant VPN peers
+will be directly connected like if there was a switch between them.
+
+IPSec:
+
+```none
+set vpn ipsec authentication psk <pre-shared-name> id '%any'
+set vpn ipsec authentication psk <pre-shared-name> secret <pre-shared-key>
+set vpn ipsec interface <VPN-interface>
+set vpn ipsec esp-group test-ESP-1 lifetime '3600'
+set vpn ipsec esp-group test-ESP-1 mode 'transport'
+set vpn ipsec esp-group test-ESP-1 pfs 'enable'
+set vpn ipsec esp-group test-ESP-1 proposal 1 encryption 'aes128'
+set vpn ipsec esp-group test-ESP-1 proposal 1 hash 'sha1'
+set vpn ipsec ike-group test-IKE-1 key-exchange 'ikev1'
+set vpn ipsec ike-group test-IKE-1 lifetime '3600'
+set vpn ipsec ike-group test-IKE-1 proposal 1 dh-group '5'
+set vpn ipsec ike-group test-IKE-1 proposal 1 encryption 'aes128'
+set vpn ipsec ike-group test-IKE-1 proposal 1 hash 'sha1'
+set vpn ipsec site-to-site peer <connection-name> authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer <connection-name> connection-type 'initiate'
+set vpn ipsec site-to-site peer <connection-name> ike-group 'test-IKE-1'
+set vpn ipsec site-to-site peer <connection-name> ikev2-reauth 'inherit'
+set vpn ipsec site-to-site peer <connection-name> local-address <local-ip>
+set vpn ipsec site-to-site peer <connection-name> tunnel 1 esp-group 'test-ESP-1'
+set vpn ipsec site-to-site peer <connection-name> tunnel 1 protocol 'l2tp'
+```
+
+Bridge:
+
+```none
+set interfaces bridge br0 description 'L2 VPN Bridge'
+# remote side in this example:
+# set interfaces bridge br0 address '172.16.30.18/30'
+set interfaces bridge br0 address '172.16.30.17/30'
+set interfaces bridge br0 member interface eth0
+set interfaces ethernet eth0 description 'L2 VPN Physical port'
+```
+
+L2TPv3:
+
+```none
+set interfaces bridge br0 member interface 'l2tpeth0'
+set interfaces l2tpv3 l2tpeth0 description 'L2 VPN Tunnel'
+set interfaces l2tpv3 l2tpeth0 destination-port '5000'
+set interfaces l2tpv3 l2tpeth0 encapsulation 'ip'
+set interfaces l2tpv3 l2tpeth0 source-address <local-ip>
+set interfaces l2tpv3 l2tpeth0 mtu '1500'
+set interfaces l2tpv3 l2tpeth0 peer-session-id '110'
+set interfaces l2tpv3 l2tpeth0 peer-tunnel-id '10'
+set interfaces l2tpv3 l2tpeth0 remote <peer-ip>
+set interfaces l2tpv3 l2tpeth0 session-id '110'
+set interfaces l2tpv3 l2tpeth0 source-port '5000'
+set interfaces l2tpv3 l2tpeth0 tunnel-id '10'
+```
diff --git a/docs/configuration/interfaces/loopback.md b/docs/configuration/interfaces/loopback.md
new file mode 100644
index 00000000..37da5399
--- /dev/null
+++ b/docs/configuration/interfaces/loopback.md
@@ -0,0 +1,80 @@
+---
+lastproofread: '2023-01-20'
+---
+
+(loopback-interface)=
+
+# Loopback
+
+The loopback networking interface is a virtual network device implemented
+entirely in software. All traffic sent to it "loops back" and just targets
+services on your local machine.
+
+:::{note}
+There can only be one loopback `lo` interface on the system. If
+you need multiple interfaces, please use the {ref}`dummy-interface`
+interface type.
+:::
+
+:::{hint}
+A loopback interface is always up, thus it could be used for
+management traffic or as source/destination for and {abbr}`IGP (Interior
+Gateway Protocol)` like {ref}`routing-bgp` so your internal BGP link is not
+dependent on physical link states and multiple routes can be chosen to the
+destination. A {ref}`dummy-interface` Interface should always be preferred
+over a {ref}`loopback-interface` interface.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-address.txt
+   :var0: loopback
+   :var1: lo
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+   :var0: loopback
+   :var1: lo
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces loopback
+
+   Show brief interface information.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces loopback
+     Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+     Interface        IP Address                        S/L  Description
+     ---------        ----------                        ---  -----------
+     lo               127.0.0.1/8                       u/u
+                      ::1/128
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces loopback lo
+
+   Show detailed information on the given loopback interface `lo`.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces loopback lo
+     lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
+         link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+         inet 127.0.0.1/8 scope host lo
+            valid_lft forever preferred_lft forever
+         inet6 ::1/128 scope host
+            valid_lft forever preferred_lft forever
+
+         RX:  bytes    packets     errors    dropped    overrun      mcast
+                300          6          0          0          0          0
+         TX:  bytes    packets     errors    dropped    carrier collisions
+                300          6          0          0          0          0
+```
diff --git a/docs/configuration/interfaces/macsec.md b/docs/configuration/interfaces/macsec.md
new file mode 100644
index 00000000..c3cd2595
--- /dev/null
+++ b/docs/configuration/interfaces/macsec.md
@@ -0,0 +1,305 @@
+---
+lastproofread: '2023-01-20'
+---
+
+(macsec-interface)=
+
+# MACsec
+
+MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in 2006.
+It defines a way to establish a protocol independent connection between two
+hosts with data confidentiality, authenticity and/or integrity, using
+GCM-AES-128. MACsec operates on the Ethernet layer and as such is a layer 2
+protocol, which means it's designed to secure traffic within a layer 2 network,
+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
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: macsec
+   :var1: macsec0
+```
+
+### MACsec options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security cipher <gcm-aes-128|gcm-aes-256>
+
+  Select cipher suite used for cryptographic operations. This setting is
+  mandatory.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security encrypt
+
+  MACsec only provides authentication by default, encryption is optional. This
+  command will enable encryption for all outgoing packets.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> source-interface <physical-source>
+
+  A physical interface is required to connect this MACsec instance to. Traffic
+  leaving this interface will now be authenticated/encrypted.
+```
+
+#### Static Keys
+
+Static {abbr}`SAK (Secure Authentication Key)` mode can be configured manually on each
+device wishing to use MACsec. Keys must be set statically on all devices for traffic
+to flow properly. Key rotation is dependent on the administrator updating all keys
+manually across connected devices. Static SAK mode can not be used with MKA.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security static key <key>
+
+  Set the device's transmit (TX) key. This key must be a hex string that is 16-bytes
+  (GCM-AES-128) or 32-bytes (GCM-AES-256).
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> mac <mac address>
+
+  Set the peer's MAC address
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> key <key>
+
+  Set the peer's key used to receive (RX) traffic
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> disable
+
+  Disable the peer configuration
+```
+
+#### Key Management
+
+{abbr}`MKA (MACsec Key Agreement protocol)` is used to synchronize keys between
+individual peers.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security mka cak <key>
+
+  IEEE 802.1X/MACsec pre-shared key mode. This allows configuring MACsec with
+  a pre-shared key using a {abbr}`CAK (MACsec connectivity association key)` and
+  {abbr}`CKN (MACsec connectivity association name)` pair.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security mka ckn <key>
+
+  {abbr}`CKN (MACsec connectivity association name)` key
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security mka priority <priority>
+
+  The peer with lower priority will become the key server and start
+  distributing SAKs.
+```
+
+#### Replay protection
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security replay-window <window>
+
+  IEEE 802.1X/MACsec replay protection window. This determines a window in which
+  replay is tolerated, to allow receipt of frames that have been misordered by
+  the network.
+
+  - ``0``: No replay window, strict check
+  - ``1-4294967295``: Number of packets that could be misordered
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: run generate macsec mka cak <gcm-aes-128|gcm-aes-256>
+
+  Generate {abbr}`MKA (MACsec Key Agreement protocol)` CAK key 128 or 256 bits.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ generate macsec mka cak gcm-aes-128
+    20693b6e08bfa482703a563898c9e3ad
+```
+
+```{eval-rst}
+.. opcmd:: run generate macsec mka ckn
+
+  Generate {abbr}`MKA (MACsec Key Agreement protocol)` CAK key.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ generate macsec mka ckn
+    88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces macsec
+
+  List all MACsec interfaces.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces macsec
+    17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off
+        cipher suite: GCM-AES-128, using ICV length 16
+        TXSC: 005056bfefaa0001 on SA 0
+    20: macsec0: protect on validate strict sc off sa off encrypt off send_sci on end_station off scb off replay off
+        cipher suite: GCM-AES-128, using ICV length 16
+        TXSC: 005056bfefaa0001 on SA 0
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces macsec <interface>
+
+  Show specific MACsec interface information
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces macsec macsec1
+    17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off
+        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
+- R2 has 192.0.2.2/24 & 2001:db8::2/64
+
+**R1**
+
+```none
+set interfaces macsec macsec1 address '192.0.2.1/24'
+set interfaces macsec macsec1 address '2001:db8::1/64'
+set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+set interfaces macsec macsec1 security encrypt
+set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4'
+set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836'
+set interfaces macsec macsec1 source-interface 'eth1'
+```
+
+**R2**
+
+```none
+set interfaces macsec macsec1 address '192.0.2.2/24'
+set interfaces macsec macsec1 address '2001:db8::2/64'
+set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+set interfaces macsec macsec1 security encrypt
+set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4'
+set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836'
+set interfaces macsec macsec1 source-interface 'eth1'
+```
+
+Pinging (IPv6) the other host and intercepting the traffic in `eth1` will
+show you the content is encrypted.
+
+```none
+17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150:
+        0x0000:  2c00 0000 000a 0050 56bf efaa 0001 d9fb  ,......PV.......
+        0x0010:  920a 8b8d 68ed 9609 29dd e767 25a4 4466  ....h...)..g%.Df
+        0x0020:  5293 487b 9990 8517 3b15 22c7 ea5c ac83  R.H{....;."..\..
+        0x0030:  4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09  Ln...C..,NiN....
+        0x0040:  0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb  .w]S.u..T..Z.f..
+        0x0050:  c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b  ..n#..m.2..X...;
+        0x0060:  4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669  M..X...../..1..i
+        0x0070:  e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e  .:.8.b..(Wj.....
+        0x0080:  6b30 92a5 7ccc 720b                      k0..|.r.
+```
+
+Disabling the encryption on the link by removing `security encrypt` will show
+the unencrypted but authenticated content.
+
+```none
+17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150:
+        0x0000:  2000 0000 0009 0050 56bf efaa 0001 86dd  .......PV.......
+        0x0010:  6009 86f3 0040 3a40 2001 0db8 0000 0000  `....@:@........
+        0x0020:  0000 0000 0000 0001 2001 0db8 0000 0000  ................
+        0x0030:  0000 0000 0000 0002 8100 d977 0f30 0003  ...........w.0..
+        0x0040:  1ca0 c65e 0000 0000 8d93 0b00 0000 0000  ...^............
+        0x0050:  1011 1213 1415 1617 1819 1a1b 1c1d 1e1f  ................
+        0x0060:  2021 2223 2425 2627 2829 2a2b 2c2d 2e2f  .!"#$%&'()*+,-./
+        0x0070:  3031 3233 3435 3637 87d5 eed3 3a39 d52b  01234567....:9.+
+        0x0080:  a282 c842 5254 ef28                      ...BRT.(
+```
+
+**R1 Static Key**
+
+```none
+set interfaces macsec macsec1 address '192.0.2.1/24'
+set interfaces macsec macsec1 address '2001:db8::1/64'
+set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+set interfaces macsec macsec1 security encrypt
+set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
+set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02
+set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
+set interfaces macsec macsec1 source-interface 'eth1'
+```
+
+**R2 Static Key**
+
+```none
+set interfaces macsec macsec1 address '192.0.2.2/24'
+set interfaces macsec macsec1 address '2001:db8::2/64'
+set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+set interfaces macsec macsec1 security encrypt
+set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
+set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:01
+set interfaces macsec macsec1 security static peer R2 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
+set interfaces macsec macsec1 source-interface 'eth1'
+```
+
+## MACsec over wan
+
+MACsec is an interesting alternative to existing tunneling solutions that
+protects layer 2 by performing integrity, origin authentication, and optionally
+encryption. The typical use case is to use MACsec between hosts and access
+switches, between two hosts, or between two switches. in this example below,
+we use VXLAN and MACsec to secure the tunnel.
+
+**R1 MACsec01**
+
+```none
+set interfaces macsec macsec1 address '192.0.2.1/24'
+set interfaces macsec macsec1 address '2001:db8::1/64'
+set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+set interfaces macsec macsec1 security encrypt
+set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
+set interfaces macsec macsec1 security static peer SEC02 key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
+set interfaces macsec macsec1 security static peer SEC02 mac '00:11:22:33:44:02'
+set interfaces macsec macsec1 source-interface 'vxlan1'
+set interfaces vxlan vxlan1 mac '00:11:22:33:44:01'
+set interfaces vxlan vxlan1 remote '10.1.3.3'
+set interfaces vxlan vxlan1 source-address '172.16.100.1'
+set interfaces vxlan vxlan1 vni '10'
+set protocols static route 10.1.3.3/32 next-hop 172.16.100.2
+```
+
+**R2 MACsec02**
+
+```none
+set interfaces macsec macsec1 address '192.0.2.2/24'
+set interfaces macsec macsec1 address '2001:db8::2/64'
+set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+set interfaces macsec macsec1 security encrypt
+set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
+set interfaces macsec macsec1 security static peer SEC01 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
+set interfaces macsec macsec1 security static peer SEC01 mac '00:11:22:33:44:01'
+set interfaces macsec macsec1 source-interface 'vxlan1'
+set interfaces vxlan vxlan1 mac '00:11:22:33:44:02'
+set interfaces vxlan vxlan1 remote '10.1.2.2'
+set interfaces vxlan vxlan1 source-address '172.16.100.2'
+set interfaces vxlan vxlan1 vni '10'
+set protocols static route 10.1.2.2/32 next-hop 172.16.100.1
+```
diff --git a/docs/configuration/interfaces/openvpn.md b/docs/configuration/interfaces/openvpn.md
new file mode 100644
index 00000000..926cb42c
--- /dev/null
+++ b/docs/configuration/interfaces/openvpn.md
@@ -0,0 +1,867 @@
+---
+lastproofread: '2021-07-05'
+---
+
+(openvpn)=
+
+# OpenVPN
+
+Traditionally hardware routers implement IPsec exclusively due to relative
+ease of implementing it in hardware and insufficient CPU power for doing
+encryption in software. Since VyOS is a software router, this is less of a
+concern. OpenVPN has been widely used on UNIX platform for a long time and is
+a popular option for remote access VPN, though it's also capable of
+site-to-site connections.
+
+Advantages of OpenVPN are:
+
+- It uses a single TCP or UDP connection and does not rely on packet source
+  addresses, so it will work even through a double NAT: perfect for public
+  hotspots and such
+- It's easy to setup and offers very flexible split tunneling
+- There's a variety of client GUI frontends for any platform
+
+Disadvantages are:
+
+- It's slower than IPsec due to higher protocol overhead and the fact it runs
+  in user mode while IPsec, on Linux, is in kernel mode
+- None of the operating systems have client software installed by default
+
+In the VyOS CLI, a key point often overlooked is that rather than being
+configured using the `set vpn` stanza, OpenVPN is configured as a network
+interface using `set interfaces openvpn`.
+
+## Site-to-Site
+
+:::{figure} /_static/images/openvpn_site2site_diagram.jpg
+:::
+
+OpenVPN is popular for client-server setups, but its site-to-site mode
+remains a relatively obscure feature, and many router appliances
+still don't support it. However, it's very useful for quickly setting up
+tunnels between routers.
+
+As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates.
+
+The pre-shared key mode is deprecated and will be removed from future OpenVPN versions,
+so VyOS will have to remove support for that option as well. The reason is that using pre-shared keys
+is significantly less secure than using TLS.
+
+We'll configure OpenVPN using self-signed certificates, and then discuss the legacy
+pre-shared key mode.
+
+In both cases, we will use the following settings:
+
+- The public IP address of the local side of the VPN will be 198.51.100.10.
+- The public IP address of the remote side of the VPN will be 203.0.113.11.
+- The tunnel will use 10.255.1.1 for the local IP and 10.255.1.2 for the remote.
+- The local site will have a subnet of 10.0.0.0/16.
+- The remote site will have a subnet of 10.1.0.0/16.
+- The official port for OpenVPN is 1194, which we reserve for client VPN; we
+  will use 1195 for site-to-site VPN.
+- The `persistent-tunnel` directive will allow us to configure tunnel-related
+  attributes, such as firewall policy as we would on any normal network
+  interface.
+- If known, the IP of the remote router can be configured using the
+  `remote-host` directive; if unknown, it can be omitted. We will assume a
+  dynamic IP for our remote router.
+
+### Setting up certificates
+
+Setting up a full-blown PKI with a CA certificate would arguably defeat the purpose
+of site-to-site OpenVPN, since its main goal is supposed to be configuration simplicity,
+compared to server setups that need to support multiple clients.
+
+However, since VyOS 1.4, it is possible to verify self-signed certificates using
+certificate fingerprints.
+
+On both sides, you need to generate a self-signed certificate, preferrably using the "ec" (elliptic curve) type.
+You can generate them by executing command `run generate pki certificate self-signed install <name>` in the configuration mode.
+Once the command is complete, it will add the certificate to the configuration session, to the `pki` subtree.
+You can then review the proposed changes and commit them.
+
+```none
+vyos@vyos# run generate pki certificate self-signed install openvpn-local
+Enter private key type: [rsa, dsa, ec] (Default: rsa) ec
+Enter private key bits: (Default: 256)
+Enter country code: (Default: GB)
+Enter state: (Default: Some-State)
+Enter locality: (Default: Some-City)
+Enter organization name: (Default: VyOS)
+Enter common name: (Default: vyos.io)
+Do you want to configure Subject Alternative Names? [y/N]
+Enter how many days certificate will be valid: (Default: 365)
+Enter certificate type: (client, server) (Default: server)
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N]
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+[edit]
+
+vyos@vyos# compare
+[pki]
++ certificate openvpn-local {
++     certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/    uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg=="
++     private {
++         key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW"
++     }
++ }
+
+[edit]
+
+vyos@vyos# commit
+```
+
+You do **not** need to copy the certificate to the other router. Instead, you need to retrieve its SHA-256 fingerprint.
+OpenVPN only supports SHA-256 fingerprints at the moment, so you need to use the following command:
+
+```none
+vyos@vyos# run show pki certificate openvpn-local fingerprint sha256
+5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79
+```
+
+Note: certificate names don't matter, we use 'openvpn-local' and 'openvpn-remote' but they can be arbitrary.
+
+Repeat the procedure on the other router.
+
+### Setting up OpenVPN
+
+Local Configuration:
+
+```none
+Configure the tunnel:
+
+set interfaces openvpn vtun1 mode site-to-site
+set interfaces openvpn vtun1 protocol udp
+set interfaces openvpn vtun1 persistent-tunnel
+set interfaces openvpn vtun1 remote-host '203.0.113.11'                         # Public IP of the other side
+set interfaces openvpn vtun1 local-port '1195'
+set interfaces openvpn vtun1 remote-port '1195'
+set interfaces openvpn vtun1 local-address '10.255.1.1'                         # Local IP of vtun interface
+set interfaces openvpn vtun1 remote-address '10.255.1.2'                        # Remote IP of vtun interface
+set interfaces openvpn vtun1 tls certificate 'openvpn-local'                    # The self-signed certificate
+set interfaces openvpn vtun1 tls peer-fingerprint <remote cert fingerprint>     # The output of 'run show pki certificate <name> fingerprint sha256
+                                                                                  on the remote rout
+```
+
+Remote Configuration:
+
+```none
+set interfaces openvpn vtun1 mode site-to-site
+set interfaces openvpn vtun1 protocol udp
+set interfaces openvpn vtun1 persistent-tunnel
+set interfaces openvpn vtun1 remote-host '198.51.100.10'                         # Pub IP of other site
+set interfaces openvpn vtun1 local-port '1195'
+set interfaces openvpn vtun1 remote-port '1195'
+set interfaces openvpn vtun1 local-address '10.255.1.2'                          # Local IP of vtun interface
+set interfaces openvpn vtun1 remote-address '10.255.1.1'                         # Remote IP of vtun interface
+set interfaces openvpn vtun1 tls certificate 'openvpn-remote'                    # The self-signed certificate
+set interfaces openvpn vtun1 tls peer-fingerprint <local cert fingerprint>       # The output of 'run show pki certificate <name> fingerprint sha256
+                                                                                  on the local router
+```
+
+### Pre-shared keys
+
+Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI was to use pre-shared keys.
+That option is still available but it is deprecated and will be removed in the future.
+However, if you need to set up a tunnel to an older VyOS version or a system with older OpenVPN,
+you need to still need to know how to use it.
+
+First, you need to generate a key by running `run generate pki openvpn shared-secret install <name>` from configuration mode.
+You can use any name, we will use `s2s`.
+
+```none
+vyos@local# run generate pki openvpn shared-secret install s2s
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+[edit]
+vyos@local# compare
+[pki openvpn shared-secret]
++ s2s {
++     key   "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3"
++     version "1"
++ }
+
+[edit]
+
+vyos@local# commit
+[edit]
+```
+
+Then you need to install the key on the remote router:
+
+```none
+vyos@remote# set pki openvpn shared-secret s2s key <generated key string>
+```
+
+Then you need to set the key in your OpenVPN interface settings:
+
+```none
+set interfaces openvpn vtun1 shared-secret-key s2s
+```
+
+### Firewall Exceptions
+
+For the OpenVPN traffic to pass through the WAN interface, you must create a
+firewall exception.
+
+```none
+set firewall name OUTSIDE_LOCAL rule 10 action accept
+set firewall name OUTSIDE_LOCAL rule 10 description 'Allow established/related'
+set firewall name OUTSIDE_LOCAL rule 10 state established enable
+set firewall name OUTSIDE_LOCAL rule 10 state related enable
+set firewall name OUTSIDE_LOCAL rule 20 action accept
+set firewall name OUTSIDE_LOCAL rule 20 description OpenVPN_IN
+set firewall name OUTSIDE_LOCAL rule 20 destination port 1195
+set firewall name OUTSIDE_LOCAL rule 20 log enable
+set firewall name OUTSIDE_LOCAL rule 20 protocol udp
+set firewall name OUTSIDE_LOCAL rule 20 source
+```
+
+You should also ensure that the OUTISDE_LOCAL firewall group is applied to the
+WAN interface and a direction (local).
+
+```none
+set firewall interface eth0 local name 'OUTSIDE-LOCAL'
+```
+
+Static Routing:
+
+Static routes can be configured referencing the tunnel interface; for example,
+the local router will use a network of 10.0.0.0/16, while the remote has a
+network of 10.1.0.0/16:
+
+Local Configuration:
+
+```none
+set protocols static route 10.1.0.0/16 interface vtun1
+```
+
+Remote Configuration:
+
+```none
+set protocols static route 10.0.0.0/16 interface vtun1
+```
+
+The configurations above will default to using 256-bit AES in GCM mode
+for encryption (if both sides support NCP) and SHA-1 for HMAC authentication.
+SHA-1 is considered weak, but other hashing algorithms are available, as are
+encryption algorithms:
+
+For Encryption:
+
+This sets the cipher when NCP (Negotiable Crypto Parameters) is disabled or
+OpenVPN version < 2.4.0.
+
+```none
+vyos@vyos# set interfaces openvpn vtun1 encryption cipher
+Possible completions:
+  des          DES algorithm
+  3des         DES algorithm with triple encryption
+  bf128        Blowfish algorithm with 128-bit key
+  bf256        Blowfish algorithm with 256-bit key
+  aes128       AES algorithm with 128-bit key CBC
+  aes128gcm    AES algorithm with 128-bit key GCM
+  aes192       AES algorithm with 192-bit key CBC
+  aes192gcm    AES algorithm with 192-bit key GCM
+  aes256       AES algorithm with 256-bit key CBC
+  aes256gcm    AES algorithm with 256-bit key GCM
+```
+
+This sets the accepted ciphers to use when version => 2.4.0 and NCP is
+enabled (which is the default). Default NCP cipher for versions >= 2.4.0 is
+aes256gcm. The first cipher in this list is what server pushes to clients.
+
+```none
+vyos@vyos# set int open vtun0 encryption ncp-ciphers
+Possible completions:
+  des          DES algorithm
+  3des         DES algorithm with triple encryption
+  aes128       AES algorithm with 128-bit key CBC
+  aes128gcm    AES algorithm with 128-bit key GCM
+  aes192       AES algorithm with 192-bit key CBC
+  aes192gcm    AES algorithm with 192-bit key GCM
+  aes256       AES algorithm with 256-bit key CBC
+  aes256gcm    AES algorithm with 256-bit key GCM
+```
+
+For Hashing:
+
+```none
+vyos@vyos# set interfaces openvpn vtun1 hash
+Possible completions:
+  md5          MD5 algorithm
+  sha1         SHA-1 algorithm
+  sha256       SHA-256 algorithm
+  sha512       SHA-512 algorithm
+```
+
+If you change the default encryption and hashing algorithms, be sure that the
+local and remote ends have matching configurations, otherwise the tunnel will
+not come up.
+
+Firewall policy can also be applied to the tunnel interface for `local`, `in`,
+and `out` directions and functions identically to ethernet interfaces.
+
+If making use of multiple tunnels, OpenVPN must have a way to distinguish
+between different tunnels aside from the pre-shared-key. This is either by
+referencing IP address or port number. One option is to dedicate a public IP
+to each tunnel. Another option is to dedicate a port number to each tunnel
+(e.g. 1195,1196,1197...).
+
+OpenVPN status can be verified using the `show openvpn` operational commands.
+See the built-in help for a complete list of options.
+
+## Server
+
+Multi-client server is the most popular OpenVPN mode on routers. It always uses
+x.509 authentication and therefore requires a PKI setup. Refer this topic
+{ref}`configuration/pki/index:pki` to generate a CA certificate,
+a server certificate and key, a certificate revocation list, a Diffie-Hellman
+key exchange parameters file. You do not need client certificates and keys for
+the server setup.
+
+In this example we will use the most complicated case: a setup where each
+client is a router that has its own subnet (think HQ and branch offices), since
+simpler setups are subsets of it.
+
+Suppose you want to use 10.23.1.0/24 network for client tunnel endpoints and
+all client subnets belong to 10.23.0.0/20. All clients need access to the
+192.168.0.0/16 network.
+
+First we need to specify the basic settings. 1194/UDP is the default. The
+`persistent-tunnel` option is recommended, it prevents the TUN/TAP device from
+closing on connection resets or daemon reloads.
+
+:::{note}
+Using **openvpn-option -reneg-sec** can be tricky. This option is
+used to renegotiate data channel after n seconds. When used at both server
+and client, the lower value will trigger the renegotiation. If you set it to
+0 on one side of the connection (to disable it), the chosen value on the
+other side will determine when the renegotiation will occur.
+:::
+
+```none
+set interfaces openvpn vtun10 mode server
+set interfaces openvpn vtun10 local-port 1194
+set interfaces openvpn vtun10 persistent-tunnel
+set interfaces openvpn vtun10 protocol udp
+```
+
+Then we need to generate, add and specify the names of the cryptographic materials.
+Each of the install command should be applied to the configuration and commited
+before using under the openvpn interface configuration.
+
+```none
+run generate pki ca install ca-1                                # Follow the instructions to generate CA cert.
+Configure mode commands to install:
+set pki ca ca-1 certificate 'generated_cert_string'
+set pki ca ca-1 private key 'generated_private_key'
+
+run generate pki certificate sign ca-1 install srv-1            # Follow the instructions to generate server cert.
+Configure mode commands to install:
+set pki certificate srv-1 certificate 'generated_server_cert'
+set pki certificate srv-1 private key 'generated_private_key'
+
+run generate pki dh install dh-1                                # Follow the instructions to generate set of
+                                                                  Diffie-Hellman parameters.
+Generating parameters...
+Configure mode commands to install DH parameters:
+set pki dh dh-1 parameters 'generated_dh_params_set'
+
+set interfaces openvpn vtun10 tls ca-certificate ca-1
+set interfaces openvpn vtun10 tls certificate srv-1
+set interfaces openvpn vtun10 tls dh-params dh-1
+```
+
+Now we need to specify the server network settings. In all cases we need to
+specify the subnet for client tunnel endpoints. Since we want clients to access
+a specific network behind our router, we will use a push-route option for
+installing that route on clients.
+
+```none
+set interfaces openvpn vtun10 server push-route 192.168.0.0/16
+set interfaces openvpn vtun10 server subnet 10.23.1.0/24
+```
+
+Since it's a HQ and branch offices setup, we will want all clients to have
+fixed addresses and we will route traffic to specific subnets through them. We
+need configuration for each client to achieve this.
+
+:::{note}
+Clients are identified by the CN field of their x.509 certificates,
+in this example the CN is `client0`:
+:::
+
+```none
+set interfaces openvpn vtun10 server client client0 ip 10.23.1.10
+set interfaces openvpn vtun10 server client client0 subnet 10.23.2.0/25
+```
+
+OpenVPN **will not** automatically create routes in the kernel for client
+subnets when they connect and will only use client-subnet association
+internally, so we need to create a route to the 10.23.0.0/20 network ourselves:
+
+```none
+set protocols static route 10.23.0.0/20 interface vtun10
+```
+
+Additionally, each client needs a copy of ca cert and its own client key and
+cert files. The files are plaintext so they may be copied either manually from the CLI.
+Client key and cert files should be signed with the proper ca cert and generated on the
+server side.
+
+HQ's router requires the following steps to generate crypto materials for the Branch 1:
+
+```none
+run generate pki certificate sign ca-1 install branch-1            # Follow the instructions to generate client
+                                                                     cert for Branch 1
+Configure mode commands to install:
+```
+
+Branch 1's router might have the following lines:
+
+```none
+set pki ca ca-1 certificate 'generated_cert_string'                # CA cert generated on HQ router
+set pki certificate branch-1 certificate 'generated_branch_cert'   # Client cert generated and signed on HQ router
+set pki certificate branch-1 private key 'generated_private_key'   # Client cert key generated on HQ router
+
+set interfaces openvpn vtun10 tls ca-cert ca-1
+set interfaces openvpn vtun10 tls certificate branch-1
+```
+
+### Client Authentication
+
+#### LDAP
+
+Enterprise installations usually ship a kind of directory service which is used
+to have a single password store for all employees. VyOS and OpenVPN support
+using LDAP/AD as single user backend.
+
+Authentication is done by using the `openvpn-auth-ldap.so` plugin which is
+shipped with every VyOS installation. A dedicated configuration file is
+required. It is best practise to store it in `/config` to survive image
+updates
+
+```none
+set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config"
+```
+
+The required config file may look like this:
+
+```none
+<LDAP>
+# LDAP server URL
+URL             ldap://ldap.example.com
+# Bind DN (If your LDAP server doesn't support anonymous binds)
+BindDN          cn=LDAPUser,dc=example,dc=com
+# Bind Password password
+Password        S3cr3t
+# Network timeout (in seconds)
+Timeout         15
+</LDAP>
+
+<Authorization>
+# Base DN
+BaseDN          "ou=people,dc=example,dc=com"
+# User Search Filter
+SearchFilter    "(&(uid=%u)(objectClass=shadowAccount))"
+# Require Group Membership - allow all users
+RequireGroup    false
+</Authorization>
+```
+
+##### Active Directory
+
+Despite the fact that AD is a superset of LDAP
+
+```none
+<LDAP>
+  # LDAP server URL
+  URL ldap://dc01.example.com
+  # Bind DN (If your LDAP server doesn’t support anonymous binds)
+  BindDN CN=LDAPUser,DC=example,DC=com
+  # Bind Password
+  Password mysecretpassword
+  # Network timeout (in seconds)
+  Timeout  15
+  # Enable Start TLS
+  TLSEnable no
+  # Follow LDAP Referrals (anonymously)
+  FollowReferrals no
+</LDAP>
+
+<Authorization>
+  # Base DN
+  BaseDN        "DC=example,DC=com"
+  # User Search Filter, user must be a member of the VPN AD group
+  SearchFilter  "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))"
+  # Require Group Membership
+  RequireGroup    false # already handled by SearchFilter
+  <Group>
+    BaseDN        "OU=Groups,DC=example,DC=com"
+    SearchFilter  "(|(cn=VPN))"
+    MemberAttribute  memberOf
+  </Group>
+</Authorization>
+```
+
+If you only want to check if the user account is enabled and can authenticate
+(against the primary group) the following snipped is sufficient:
+
+```none
+<LDAP>
+  URL ldap://dc01.example.com
+  BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com
+  Password ThisIsTopSecret
+  Timeout  15
+  TLSEnable no
+  FollowReferrals no
+</LDAP>
+
+<Authorization>
+  BaseDN          "DC=example,DC=com"
+  SearchFilter    "sAMAccountName=%u"
+  RequireGroup    false
+</Authorization>
+```
+
+A complete LDAP auth OpenVPN configuration could look like the following
+example:
+
+```none
+vyos@vyos# show interfaces openvpn
+ openvpn vtun0 {
+     mode server
+     openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix"
+     openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config"
+     openvpn-option "--push redirect-gateway"
+     openvpn-option --duplicate-cn
+     openvpn-option "--verify-client-cert none"
+     openvpn-option --comp-lzo
+     openvpn-option --persist-key
+     openvpn-option --persist-tun
+     server {
+         domain-name example.com
+         max-connections 5
+         name-server 203.0.113.0.10
+         name-server 198.51.100.3
+         subnet 172.18.100.128/29
+     }
+     tls {
+         ca-certificate ca.crt
+         certificate server.crt
+         dh-params dh1024.pem
+     }
+ }
+```
+
+## Client
+
+VyOS can not only act as an OpenVPN site-to-site or server for multiple clients.
+You can indeed also configure any VyOS OpenVPN interface as an OpenVPN client
+connecting to a VyOS OpenVPN server or any other OpenVPN server.
+
+Given the following example we have one VyOS router acting as OpenVPN server
+and another VyOS router acting as OpenVPN client. The server also pushes a
+static client IP address to the OpenVPN client. Remember, clients are identified
+using their CN attribute in the SSL certificate.
+
+(openvpn-client-server)=
+
+### Configuration
+
+#### Server Side
+
+```none
+set interfaces openvpn vtun10 encryption cipher 'aes256'
+set interfaces openvpn vtun10 hash 'sha512'
+set interfaces openvpn vtun10 local-host '172.18.201.10'
+set interfaces openvpn vtun10 local-port '1194'
+set interfaces openvpn vtun10 mode 'server'
+set interfaces openvpn vtun10 persistent-tunnel
+set interfaces openvpn vtun10 protocol 'udp'
+set interfaces openvpn vtun10 server client client1 ip '10.10.0.10'
+set interfaces openvpn vtun10 server domain-name 'vyos.net'
+set interfaces openvpn vtun10 server max-connections '250'
+set interfaces openvpn vtun10 server name-server '172.16.254.30'
+set interfaces openvpn vtun10 server subnet '10.10.0.0/24'
+set interfaces openvpn vtun10 server topology 'subnet'
+set interfaces openvpn vtun10 tls ca-cert ca-1
+set interfaces openvpn vtun10 tls certificate srv-1
+set interfaces openvpn vtun10 tls crypt-key srv-1
+set interfaces openvpn vtun10 tls dh-params dh-1
+set interfaces openvpn vtun10 use-lzo-compression
+```
+
+(openvpn-client-client)=
+
+#### Client Side
+
+```none
+set interfaces openvpn vtun10 encryption cipher 'aes256'
+set interfaces openvpn vtun10 hash 'sha512'
+set interfaces openvpn vtun10 mode 'client'
+set interfaces openvpn vtun10 persistent-tunnel
+set interfaces openvpn vtun10 protocol 'udp'
+set interfaces openvpn vtun10 remote-host '172.18.201.10'
+set interfaces openvpn vtun10 remote-port '1194'
+set interfaces openvpn vtun10 tls ca-cert ca-1
+set interfaces openvpn vtun10 tls certificate client-1
+set interfaces openvpn vtun10 tls crypt-key client-1
+set interfaces openvpn vtun10 use-lzo-compression
+```
+
+### Options
+
+We do not have CLI nodes for every single OpenVPN option. If an option is
+missing, a feature request should be opened at [Phabricator] so all users can
+benefit from it (see {ref}`issues_features`).
+
+If you are a hacker or want to try on your own we support passing raw OpenVPN
+options to OpenVPN.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option 'persistent-key'
+```
+
+Will add `persistent-key` at the end of the generated OpenVPN configuration.
+Please use this only as last resort - things might break and OpenVPN won't start
+if you pass invalid options/syntax.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option
+   'push &quot;keepalive 1 10&quot;'
+```
+
+Will add `push "keepalive 1 10"` to the generated OpenVPN config file.
+
+:::{note}
+Sometimes option lines in the generated OpenVPN configuration require
+quotes. This is done through a hack on our config generator. You can pass
+quotes using the `&quot;` statement.
+:::
+
+### Server bridge
+
+In Ethernet bridging configurations, OpenVPN's server mode can be set as a
+'bridge' where the VPN tunnel encapsulates entire Ethernet frames
+(up to 1514 bytes) instead of just IP packets (up to 1500 bytes). This setup
+allows clients to transmit Layer 2 frames through the OpenVPN tunnel. Below,
+we outline a basic configuration to achieve this:
+
+Server Side:
+
+```none
+set interfaces bridge br10 member interface eth1.10
+set interfaces bridge br10 member interface vtun10
+set interfaces openvpn vtun10 device-type 'tap'
+set interfaces openvpn vtun10 encryption data-ciphers 'aes192'
+set interfaces openvpn vtun10 hash 'sha256''
+set interfaces openvpn vtun10 local-host '172.18.201.10'
+set interfaces openvpn vtun10 local-port '1194'
+set interfaces openvpn vtun10 mode 'server'
+set interfaces openvpn vtun10 server bridge gateway '10.10.0.1'
+set interfaces openvpn vtun10 server bridge start '10.10.0.100'
+set interfaces openvpn vtun10 server bridge stop '10.10.0.200'
+set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0'
+set interfaces openvpn vtun10 server topology 'subnet'
+set interfaces openvpn vtun10 tls ca-certificate 'ca-1'
+set interfaces openvpn vtun10 tls certificate 'srv-1'
+set interfaces openvpn vtun10 tls dh-params 'srv-1'
+```
+
+Client Side :
+
+```none
+set interfaces openvpn vtun10 device-type 'tap'
+set interfaces openvpn vtun10 encryption data-ciphers 'aes192'
+set interfaces openvpn vtun10 hash 'sha256''
+set interfaces openvpn vtun10 mode 'client'
+set interfaces openvpn vtun10 protocol 'udp'
+set interfaces openvpn vtun10 remote-host '172.18.201.10'
+set interfaces openvpn vtun10 remote-port '1194'
+set interfaces openvpn vtun10 tls ca-certificate 'ca-1'
+set interfaces openvpn vtun10 tls certificate 'client-1'
+```
+
+## Multi-factor Authentication
+
+VyOS supports multi-factor authentication (MFA) or two-factor authentication
+using Time-based One-Time Password (TOTP). Compatible with Google Authenticator
+software token, other software tokens.
+
+### MFA TOTP options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp challenge <enable | disable>
+
+  If set to enable, openvpn-otp will expect password as result of challenge/
+  response protocol.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp digits <1-65535>
+
+  Configure number of digits to use for totp hash (default: 6)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp drift <1-65535>
+
+  Configure time drift in seconds (default: 0)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp slop <1-65535>
+
+  Configure maximum allowed clock slop in seconds (default: 180)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp step <1-65535>
+
+  Configure step value for totp in seconds (default: 30)
+```
+
+### Example
+
+```none
+set interfaces openvpn vtun20 encryption cipher 'aes256'
+set interfaces openvpn vtun20 hash 'sha512'
+set interfaces openvpn vtun20 mode 'server'
+set interfaces openvpn vtun20 persistent-tunnel
+set interfaces openvpn vtun20 server client user1
+set interfaces openvpn vtun20 server mfa totp challenge 'disable'
+set interfaces openvpn vtun20 server subnet '10.10.2.0/24'
+set interfaces openvpn vtun20 server topology 'subnet'
+set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20'
+set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20'
+set interfaces openvpn vtun20 tls dh-params 'dh-pem'
+```
+
+For every client in the openvpn server configuration a totp secret is created.
+To display the authentication information, use the command:
+
+```{eval-rst}
+.. cfgcmd:: show interfaces openvpn <interface> user <username> mfa <qrcode|secret|uri>
+```
+
+An example:
+
+```none
+vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode
+█████████████████████████████████████
+█████████████████████████████████████
+████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████
+████ █   █ █▀▀▄ █▀▀▀█▀██ █ █   █ ████
+████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████
+████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████
+████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████
+████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████
+████ ▄█▀▀▄▄  ▄█▀  ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████
+████▄█ ▀▄▄▄▀  ▀ ▄█ ▄ █▄█▀ █▀  █▀█████
+████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀  ▀ ▀ ▄█▀████
+████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█  █▀██▀████
+████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████
+████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀  █▄█ ██▀█████
+████ █   █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄   ████
+████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████
+████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████
+█████████████████████████████████████
+█████████████████████████████████████
+```
+
+Use the QR code to add the user account in Google authenticator application and
+on client side, use the OTP number as password.
+
+## OpenVPN Data Channel Offload (DCO)
+
+OpenVPN Data Channel Offload (DCO) enables significant performance enhancement
+in encrypted OpenVPN data processing. By minimizing context switching for each
+packet, DCO effectively reduces overhead. This optimization is achieved by
+keeping most data handling tasks within the kernel, avoiding frequent switches
+between kernel and user space for encryption and packet handling.
+
+As a result, the processing of each packet becomes more efficient, potentially
+leveraging hardware encryption offloading support available in the kernel.
+
+:::{note}
+OpenVPN DCO is not full OpenVPN features supported , is currently
+considered experimental. Furthermore, there are certain OpenVPN features and
+use cases that remain incompatible with DCO. To get a comprehensive
+understanding of the limitations associated with DCO, refer to the list of
+known limitations in the documentation.
+
+<https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features>
+:::
+
+### Enabling OpenVPN DCO
+
+DCO support is a per-tunnel option and it is not automatically enabled by
+default for new or upgraded tunnels. Existing tunnels will continue to function
+as they have in the past.
+
+DCO can be enabled for both new and existing tunnels,VyOS adds an option in each
+tunnel configuration where we can enable this function .The current best
+practice is to create a new tunnel with DCO to minimize the chance of problems
+with existing clients.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn <name> offload dco
+
+  Enable OpenVPN Data Channel Offload feature by loading the appropriate kernel
+  module.
+
+  Disabled by default - no kernel module loaded.
+
+  .. note:: Enable this feature causes an interface reset.
+
+```
+
+### Troubleshooting
+
+VyOS provides some operational commands on OpenVPN.
+
+#### Check status
+
+The following commands let you check tunnel status.
+
+```{eval-rst}
+.. opcmd:: show openvpn client
+
+   Use this command to check the tunnel status for OpenVPN client interfaces.
+```
+
+```{eval-rst}
+.. opcmd:: show openvpn server
+
+   Use this command to check the tunnel status for OpenVPN server interfaces.
+```
+
+```{eval-rst}
+.. opcmd:: show openvpn site-to-site
+
+   Use this command to check the tunnel status for OpenVPN site-to-site
+   interfaces.
+
+```
+
+#### Reset OpenVPN
+
+The following commands let you reset OpenVPN.
+
+```{eval-rst}
+.. opcmd:: reset openvpn client <text>
+
+   Use this command to reset the specified OpenVPN client.
+```
+
+```{eval-rst}
+.. opcmd:: reset openvpn interface <interface>
+
+   Use this command to reset the OpenVPN process on a specific interface.
+
+
+```
+
+```{include} /_include/common-references.txt
+```
diff --git a/docs/configuration/interfaces/pppoe.md b/docs/configuration/interfaces/pppoe.md
new file mode 100644
index 00000000..25e017f4
--- /dev/null
+++ b/docs/configuration/interfaces/pppoe.md
@@ -0,0 +1,443 @@
+---
+lastproofread: '2022-07-27'
+---
+
+(pppoe-interface)=
+
+# PPPoE
+
+{abbr}`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol
+for encapsulating PPP frames inside Ethernet frames. It appeared in 1999,
+in the context of the boom of DSL as the solution for tunneling packets
+over the DSL connection to the {abbr}`ISPs (Internet Service Providers)`
+IP network, and from there to the rest of the Internet. A 2005 networking
+book noted that "Most DSL providers use PPPoE, which provides authentication,
+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 because 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`
+address, such as `192.168.1.0/24` by default.
+
+For a simple home network using just the ISP's equipment, this is usually
+desirable. But if you want to run VyOS as your firewall and router, this
+will result in having a double NAT and firewall setup. This results in a
+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
+it. In order for this method to work, you will have to figure out how to make
+your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL
+Transceiver device to connect between the Ethernet link of your VyOS and the
+phone cable. Once your DSL Transceiver is in Bridge Mode, you should get no
+IP address from it. Please make sure you connect to the Ethernet Port 1 if
+your DSL Transceiver has a switch, as some of them only work this way.
+
+Once you have an Ethernet device connected, i.e. `eth0`, then you can
+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
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+   :var0: pppoe
+   :var1: pppoe0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable.txt
+   :var0: pppoe
+   :var1: pppoe0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-mtu.txt
+   :var0: pppoe
+   :var1: pppoe0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vrf.txt
+   :var0: pppoe
+   :var1: pppoe0
+```
+
+### PPPoE options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name>
+
+   Use this command to restrict the PPPoE session on a given access
+   concentrator. Normally, a host sends a PPPoE initiation packet to start the
+   PPPoE discovery process, a number of access concentrators respond with offer
+   packets and the host selects one of the responding access concentrators to
+   serve this session.
+
+   This command allows you to select a specific access concentrator when you
+   know the access concentrators `<name>`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> authentication username <username>
+
+   Use this command to set the username for authenticating with a remote PPPoE
+   endpoint. Authentication is optional from the system's point of view but
+   most service providers require it.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> authentication password <password>
+
+   Use this command to set the password for authenticating with a remote PPPoE
+   endpoint. Authentication is optional from the system's point of view but
+   most service providers require it.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> connect-on-demand
+
+   When set the interface is enabled for "dial-on-demand".
+
+   Use this command to instruct the system to establish a PPPoE connection
+   automatically once traffic passes through the interface. A disabled on-demand
+   connection is established at boot time and remains up. If the link fails for
+   any reason, the link is brought back up immediately.
+
+   Enabled on-demand PPPoE connections bring up the link only when traffic needs
+   to pass this link.  If the link fails for any reason, the link is brought
+   back up automatically once traffic passes the interface again. If you
+   configure an on-demand PPPoE connection, you must also configure the idle
+   timeout period, after which an idle PPPoE link will be disconnected. A
+   non-zero idle timeout will never disconnect the link after it first came up.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> no-default-route
+
+   Only request an address from the PPPoE server but do not install any default
+   route.
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces pppoe pppoe0 no-default-route
+
+   .. note:: This command got added in VyOS 1.4 and inverts the logic from the old
+     ``default-route`` CLI option.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> default-route-distance <distance>
+
+   Set the distance for the default gateway sent by the PPPoE server.
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces pppoe pppoe0 default-route-distance 220
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> mru <mru>
+
+   Set the {abbr}`MRU (Maximum Receive Unit)` to `mru`. PPPd will ask the peer to
+   send packets of no more than `mru` bytes. The value of `mru` must be between 128
+   and 16384.
+
+   A value of 296 works well on very slow links (40 bytes for TCP/IP header + 256
+   bytes of data).
+
+   The default is 1492.
+
+   .. note:: When using the IPv6 protocol, MRU must be at least 1280 bytes.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> idle-timeout <time>
+
+   Use this command to set the idle timeout interval to be used with on-demand
+   PPPoE sessions. When an on-demand connection is established, the link is
+   brought up only when traffic is sent and is disabled when the link is idle
+   for the interval specified.
+
+   If this parameter is not set or 0, an on-demand link will not be taken down
+   when it is idle and after the initial establishment of the connection. It
+   will stay up forever.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> holdoff <time>
+
+   Use this command to set re-dial delay time to be used with persist PPPoE
+   sessions. When the PPPoE session is terminated by peer, and on-demand
+   option is not set, the router will attempt to re-establish the PPPoE link.
+
+   If this parameter is not set, the default holdoff time is 30 seconds.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> local-address <address>
+
+   Use this command to set the IP address of the local endpoint of a PPPoE
+   session. If it is not set it will be negotiated.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> no-peer-dns
+
+   Use this command to not install advertised DNS nameservers into the local
+   system.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> remote-address <address>
+
+   Use this command to set the IP address of the remote endpoint of a PPPoE
+   session. If it is not set it will be negotiated.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> service-name <name>
+
+   Use this command to specify a service name by which the local PPPoE interface
+   can select access concentrators to connect with. It will connect to any
+   access concentrator if not set.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> source-interface <source-interface>
+
+   Use this command to link the PPPoE connection to a physical interface. Each
+   PPPoE connection must be established over a physical interface. Interfaces
+   can be regular Ethernet interfaces, VIFs or bonding interfaces/VIFs.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> ip adjust-mss <mss | clamp-mss-to-pmtu>
+
+  As Internet wide PMTU discovery rarely works, we sometimes need to clamp our
+  TCP MSS value to a specific value. This is a field in the TCP options part of
+  a SYN packet. By setting the MSS value, you are telling the remote side
+  unequivocally 'do not try to send me packets bigger than this value'.
+
+  .. note:: This command was introduced in VyOS 1.4 - it was previously called:
+    ``set firewall options interface <name> adjust-mss <value>``
+
+  .. hint:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in
+    1452 bytes on a 1492 byte MTU.
+
+  Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to
+  automatically set the proper value.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> ip disable-forwarding
+
+  Configure interface-specific Host/Router behaviour. If set, the interface will
+  switch to host mode and IPv6 forwarding will be disabled on this interface.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> ip source-validation <strict | loose | disable>
+
+  Enable policy for source validation by reversed path, as specified in
+  {rfc}`3704`. Current recommended practice in {rfc}`3704` is to enable strict
+  mode to prevent IP spoofing from DDos attacks. If using asymmetric routing
+  or other complicated routing, then loose mode is recommended.
+
+  - strict: Each incoming packet is tested against the FIB and if the interface
+    is not the best reverse path the packet check will fail. By default failed
+    packets are discarded.
+
+  - loose: Each incoming packet's source address is also tested against the FIB
+    and if the source address is not reachable via any interface the packet
+    check will fail.
+
+  - disable: No source validation
+```
+
+#### IPv6
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> ipv6 address autoconf
+
+   Use this command to enable acquisition of IPv6 address using stateless
+   autoconfig (SLAAC).
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> ipv6 adjust-mss <mss | clamp-mss-to-pmtu>
+
+  As Internet wide PMTU discovery rarely works, we sometimes need to clamp our
+  TCP MSS value to a specific value. This is a field in the TCP options part of
+  a SYN packet. By setting the MSS value, you are telling the remote side
+  unequivocally 'do not try to send me packets bigger than this value'.
+
+  .. note:: This command was introduced in VyOS 1.4 - it was previously called:
+    ``set firewall options interface <name> adjust-mss <value>``
+
+  .. hint:: MSS value = MTU - 40 (IPv6 header) - 20 (TCP header), resulting in
+    1432 bytes on a 1492 byte MTU.
+
+  Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to
+  automatically set the proper value.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> ipv6 disable-forwarding
+
+  Configure interface-specific Host/Router behaviour. If set, the interface will
+  switch to host mode and IPv6 forwarding will be disabled on this interface.
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-dhcpv6-prefix-delegation.txt
+  :var0: pppoe
+  :var1: pppoe0
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces pppoe <interface>
+
+   Show detailed information on given `<interface>`
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces pppoe pppoe0
+     pppoe0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3
+         link/ppp
+         inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0
+            valid_lft forever preferred_lft forever
+
+         RX:  bytes    packets     errors    dropped    overrun      mcast
+         7002658233    5064967          0          0          0          0
+         TX:  bytes    packets     errors    dropped    carrier collisions
+          533822843    1620173          0          0          0          0
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces pppoe <interface> queue
+
+   Displays queue information for a PPPoE interface.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces pppoe pppoe0 queue
+     qdisc pfifo_fast 0: root refcnt 2 bands 3 priomap  1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1
+      Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0)
+      backlog 0b 0p requeues 0
+```
+
+### Connect/Disconnect
+
+```{eval-rst}
+.. opcmd:: disconnect interface <interface>
+
+   Test disconnecting given connection-oriented interface. `<interface>` can be
+   ``pppoe0`` as the example.
+```
+
+```{eval-rst}
+.. opcmd:: connect interface <interface>
+
+   Test connecting given connection-oriented interface. `<interface>` can be
+   ``pppoe0`` as the example.
+```
+
+## Example
+
+Requirements:
+
+- Your ISPs modem is connected to port `eth0` of your VyOS box.
+- No VLAN tagging required by your ISP.
+- You need your PPPoE credentials from your DSL ISP in order to configure
+  this. The usual username is in the form of <mailto:name@host.net> but may vary
+  depending on ISP.
+- The largest MTU size you can use with DSL is 1492 due to PPPoE overhead.
+  If you are switching from a DHCP based ISP like cable then be aware that
+  things like VPN links may need to have their MTU sizes adjusted to work
+  within this limit.
+- With the `name-server` option set to `none`, VyOS will ignore the
+  nameservers your ISP sends you and thus you can fully rely on the ones you
+  have configured statically.
+
+:::{note}
+Syntax has changed from VyOS 1.2 (crux) and it will be automatically
+migrated during an upgrade.
+
+A default route is automatically installed once the interface is up.
+To change this behavior use the `no-default-route` CLI option.
+:::
+
+```none
+set interfaces pppoe pppoe0 authentication username 'userid'
+set interfaces pppoe pppoe0 authentication password 'secret'
+set interfaces pppoe pppoe0 source-interface 'eth0'
+```
+
+You should add a firewall to your configuration above as well by
+assigning it to the pppoe0 itself as shown here:
+
+```none
+set firewall interface pppoe0 in name NET-IN
+set firewall interface pppoe0 local name NET-LOCAL
+set firewall interface pppoe0 out name NET-OUT
+```
+
+### VLAN Example
+
+Some recent ISPs require you to build the PPPoE connection through a VLAN
+interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS
+can easily create a PPPoE session through an encapsulated VLAN interface.
+The following configuration will run your PPPoE connection through VLAN7
+which is the default VLAN for Deutsche Telekom:
+
+```none
+set interfaces pppoe pppoe0 authentication username 'userid'
+set interfaces pppoe pppoe0 authentication password 'secret'
+set interfaces pppoe pppoe0 source-interface 'eth0.7'
+```
+
+#### IPv6 DHCPv6-PD Example
+
+
+The following configuration will setup a PPPoE session source from eth1 and
+assign a /64 prefix out of a /56 delegation (requested from the ISP) to eth0.
+The IPv6 address assigned to eth0 will be \<prefix>::1/64. If you do not know
+the prefix size delegated to you, start with sla-len 0.
+
+In addition we setup IPv6 {abbr}`RA (Router Advertisements)` to make the
+prefix known on the eth0 link.
+
+
+```none
+set interfaces pppoe pppoe0 authentication username vyos
+set interfaces pppoe pppoe0 authentication password vyos
+set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 address '1'
+set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 sla-id '0'
+set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56'
+set interfaces pppoe pppoe0 ipv6 address autoconf
+set interfaces pppoe pppoe0 source-interface eth1
+
+set service router-advert interface eth0 prefix ::/64
+```
diff --git a/docs/configuration/interfaces/pseudo-ethernet.md b/docs/configuration/interfaces/pseudo-ethernet.md
new file mode 100644
index 00000000..641bc8fb
--- /dev/null
+++ b/docs/configuration/interfaces/pseudo-ethernet.md
@@ -0,0 +1,68 @@
+---
+lastproofread: '2023-01-26'
+---
+
+(pseudo-ethernet-interface)=
+
+# MACVLAN - Pseudo Ethernet
+
+Pseudo-Ethernet or MACVLAN interfaces can be seen as subinterfaces to regular
+ethernet interfaces. Each and every subinterface is created a different media
+access control (MAC) address, for a single physical Ethernet port. Pseudo-
+Ethernet interfaces have most of their application in virtualized environments,
+
+By using Pseudo-Ethernet interfaces there will be less system overhead compared
+to running a traditional bridging approach. Pseudo-Ethernet interfaces can also
+be used to workaround the general limit of 4096 virtual LANs (VLANs) per
+physical Ethernet port, since that limit is with respect to a single MAC
+address.
+
+Every Virtual Ethernet interfaces behaves like a real Ethernet interface. They
+can have IPv4/IPv6 addresses configured, or can request addresses by DHCP/
+DHCPv6 and are associated/mapped with a real ethernet port. This also makes
+Pseudo-Ethernet interfaces interesting for testing purposes. A Pseudo-Ethernet
+device will inherit characteristics (speed, duplex, ...) from its physical
+parent (the so called link) interface.
+
+Once created in the system, Pseudo-Ethernet interfaces can be referenced in
+the exact same way as other Ethernet interfaces. Notes about using Pseudo-
+Ethernet interfaces:
+
+- Pseudo-Ethernet interfaces can not be reached from your internal host. This
+  means that you can not try to ping a Pseudo-Ethernet interface from the host
+  system on which it is defined. The ping will be lost.
+- Loopbacks occurs at the IP level the same way as for other interfaces,
+  ethernet frames are not forwarded between Pseudo-Ethernet interfaces.
+- Pseudo-Ethernet interfaces may not work in environments which expect a
+  {abbr}`NIC (Network Interface Card)` to only have a single address. This
+  applies to:
+  \- VMware machines using default settings
+  \- Network switches with security settings allowing only a single MAC address
+  \- xDSL modems that try to learn the MAC address of the NIC
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: pseudo-ethernet
+   :var1: peth0
+```
+
+### Pseudo Ethernet/MACVLAN options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX>
+
+   Specifies the physical `<ethX>` Ethernet interface associated with a Pseudo
+   Ethernet `<interface>`.
+```
+
+### VLAN
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: pseudo-ethernet
+   :var1: peth0
+```
diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/rst-bonding.rst
index 27f1bbed..27f1bbed 100644
--- a/docs/configuration/interfaces/bonding.rst
+++ b/docs/configuration/interfaces/rst-bonding.rst
diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/rst-bridge.rst
index e69a6e26..e69a6e26 100644
--- a/docs/configuration/interfaces/bridge.rst
+++ b/docs/configuration/interfaces/rst-bridge.rst
diff --git a/docs/configuration/interfaces/dummy.rst b/docs/configuration/interfaces/rst-dummy.rst
index 945361c2..945361c2 100644
--- a/docs/configuration/interfaces/dummy.rst
+++ b/docs/configuration/interfaces/rst-dummy.rst
diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/rst-ethernet.rst
index 30a13b5b..30a13b5b 100644
--- a/docs/configuration/interfaces/ethernet.rst
+++ b/docs/configuration/interfaces/rst-ethernet.rst
diff --git a/docs/configuration/interfaces/geneve.rst b/docs/configuration/interfaces/rst-geneve.rst
index 1e8b8096..1e8b8096 100644
--- a/docs/configuration/interfaces/geneve.rst
+++ b/docs/configuration/interfaces/rst-geneve.rst
diff --git a/docs/configuration/interfaces/index.rst b/docs/configuration/interfaces/rst-index.rst
index 0f02d1e3..0f02d1e3 100644
--- a/docs/configuration/interfaces/index.rst
+++ b/docs/configuration/interfaces/rst-index.rst
diff --git a/docs/configuration/interfaces/l2tpv3.rst b/docs/configuration/interfaces/rst-l2tpv3.rst
index 4fa47199..4fa47199 100644
--- a/docs/configuration/interfaces/l2tpv3.rst
+++ b/docs/configuration/interfaces/rst-l2tpv3.rst
diff --git a/docs/configuration/interfaces/loopback.rst b/docs/configuration/interfaces/rst-loopback.rst
index b5fbdf83..b5fbdf83 100644
--- a/docs/configuration/interfaces/loopback.rst
+++ b/docs/configuration/interfaces/rst-loopback.rst
diff --git a/docs/configuration/interfaces/macsec.rst b/docs/configuration/interfaces/rst-macsec.rst
index 1ab7f361..1ab7f361 100644
--- a/docs/configuration/interfaces/macsec.rst
+++ b/docs/configuration/interfaces/rst-macsec.rst
diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/rst-openvpn.rst
index 76d44ed5..76d44ed5 100644
--- a/docs/configuration/interfaces/openvpn.rst
+++ b/docs/configuration/interfaces/rst-openvpn.rst
diff --git a/docs/configuration/interfaces/pppoe.rst b/docs/configuration/interfaces/rst-pppoe.rst
index 65081e1c..65081e1c 100644
--- a/docs/configuration/interfaces/pppoe.rst
+++ b/docs/configuration/interfaces/rst-pppoe.rst
diff --git a/docs/configuration/interfaces/pseudo-ethernet.rst b/docs/configuration/interfaces/rst-pseudo-ethernet.rst
index 59b3581c..59b3581c 100644
--- a/docs/configuration/interfaces/pseudo-ethernet.rst
+++ b/docs/configuration/interfaces/rst-pseudo-ethernet.rst
diff --git a/docs/configuration/interfaces/sstp-client.rst b/docs/configuration/interfaces/rst-sstp-client.rst
index 27eb9c39..27eb9c39 100644
--- a/docs/configuration/interfaces/sstp-client.rst
+++ b/docs/configuration/interfaces/rst-sstp-client.rst
diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/rst-tunnel.rst
index 31539d9f..31539d9f 100644
--- a/docs/configuration/interfaces/tunnel.rst
+++ b/docs/configuration/interfaces/rst-tunnel.rst
diff --git a/docs/configuration/interfaces/virtual-ethernet.rst b/docs/configuration/interfaces/rst-virtual-ethernet.rst
index 3324feb6..3324feb6 100644
--- a/docs/configuration/interfaces/virtual-ethernet.rst
+++ b/docs/configuration/interfaces/rst-virtual-ethernet.rst
diff --git a/docs/configuration/interfaces/vti.rst b/docs/configuration/interfaces/rst-vti.rst
index 1704b9d1..1704b9d1 100644
--- a/docs/configuration/interfaces/vti.rst
+++ b/docs/configuration/interfaces/rst-vti.rst
diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/rst-vxlan.rst
index 831870c5..831870c5 100644
--- a/docs/configuration/interfaces/vxlan.rst
+++ b/docs/configuration/interfaces/rst-vxlan.rst
diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/rst-wireguard.rst
index a40bee01..a40bee01 100644
--- a/docs/configuration/interfaces/wireguard.rst
+++ b/docs/configuration/interfaces/rst-wireguard.rst
diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/rst-wireless.rst
index df153763..df153763 100644
--- a/docs/configuration/interfaces/wireless.rst
+++ b/docs/configuration/interfaces/rst-wireless.rst
diff --git a/docs/configuration/interfaces/wwan.rst b/docs/configuration/interfaces/rst-wwan.rst
index 76a4a3d7..76a4a3d7 100644
--- a/docs/configuration/interfaces/wwan.rst
+++ b/docs/configuration/interfaces/rst-wwan.rst
diff --git a/docs/configuration/interfaces/sstp-client.md b/docs/configuration/interfaces/sstp-client.md
new file mode 100644
index 00000000..b2c79537
--- /dev/null
+++ b/docs/configuration/interfaces/sstp-client.md
@@ -0,0 +1,173 @@
+---
+lastproofread: '2022-12-11'
+---
+
+(sstp-client-interface)=
+
+# SSTP Client
+
+{abbr}`SSTP (Secure Socket Tunneling Protocol)` is a form of {abbr}`VTP (Virtual
+Private Network)` tunnel that provides a mechanism to transport PPP traffic
+through an SSL/TLS channel. SSL/TLS provides transport-level security with key
+negotiation, encryption and traffic integrity checking. The use of SSL/TLS over
+TCP port 443 (by default, port can be changed) allows SSTP to pass through
+virtually all firewalls and proxy servers except for authenticated web proxies.
+
+:::{note}
+VyOS also comes with a build in SSTP server, see {ref}`sstp`.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+   :var0: sstpc
+   :var1: sstpc0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable.txt
+   :var0: sstpc
+   :var1: sstpc0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-mtu.txt
+   :var0: sstpc
+   :var1: sstpc0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vrf.txt
+   :var0: sstpc
+   :var1: sstpc0
+```
+
+### SSTP Client Options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> no-default-route
+
+   Only request an address from the SSTP server but do not install any default
+   route.
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces sstpc sstpc0 no-default-route
+
+   .. note:: This command got added in VyOS 1.4 and inverts the logic from the old
+     ``default-route`` CLI option.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> default-route-distance <distance>
+
+   Set the distance for the default gateway sent by the SSTP server.
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces sstpc sstpc0 default-route-distance 220
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> no-peer-dns
+
+   Use this command to not install advertised DNS nameservers into the local
+   system.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> server <address>
+
+   SSTP remote server to connect to. Can be either an IP address or FQDN.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> ip adjust-mss <mss | clamp-mss-to-pmtu>
+
+  As Internet wide PMTU discovery rarely works, we sometimes need to clamp our
+  TCP MSS value to a specific value. This is a field in the TCP options part of
+  a SYN packet. By setting the MSS value, you are telling the remote side
+  unequivocally 'do not try to send me packets bigger than this value'.
+
+  .. note:: This command was introduced in VyOS 1.4 - it was previously called:
+    ``set firewall options interface <name> adjust-mss <value>``
+
+  .. hint:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in
+    1452 bytes on a 1492 byte MTU.
+
+  Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to
+  automatically set the proper value.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> ip disable-forwarding
+
+  Configure interface-specific Host/Router behaviour. If set, the interface will
+  switch to host mode and IPv6 forwarding will be disabled on this interface.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> ip source-validation <strict | loose | disable>
+
+  Enable policy for source validation by reversed path, as specified in
+  {rfc}`3704`. Current recommended practice in {rfc}`3704` is to enable strict
+  mode to prevent IP spoofing from DDos attacks. If using asymmetric routing
+  or other complicated routing, then loose mode is recommended.
+
+  - strict: Each incoming packet is tested against the FIB and if the interface
+    is not the best reverse path the packet check will fail. By default failed
+    packets are discarded.
+
+  - loose: Each incoming packet's source address is also tested against the FIB
+    and if the source address is not reachable via any interface the packet
+    check will fail.
+
+  - disable: No source validation
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces sstpc <interface>
+
+   Show detailed information on given `<interface>`
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces sstpc sstpc10
+     sstpc10: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 3
+         link/ppp
+         inet 192.0.2.5 peer 192.0.2.254/32 scope global sstpc10
+            valid_lft forever preferred_lft forever
+         inet6 fe80::fd53:c7ff:fe8b:144f/64 scope link
+            valid_lft forever preferred_lft forever
+
+         RX:  bytes  packets  errors  dropped  overrun       mcast
+                215        9       0        0        0           0
+         TX:  bytes  packets  errors  dropped  carrier  collisions
+                539       14       0        0        0           0
+
+```
+
+### Connect/Disconnect
+
+```{eval-rst}
+.. opcmd:: disconnect interface <interface>
+
+   Test disconnecting given connection-oriented interface. `<interface>` can be
+   ``sstpc0`` as the example.
+```
+
+```{eval-rst}
+.. opcmd:: connect interface <interface>
+
+   Test connecting given connection-oriented interface. `<interface>` can be
+   ``sstpc0`` as the example.
+```
diff --git a/docs/configuration/interfaces/tunnel.md b/docs/configuration/interfaces/tunnel.md
new file mode 100644
index 00000000..7f435f8c
--- /dev/null
+++ b/docs/configuration/interfaces/tunnel.md
@@ -0,0 +1,281 @@
+---
+lastproofread: '2023-01-26'
+---
+
+(tunnel-interface)=
+
+# Tunnel
+
+This article touches on 'classic' IP tunneling protocols.
+
+GRE is often seen as a one size fits all solution when it comes to classic IP
+tunneling protocols, and for a good reason. However, there are more specialized
+options, and many of them are supported by VyOS. There are also rather obscure
+GRE options that can be useful.
+
+All those protocols are grouped under `interfaces tunnel` in VyOS. Let's take
+a closer look at the protocols and options currently supported by VyOS.
+
+## Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-address.txt
+   :var0: tunnel
+   :var1: tun0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-without-mac.txt
+   :var0: tunnel
+   :var1: tun0
+```
+
+## IPIP
+
+This is one of the simplest types of tunnels, as defined by {rfc}`2003`.
+It takes an IPv4 packet and sends it as a payload of another IPv4 packet. For
+this reason, there are no other configuration options for this kind of tunnel.
+
+An example:
+
+```none
+set interfaces tunnel tun0 encapsulation ipip
+set interfaces tunnel tun0 source-address 192.0.2.10
+set interfaces tunnel tun0 remote 203.0.113.20
+set interfaces tunnel tun0 address 192.168.100.200/24
+```
+
+## IP6IP6
+
+This is the IPv6 counterpart of IPIP. I'm not aware of an RFC that defines this
+encapsulation specifically, but it's a natural specific case of IPv6
+encapsulation mechanisms described in :rfc:2473\`.
+
+It's not likely that anyone will need it any time soon, but it does exist.
+
+An example:
+
+```none
+set interfaces tunnel tun0 encapsulation ip6ip6
+set interfaces tunnel tun0 source-address 2001:db8:aa::1
+set interfaces tunnel tun0 remote 2001:db8:aa::2
+set interfaces tunnel tun0 address 2001:db8:bb::1/64
+```
+
+## IPIP6
+
+In the future this is expected to be a very useful protocol (though there are
+[other proposals]).
+
+As the name implies, it's IPv4 encapsulated in IPv6, as simple as that.
+
+An example:
+
+```none
+set interfaces tunnel tun0 encapsulation ipip6
+set interfaces tunnel tun0 source-address 2001:db8:aa::1
+set interfaces tunnel tun0 remote 2001:db8:aa::2
+set interfaces tunnel tun0 address 192.168.70.80/24
+```
+
+## 6in4 (SIT)
+
+6in4 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in
+{rfc}`4213`. The 6in4 traffic is sent over IPv4 inside IPv4 packets whose IP
+headers have the IP protocol number set to 41. This protocol number is
+specifically designated for IPv6 encapsulation, the IPv4 packet header is
+immediately followed by the IPv6 packet being carried. The encapsulation
+overhead is the size of the IPv4 header of 20 bytes, therefore with an MTU of
+1500 bytes, IPv6 packets of 1480 bytes can be sent without fragmentation. This
+tunneling technique is frequently used by IPv6 tunnel brokers like [Hurricane
+Electric][hurricane electric].
+
+An example:
+
+```none
+set interfaces tunnel tun0 encapsulation sit
+set interfaces tunnel tun0 source-address 192.0.2.10
+set interfaces tunnel tun0 remote 192.0.2.20
+set interfaces tunnel tun0 address 2001:db8:bb::1/64
+```
+
+A full example of a Tunnelbroker.net config can be found at
+{ref}`here <examples-tunnelbroker-ipv6>`.
+
+## Generic Routing Encapsulation (GRE)
+
+A GRE tunnel operates at layer 3 of the OSI model and is represented by IP
+protocol 47. The main benefit of a GRE tunnel is that you are able to carry
+multiple protocols inside the same tunnel. GRE also supports multicast traffic
+and supports routing protocols that leverage multicast to form neighbor
+adjacencies.
+
+A VyOS GRE tunnel can carry both IPv4 and IPv6 traffic and can also be created
+over either IPv4 (gre) or IPv6 (ip6gre).
+
+### Configuration
+
+A basic configuration requires a tunnel source (source-address), a tunnel
+destination (remote), an encapsulation type (gre), and an address (ipv4/ipv6).
+Below is a basic IPv4 only configuration example taken from a VyOS router and
+a Cisco IOS router. The main difference between these two configurations is
+that VyOS requires you explicitly configure the encapsulation type. The Cisco
+router defaults to GRE IP otherwise it would have to be configured as well.
+
+**VyOS Router:**
+
+```none
+set interfaces tunnel tun100 address '10.0.0.1/30'
+set interfaces tunnel tun100 encapsulation 'gre'
+set interfaces tunnel tun100 source-address '198.51.100.2'
+set interfaces tunnel tun100 remote '203.0.113.10'
+```
+
+**Cisco IOS Router:**
+
+```none
+interface Tunnel100
+ip address 10.0.0.2 255.255.255.252
+tunnel source 203.0.113.10
+tunnel destination 198.51.100.2
+```
+
+Here is a second example of a dual-stack tunnel over IPv6 between a VyOS router
+and a Linux host using systemd-networkd.
+
+**VyOS Router:**
+
+```none
+set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126'
+set interfaces tunnel tun101 address '192.168.5.1/30'
+set interfaces tunnel tun101 encapsulation 'ip6gre'
+set interfaces tunnel tun101 source-address '2001:db8:babe:face::3afe:3'
+set interfaces tunnel tun101 remote '2001:db8:9bb:3ce::5'
+```
+
+**Linux systemd-networkd:**
+
+This requires two files, one to create the device (XXX.netdev) and one
+to configure the network on the device (XXX.network)
+
+```none
+# cat /etc/systemd/network/gre-example.netdev
+[NetDev]
+Name=gre-example
+Kind=ip6gre
+MTUBytes=14180
+
+[Tunnel]
+Remote=2001:db8:babe:face::3afe:3
+
+
+# cat /etc/systemd/network/gre-example.network
+[Match]
+Name=gre-example
+
+[Network]
+Address=2001:db8:feed:beef::2/126
+
+[Address]
+Address=192.168.5.2/30
+```
+
+### Tunnel keys
+
+GRE is also the only classic protocol that allows creating multiple tunnels
+with the same source and destination due to its support for tunnel keys.
+Despite its name, this feature has nothing to do with security: it's simply
+an identifier that allows routers to tell one tunnel from another.
+
+An example:
+
+```none
+set interfaces tunnel tun0 source-address 192.0.2.10
+set interfaces tunnel tun0 remote 192.0.2.20
+set interfaces tunnel tun0 address 10.40.50.60/24
+set interfaces tunnel tun0 parameters ip key 10
+```
+
+```none
+set interfaces tunnel tun0 source-address 192.0.2.10
+set interfaces tunnel tun0 remote 192.0.2.20
+set interfaces tunnel tun0 address 172.16.17.18/24
+set interfaces tunnel tun0 parameters ip key 20
+```
+
+### GRETAP
+
+While normal GRE is for layer 3, GRETAP is for layer 2. GRETAP can encapsulate
+Ethernet frames, thus it can be bridged with other interfaces to create
+datalink layer segments that span multiple remote sites.
+
+```none
+set interfaces bridge br0 member interface eth0
+set interfaces bridge br0 member interface tun0
+set interfaces tunnel tun0 encapsulation gretap
+set interfaces tunnel tun0 source-address 198.51.100.2
+set interfaces tunnel tun0 remote 203.0.113.10
+```
+
+### Troubleshooting
+
+GRE is a well defined standard that is common in most networks. While not
+inherently difficult to configure there are a couple of things to keep in mind
+to make sure the configuration performs as expected. A common cause for GRE
+tunnels to fail to come up correctly include ACL or Firewall configurations
+that are discarding IP protocol 47 or blocking your source/destination traffic.
+
+**1. Confirm IP connectivity between tunnel source-address and remote:**
+
+```none
+vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4
+PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data.
+64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms
+64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms
+64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms
+64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms
+
+--- 203.0.113.10 ping statistics ---
+4 packets transmitted, 4 received, 0% packet loss, time 3007ms
+rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms
+```
+
+**2. Confirm the link type has been set to GRE:**
+
+```none
+vyos@vyos:~$ show interfaces tunnel tun100
+tun100@NONE: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000
+  link/gre 198.51.100.2 peer 203.0.113.10
+  inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100
+     valid_lft forever preferred_lft forever
+  inet6 fe80::5efe:c612:2/64 scope link
+     valid_lft forever preferred_lft forever
+
+  RX:  bytes    packets     errors    dropped    overrun      mcast
+        2183         27          0          0          0          0
+  TX:  bytes    packets     errors    dropped    carrier collisions
+         836          9          0          0          0          0
+```
+
+**3. Confirm IP connectivity across the tunnel:**
+
+```none
+vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4
+PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data.
+64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms
+64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms
+64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms
+64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms
+
+--- 10.0.0.2 ping statistics ---
+4 packets transmitted, 4 received, 0% packet loss, time 3008ms
+rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms
+```
+
+:::{note}
+There is also a GRE over IPv6 encapsulation available, it is
+called: `ip6gre`.
+:::
+
+[hurricane electric]: https://tunnelbroker.net/
+[other proposals]: https://www.isc.org/othersoftware/
diff --git a/docs/configuration/interfaces/virtual-ethernet.md b/docs/configuration/interfaces/virtual-ethernet.md
new file mode 100644
index 00000000..13d3fb8f
--- /dev/null
+++ b/docs/configuration/interfaces/virtual-ethernet.md
@@ -0,0 +1,118 @@
+---
+lastproofread: '2022-11-25'
+---
+
+(virtual-ethernet)=
+
+# Virtual Ethernet
+
+The veth devices are virtual Ethernet devices. They can act as tunnels between
+network namespaces to create a bridge to a physical network device in another
+namespace or VRF, but can also be used as standalone network devices.
+
+:::{note}
+veth interfaces need to be created in pairs - it's called the peer name
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-address-with-dhcp.txt
+   :var0: virtual-ethernet
+   :var1: veth0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+   :var0: virtual-ethernet
+   :var1: veth0
+```
+
+### VLAN
+
+#### Regular VLANs (802.1q)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: virtual-ethernet
+   :var1: veth0
+```
+
+#### QinQ (802.1ad)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021ad.txt
+   :var0: virtual-ethernet
+   :var1: veth0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable.txt
+   :var0: virtual-ethernet
+   :var1: veth0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vrf.txt
+   :var0: virtual-ethernet
+   :var1: veth0
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces virtual-ethernet
+
+   Show brief interface information.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces virtual-ethernet
+     Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+     Interface        IP Address                        S/L  Description
+     ---------        ----------                        ---  -----------
+     veth10           100.64.0.0/31                     u/u
+     veth11           100.64.0.1/31                     u/u
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces virtual-ethernet <interface>
+
+   Show detailed information on given `<interface>`
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces virtual-ethernet veth11
+     10: veth11@veth10: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master red state UP group default qlen 1000
+         link/ether b2:7b:df:47:e9:11 brd ff:ff:ff:ff:ff:ff
+         inet 100.64.0.1/31 scope global veth11
+            valid_lft forever preferred_lft forever
+         inet6 fe80::b07b:dfff:fe47:e911/64 scope link
+            valid_lft forever preferred_lft forever
+
+
+         RX:  bytes    packets     errors    dropped    overrun      mcast
+                  0          0          0          0          0          0
+         TX:  bytes    packets     errors    dropped    carrier collisions
+            1369707       4267          0          0          0          0
+```
+
+## Example
+
+Interconnect the global VRF with vrf "red" using the veth10 \<-> veth 11 pair
+
+```none
+set interfaces virtual-ethernet veth10 address '100.64.0.0/31'
+set interfaces virtual-ethernet veth10 peer-name 'veth11'
+set interfaces virtual-ethernet veth11 address '100.64.0.1/31'
+set interfaces virtual-ethernet veth11 peer-name 'veth10'
+set interfaces virtual-ethernet veth11 vrf 'red'
+set vrf name red table '1000'
+
+vyos@vyos:~$ ping 100.64.0.1
+PING 100.64.0.1 (100.64.0.1) 56(84) bytes of data.
+64 bytes from 100.64.0.1: icmp_seq=1 ttl=64 time=0.080 ms
+64 bytes from 100.64.0.1: icmp_seq=2 ttl=64 time=0.119 ms
+```
diff --git a/docs/configuration/interfaces/vti.md b/docs/configuration/interfaces/vti.md
new file mode 100644
index 00000000..f516014d
--- /dev/null
+++ b/docs/configuration/interfaces/vti.md
@@ -0,0 +1,40 @@
+(vti-interface)=
+
+# VTI - Virtual Tunnel Interface
+
+Set Virtual Tunnel Interface
+
+```none
+set interfaces vti vti0 address 192.168.2.249/30
+set interfaces vti vti0 address 2001:db8:2::249/64
+```
+
+Results in:
+
+```none
+vyos@vyos# show interfaces vti
+vti vti0 {
+    address 192.168.2.249/30
+    address 2001:db8:2::249/64
+    description "Description"
+}
+```
+
+:::{warning}
+When using site-to-site IPsec with VTI interfaces,
+be sure to disable route autoinstall
+:::
+
+```none
+set vpn ipsec options disable-route-autoinstall
+```
+
+More details about the IPsec and VTI issue and option disable-route-autoinstall
+<https://blog.vyos.io/vyos-1-dot-2-0-development-news-in-july>
+
+The root cause of the problem is that for VTI tunnels to work, their traffic
+selectors have to be set to 0.0.0.0/0 for traffic to match the tunnel, even
+though actual routing decision is made according to netfilter marks. Unless
+route insertion is disabled entirely, StrongSWAN thus mistakenly inserts a
+default route through the VTI peer address, which makes all traffic routed
+to nowhere.
diff --git a/docs/configuration/interfaces/vxlan.md b/docs/configuration/interfaces/vxlan.md
new file mode 100644
index 00000000..0eff152c
--- /dev/null
+++ b/docs/configuration/interfaces/vxlan.md
@@ -0,0 +1,366 @@
+---
+lastproofread: '2023-01-26'
+---
+
+(vxlan-interface)=
+
+# VXLAN
+
+{abbr}`VXLAN (Virtual Extensible LAN)` is a network virtualization technology
+that attempts to address the scalability problems associated with large cloud
+computing deployments. It uses a VLAN-like encapsulation technique to
+encapsulate OSI layer 2 Ethernet frames within layer 4 UDP datagrams, using
+4789 as the default IANA-assigned destination UDP port number. VXLAN
+endpoints, which terminate VXLAN tunnels and may be either virtual or physical
+switch ports, are known as {abbr}`VTEPs (VXLAN tunnel endpoints)`.
+
+VXLAN is an evolution of efforts to standardize an overlay encapsulation
+protocol. It increases the scalability up to 16 million logical networks and
+allows for layer 2 adjacency across IP networks. Multicast or unicast with
+head-end replication (HER) is used to flood broadcast, unknown unicast,
+and multicast (BUM) traffic.
+
+The VXLAN specification was originally created by VMware, Arista Networks
+and Cisco. Other backers of the VXLAN technology include Huawei, Broadcom,
+Citrix, Pica8, Big Switch Networks, Cumulus Networks, Dell EMC, Ericsson,
+Mellanox, FreeBSD, OpenBSD, Red Hat, Joyent, and Juniper Networks.
+
+VXLAN was officially documented by the IETF in {rfc}`7348`.
+
+If configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing
+(Hyper-V) or Forged Transmits (ESX) are permitted, otherwise forwarded frames
+may be blocked by the hypervisor.
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-without-dhcp.txt
+  :var0: vxlan
+  :var1: vxlan0
+```
+
+### VXLAN specific options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> vni <number>
+
+  Each VXLAN segment is identified through a 24-bit segment ID, termed the
+  {abbr}`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows
+  up to 16M VXLAN segments to coexist within the same administrative domain.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> port <port>
+
+  Configure port number of remote VXLAN endpoint.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> source-address <IP address>
+
+  Source IP address used for VXLAN underlay. This is mandatory when using VXLAN
+  via L2VPN/EVPN.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> gpe
+
+  Enables the Generic Protocol extension (VXLAN-GPE). Currently, this is only
+  supported together with the external keyword.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> parameters external
+
+  Specifies whether an external control plane (e.g. BGP L2VPN/EVPN) or the
+  internal FDB should be used.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> parameters neighbor-suppress
+
+  In order to minimize the flooding of ARP and ND messages in the VXLAN network,
+  EVPN includes provisions {rfc}`7432#section-10` that allow participating VTEPs
+  to suppress such messages in case they know the MAC-IP binding and can reply
+  on behalf of the remote host.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> parameters nolearning
+
+   Specifies if unknown source link layer addresses and IP addresses are entered
+   into the VXLAN device forwarding database.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> parameters vni-filter
+
+   Specifies whether the VXLAN device is capable of vni filtering.
+
+   Only works with a VXLAN device with external flag set.
+
+   .. note::  The device can only receive packets with VNIs configured in
+      the VNI filtering table.
+```
+
+#### Unicast
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> remote <address>
+
+  IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the
+  remote IPv4/IPv6 address can set directly.
+```
+
+#### Multicast
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> source-interface <interface>
+
+  Interface used for VXLAN underlay. This is mandatory when using VXLAN via
+  a multicast network. VXLAN traffic will always enter and exit this interface.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> group <address>
+
+  Multicast group address for VXLAN interface. VXLAN tunnels can be built
+  either via Multicast or via Unicast.
+
+  Both IPv4 and IPv6 multicast is possible.
+```
+
+## Multicast VXLAN
+
+Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5
+
+PC4 has IP 10.0.0.4/24 and PC5 has IP 10.0.0.5/24, so they believe they are in
+the same broadcast domain.
+
+Let's assume PC4 on Leaf2 wants to ping PC5 on Leaf3. Instead of setting Leaf3
+as our remote end manually, Leaf2 encapsulates the packet into a UDP-packet and
+sends it to its designated multicast-address via Spine1. When Spine1 receives
+this packet it forwards it to all other leaves who has joined the same
+multicast-group, in this case Leaf3. When Leaf3 receives the packet it forwards
+it, while at the same time learning that PC4 is reachable behind Leaf2, because
+the encapsulated packet had Leaf2's IP address set as source IP.
+
+PC5 receives the ping echo, responds with an echo reply that Leaf3 receives and
+this time forwards to Leaf2's unicast address directly because it learned the
+location of PC4 above. When Leaf2 receives the echo reply from PC5 it sees that
+it came from Leaf3 and so remembers that PC5 is reachable via Leaf3.
+
+Thanks to this discovery, any subsequent traffic between PC4 and PC5 will not
+be using the multicast-address between the leaves as they both know behind which
+Leaf the PCs are connected. This saves traffic as less multicast packets sent
+reduces the load on the network, which improves scalability when more leaves are
+added.
+
+For optimal scalability, Multicast shouldn't be used at all, but instead use BGP
+to signal all connected devices between leaves. Unfortunately, VyOS does not yet
+support this.
+
+## Single VXLAN device (SVD)
+
+FRR supports a new way of configuring VLAN-to-VNI mappings for EVPN-VXLAN, when
+working with the Linux kernel. In this new way, the mapping of a VLAN to a
+{abbr}`VNI (VXLAN Network Identifier (or VXLAN Segment ID))` is configured
+against a container VXLAN interface which is referred to as a
+{abbr}`SVD (Single VXLAN device)`.
+
+Multiple VLAN to VNI mappings can be configured against the same SVD. This
+allows for a significant scaling of the number of VNIs since a separate VXLAN
+interface is no longer required for each VNI.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> vlan-to-vni <vlan> vni <vni>
+
+   Maps the VNI to the specified VLAN id. The VLAN can then be consumed by
+   a bridge.
+
+   Sample configuration of SVD with VLAN to VNI mappings is shown below.
+
+   .. code-block:: none
+
+    set interfaces bridge br0 member interface vxlan0
+    set interfaces vxlan vxlan0 parameters external
+    set interfaces vxlan vxlan0 source-interface 'dum0'
+    set interfaces vxlan vxlan0 vlan-to-vni 10 vni '10010'
+    set interfaces vxlan vxlan0 vlan-to-vni 11 vni '10011'
+    set interfaces vxlan vxlan0 vlan-to-vni 30 vni '10030'
+    set interfaces vxlan vxlan0 vlan-to-vni 31 vni '10031'
+```
+
+### Example
+
+The setup is this: Leaf2 - Spine1 - Leaf3
+
+Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a
+VyOS router running 1.2.
+
+This topology was built using GNS3.
+
+Topology:
+
+```none
+Spine1:
+fa0/2 towards Leaf2, IP-address: 10.1.2.1/24
+fa0/3 towards Leaf3, IP-address: 10.1.3.1/24
+
+Leaf2:
+Eth0 towards Spine1, IP-address: 10.1.2.2/24
+Eth1 towards a vlan-aware switch
+
+Leaf3:
+Eth0 towards Spine1, IP-address 10.1.3.3/24
+Eth1 towards a vlan-aware switch
+```
+
+**Spine1 Configuration:**
+
+```none
+conf t
+ip multicast-routing
+!
+interface fastethernet0/2
+ ip address 10.1.2.1 255.255.255.0
+ ip pim sparse-dense-mode
+!
+interface fastethernet0/3
+ ip address 10.1.3.1 255.255.255.0
+ ip pim sparse-dense-mode
+!
+router ospf 1
+ network 10.0.0.0 0.255.255.255 area 0
+```
+
+Multicast-routing is required for the leaves to forward traffic between each
+other in a more scalable way. This also requires PIM to be enabled towards the
+leaves so that the Spine can learn what multicast groups each Leaf expects
+traffic from.
+
+**Leaf2 configuration:**
+
+```none
+set interfaces ethernet eth0 address '10.1.2.2/24'
+set protocols ospf area 0 network '10.0.0.0/8'
+
+! Our first vxlan interface
+set interfaces bridge br241 address '172.16.241.1/24'
+set interfaces bridge br241 member interface 'eth1.241'
+set interfaces bridge br241 member interface 'vxlan241'
+
+set interfaces vxlan vxlan241 group '239.0.0.241'
+set interfaces vxlan vxlan241 source-interface 'eth0'
+set interfaces vxlan vxlan241 vni '241'
+
+! Our seconds vxlan interface
+set interfaces bridge br242 address '172.16.242.1/24'
+set interfaces bridge br242 member interface 'eth1.242'
+set interfaces bridge br242 member interface 'vxlan242'
+
+set interfaces vxlan vxlan242 group '239.0.0.242'
+set interfaces vxlan vxlan242 source-interface 'eth0'
+set interfaces vxlan vxlan242 vni '242'
+```
+
+**Leaf3 configuration:**
+
+```none
+set interfaces ethernet eth0 address '10.1.3.3/24'
+set protocols ospf area 0 network '10.0.0.0/8'
+
+! Our first vxlan interface
+set interfaces bridge br241 address '172.16.241.1/24'
+set interfaces bridge br241 member interface 'eth1.241'
+set interfaces bridge br241 member interface 'vxlan241'
+
+set interfaces vxlan vxlan241 group '239.0.0.241'
+set interfaces vxlan vxlan241 source-interface 'eth0'
+set interfaces vxlan vxlan241 vni '241'
+
+! Our seconds vxlan interface
+set interfaces bridge br242 address '172.16.242.1/24'
+set interfaces bridge br242 member interface 'eth1.242'
+set interfaces bridge br242 member interface 'vxlan242'
+
+set interfaces vxlan vxlan242 group '239.0.0.242'
+set interfaces vxlan vxlan242 source-interface 'eth0'
+set interfaces vxlan vxlan242 vni '242'
+```
+
+As you can see, Leaf2 and Leaf3 configuration is almost identical. There are
+lots of commands above, I'll try to into more detail below, command
+descriptions are placed under the command boxes:
+
+```none
+set interfaces bridge br241 address '172.16.241.1/24'
+```
+
+This commands creates a bridge that is used to bind traffic on eth1 vlan 241
+with the vxlan241-interface. The IP address is not required. It may however be
+used as a default gateway for each Leaf which allows devices on the vlan to
+reach other subnets. This requires that the subnets are redistributed by OSPF
+so that the Spine will learn how to reach it. To do this you need to change the
+OSPF network from '10.0.0.0/8' to '0.0.0.0/0' to allow 172.16/12-networks to be
+advertised.
+
+```none
+set interfaces bridge br241 member interface 'eth1.241'
+set interfaces bridge br241 member interface 'vxlan241'
+```
+
+Binds eth1.241 and vxlan241 to each other by making them both member
+interfaces of the same bridge.
+
+```none
+set interfaces vxlan vxlan241 group '239.0.0.241'
+```
+
+The multicast-group used by all leaves for this vlan extension. Has to be the
+same on all leaves that has this interface.
+
+```none
+set interfaces vxlan vxlan241 source-interface 'eth0'
+```
+
+Sets the interface to listen for multicast packets on. Could be a loopback, not
+yet tested.
+
+```none
+set interfaces vxlan vxlan241 vni '241'
+```
+
+Sets the unique id for this vxlan-interface. Not sure how it correlates with
+multicast-address.
+
+```none
+set interfaces vxlan vxlan241 port 12345
+```
+
+The destination port used for creating a VXLAN interface defaults to
+4789\. Aconfiguration directive to support a user-specified destination port
+to override that behavior is available using the above command.
+
+## Unicast VXLAN
+
+Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can be
+set directly. Let's change the Multicast example from above:
+
+```none
+# leaf2 and leaf3
+delete interfaces vxlan vxlan241 group '239.0.0.241'
+delete interfaces vxlan vxlan241 source-interface 'eth0'
+
+# leaf2
+set interface vxlan vxlan241 remote 10.1.3.3
+
+# leaf3
+set interface vxlan vxlan241 remote 10.1.2.2
+```
+
+The default port udp is set to 4789.
+It can be changed with `set interface vxlan <vxlanN> port <port>`
diff --git a/docs/configuration/interfaces/wireguard.md b/docs/configuration/interfaces/wireguard.md
new file mode 100644
index 00000000..3f69a7fe
--- /dev/null
+++ b/docs/configuration/interfaces/wireguard.md
@@ -0,0 +1,434 @@
+---
+lastproofread: '2023-01-26'
+---
+
+(wireguard)=
+
+# WireGuard
+
+WireGuard is an extremely simple yet fast and modern VPN that utilizes
+state-of-the-art cryptography. See <https://www.wireguard.com> for more
+information.
+
+## Site to Site VPN
+
+This diagram corresponds with the example site to site configuration below.
+
+:::{figure} /_static/images/wireguard_site2site_diagram.jpg
+:::
+
+## Keypairs
+
+WireGuard requires the generation of a keypair, which includes a private key to
+decrypt incoming traffic, and a public key for peer(s) to encrypt traffic.
+
+### Generate Keypair
+
+```{eval-rst}
+.. opcmd:: generate pki wireguard key-pair
+
+   It generates the keypair, which includes the public and private parts.
+   The key is not stored on the system - only a keypair is generated.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ generate pki wireguard key-pair
+     Private key: iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=
+     Public key: EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=
+```
+
+```{eval-rst}
+.. opcmd:: generate pki wireguard key-pair install interface <interface>
+
+   Generates a keypair, which includes the public and private parts, and build
+   a configuration command to install this key to ``interface``.
+
+   .. code-block:: none
+
+      vyos@vyos:~$ generate pki wireguard key-pair install interface wg10
+      "generate" CLI command executed from operational level.
+      Generated private-key is not stored to CLI, use configure mode commands to install key:
+
+      set interfaces wireguard wg10 private-key '4Krkv8h6NkAYMMaBWI957yYDJDMvj9URTHstdlOcDU0='
+
+      Corresponding public-key to use on peer system is: 'UxDsYT6EnpTIOKUzvMlw2p0sNOKQvFxEdSVrnNrX1Ro='
+
+   .. note:: If this command is invoked from configure mode with the ``run``
+      prefix the key is automatically installed to the appropriate interface:
+
+      .. code-block:: none
+
+        vyos@vyos# run generate pki wireguard key-pair install interface wg10
+        "generate" CLI command executed from config session.
+        Generated private-key was imported to CLI!
+
+        Use the following command to verify: show interfaces wireguard wg10
+        Corresponding public-key to use on peer system is: '7d9KwabjLhHpJiEJeIGd0CBlao/eTwFOh6xyCovTfG8='
+
+        vyos@vyos# compare
+        [edit interfaces]
+        +wireguard wg10 {
+        +    private-key CJweb8FC6BU3Loj4PC2pn5V82cDjIPs7G1saW0ZfLWc=
+        +}
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireguard <interface> public-key
+
+   Retrieve public key portion from configured WIreGuard interface.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces wireguard wg01 public-key
+     EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=
+
+```
+
+#### Optional
+
+```{eval-rst}
+.. opcmd:: generate pki wireguard preshared-key
+
+   An additional layer of symmetric-key crypto can be used on top of the
+   asymmetric crypto.
+
+   This is optional.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ generate pki wireguard preshared-key
+     Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs=
+
+```
+
+```{eval-rst}
+.. opcmd:: generate pki wireguard preshared-key install interface <interface> peer <peer>
+
+   An additional layer of symmetric-key crypto can be used on top of the
+   asymmetric crypto. This command automatically creates for you the required
+   CLI command to install this PSK for a given peer.
+
+   This is optional.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ generate pki wireguard preshared-key install interface wg10 peer foo
+     "generate" CLI command executed from operational level.
+     Generated preshared-key is not stored to CLI, use configure mode commands to install key:
+
+     set interfaces wireguard wg10 peer foo preshared-key '32vQ1w1yFKTna8n7Gu7EimubSe2Y63m8bafz55EG3Ro='
+
+     Pre-shared key: +LuaZ8W6DjsDFJFX3jJzoNqrsXHhvq08JztM9z8LHCs=
+
+
+   .. note:: If this command is invoked from configure mode with the ``run``
+      prefix the key is automatically installed to the appropriate interface:
+
+```
+
+## Interface configuration
+
+The next step is to configure your local side as well as the policy based
+trusted destination addresses. If you only initiate a connection, the listen
+port and address/port is optional; however, if you act like a server and
+endpoints initiate the connections to your system, you need to define a port
+your clients can connect to, otherwise the port is randomly chosen and may
+make connection difficult with firewall rules, since the port may be different
+each time the system is rebooted.
+
+You will also need the public key of your peer as well as the network(s) you
+want to tunnel (allowed-ips) to configure a WireGuard tunnel. The public key
+below is always the public key from your peer, not your local one.
+
+**local side - commands**
+
+- WireGuard interface itself uses address 10.1.0.1/30
+- We only allow the 192.168.2.0/24 subnet to travel over the tunnel
+- Our remote end of the tunnel for peer `to-wg02` is reachable at 192.0.2.1
+  port 51820
+- The remote peer `to-wg02` uses XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=
+  as its public key portion
+- We listen on port 51820
+- We route all traffic for the 192.168.2.0/24 network to interface `wg01`
+
+```none
+set interfaces wireguard wg01 address '10.1.0.1/30'
+set interfaces wireguard wg01 description 'VPN-to-wg02'
+set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24'
+set interfaces wireguard wg01 peer to-wg02 address '192.0.2.1'
+set interfaces wireguard wg01 peer to-wg02 port '51820'
+set interfaces wireguard wg01 peer to-wg02 public-key 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI='
+set interfaces wireguard wg01 port '51820'
+
+set protocols static route 192.168.2.0/24 interface wg01
+```
+
+The last step is to define an interface route for 192.168.2.0/24 to get through
+the WireGuard interface `wg01`. Multiple IPs or networks can be defined and
+routed. The last check is allowed-ips which either prevents or allows the
+traffic.
+
+:::{warning}
+You can not assign the same allowed-ips statement to multiple
+WireGuard peers. This a design decision. For more information please
+check the [WireGuard mailing list].
+:::
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireguard <interface> private-key <private-key>
+
+  Associates the previously generated private key to a specific WireGuard
+  interface. The private key can be generate via the command
+
+  {opcmd}`generate pki wireguard key-pair`.
+
+  .. code-block:: none
+
+    set interfaces wireguard wg01 private-key 'iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY='
+
+  The command {opcmd}`show interfaces wireguard wg01 public-key` will then show the
+  public key, which needs to be shared with the peer.
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-per-client-thread.txt
+   :var0: wireguard
+   :var1: wg01
+```
+
+**remote side - commands**
+
+```none
+set interfaces wireguard wg01 address '10.1.0.2/30'
+set interfaces wireguard wg01 description 'VPN-to-wg01'
+set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24'
+set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2'
+set interfaces wireguard wg01 peer to-wg01 port '51820'
+set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw='
+set interfaces wireguard wg01 port '51820'
+set interfaces wireguard wg01 private-key 'OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU='
+
+set protocols static route 192.168.1.0/24 interface wg01
+```
+
+## Firewall Exceptions
+
+For the WireGuard traffic to pass through the WAN interface, you must create a
+firewall exception.
+
+```none
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related'
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp
+```
+
+You should also ensure that the OUTISDE_LOCAL firewall group is applied to the
+WAN interface and in an input (local) direction.
+
+```none
+set firewall ipv4 input filter rule 10 action jump
+set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL'
+set firewall ipv4 input filter rule 10 inbound-interface name 'eth0'
+```
+
+Assure that your firewall rules allow the traffic, in which case you have a
+working VPN using WireGuard.
+
+```none
+wg01# ping 192.168.1.1
+PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data.
+64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms
+64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms
+
+wg02# ping 192.168.2.1
+PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data.
+64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms
+64 bytes from 192.168.2.1: icmp_seq=2 ttl=64 time=1.02 ms
+```
+
+An additional layer of symmetric-key crypto can be used on top of the
+asymmetric crypto. This is optional.
+
+```none
+vyos@vyos:~$ generate pki wireguard preshared-key
+Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=
+```
+
+Copy the key, as it is not stored on the local filesystem. Because it
+is a symmetric key, only you and your peer should have knowledge of
+its content. Make sure you distribute the key in a safe manner,
+
+```none
+wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc='
+wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc='
+```
+
+## Remote Access "RoadWarrior" Example
+
+With WireGuard, a Road Warrior VPN config is similar to a site-to-site
+VPN. It just lacks the `address` and `port` statements.
+
+In the following example, the IPs for the remote clients are defined in
+the peers. This allows the peers to interact with one another. In
+comparison to the site-to-site example the `persistent-keepalive`
+flag is set to 15 seconds to assure the connection is kept alive.
+This is mainly relevant if one of the peers is behind NAT and can't
+be connected to if the connection is lost. To be effective this
+value needs to be lower than the UDP timeout.
+
+```none
+wireguard wg01 {
+    address 10.172.24.1/24
+    address 2001:db8:470:22::1/64
+    description RoadWarrior
+    peer MacBook {
+        allowed-ips 10.172.24.30/32
+        allowed-ips 2001:db8:470:22::30/128
+        persistent-keepalive 15
+        public-key F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc=
+    }
+    peer iPhone {
+        allowed-ips 10.172.24.20/32
+        allowed-ips 2001:db8:470:22::20/128
+        persistent-keepalive 15
+        public-key BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00=
+    }
+    port 2224
+    private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=
+}
+```
+
+The following is the config for the iPhone peer above. It's important to
+note that the `AllowedIPs` wildcard setting directs all IPv4 and IPv6 traffic
+through the connection.
+
+```none
+[Interface]
+PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf=
+Address = 10.172.24.20/24, 2001:db8:470:22::20/64
+DNS = 10.0.0.53, 10.0.0.54
+
+[Peer]
+PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc=
+AllowedIPs = 0.0.0.0/0, ::/0
+Endpoint = 192.0.2.1:2224
+PersistentKeepalive = 25
+```
+
+However, split-tunneling can be achieved by specifying the remote subnets.
+This ensures that only traffic destined for the remote site is sent over the
+tunnel. All other traffic is unaffected.
+
+```none
+[Interface]
+PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go=
+Address = 10.172.24.30/24, 2001:db8:470:22::30/64
+
+[Peer]
+PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc=
+AllowedIPs = 10.172.24.30/24, 2001:db8:470:22::/64
+Endpoint = 192.0.2.1:2224
+PersistentKeepalive = 25
+```
+
+## Operational Commands
+
+### Status
+
+```{eval-rst}
+.. opcmd:: show interfaces wireguard wg01 summary
+
+  Show info about the Wireguard service.
+  It also shows the latest handshake.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wireguard wg01 summary
+    interface: wg01
+      public key:
+      private key: (hidden)
+      listening port: 51820
+
+    peer: <peer public-key>
+      endpoint: <peer public IP>
+      allowed ips: 10.69.69.2/32
+      latest handshake: 23 hours, 45 minutes, 26 seconds ago
+      transfer: 1.26 MiB received, 6.47 MiB sent
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireguard
+
+  Get a list of all wireguard interfaces
+
+  .. code-block:: none
+
+    Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+    Interface        IP Address                        S/L  Description
+    ---------        ----------                        ---  -----------
+    wg01             10.0.0.1/24                       u/u
+
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireguard <interface>
+
+  Show general information about specific WireGuard interface
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wireguard wg01
+    interface: wg01
+      address: 10.0.0.1/24
+      public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE=
+      private key: (hidden)
+      listening port: 41751
+
+        RX:  bytes  packets  errors  dropped  overrun       mcast
+                 0        0       0        0        0           0
+        TX:  bytes  packets  errors  dropped  carrier  collisions
+                 0        0       0        0        0           0
+```
+
+## Remote Access "RoadWarrior" clients
+
+Some users tend to connect their mobile devices using WireGuard to their VyOS
+router. To ease deployment one can generate a "per mobile" configuration from
+the VyOS CLI.
+
+:::{warning}
+From a security perspective, it is not recommended to let a third
+party create and share the private key for a secured connection.
+You should create the private portion on your own and only hand out the
+public key. Please keep this in mind when using this convenience feature.
+:::
+
+```{eval-rst}
+.. opcmd:: generate wireguard client-config <name> interface <interface> server
+   <ip|fqdn> address <client-ip>
+
+  Using this command, you will create a new client configuration which can
+  connect to ``interface`` on this router. The public key from the specified
+  interface is automatically extracted and embedded into the configuration.
+
+  The command also generates a configuration snipped which can be copy/pasted
+  into the VyOS CLI if needed. The supplied ``<name>`` on the CLI will become
+  the peer name in the snippet.
+
+  In addition you will specifiy the IP address or FQDN for the client where it
+  will connect to. The address parameter can be used up to two times and is used
+  to assign the clients specific IPv4 (/32) or IPv6 (/128) address.
+
+  .. figure:: /_static/images/wireguard_qrcode.jpg
+     :alt: WireGuard Client QR code
+```
+
+
+
+[wireguard mailing list]: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html
diff --git a/docs/configuration/interfaces/wireless.md b/docs/configuration/interfaces/wireless.md
new file mode 100644
index 00000000..c8273737
--- /dev/null
+++ b/docs/configuration/interfaces/wireless.md
@@ -0,0 +1,698 @@
+---
+lastproofread: '2023-01-26'
+---
+
+(wireless-interface)=
+
+# WLAN/WIFI - Wireless LAN
+
+{abbr}`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless
+support (commonly referred to as Wi-Fi) by means of compatible hardware. If your
+hardware supports it, VyOS supports multiple logical wireless interfaces per
+physical device.
+
+There are three modes of operation for a wireless interface:
+
+- {abbr}`WAP (Wireless Access-Point)` provides network access to connecting
+  stations if the physical hardware supports acting as a WAP
+- A station acts as a Wi-Fi client accessing the network through an available
+  WAP
+- Monitor, the system passively monitors any kind of wireless traffic
+
+If the system detects an unconfigured wireless device, it will be automatically
+added the configuration tree, specifying any detected settings (for example,
+its MAC address) and configured to run in monitor mode.
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: wireless
+   :var1: wlan0
+```
+
+### Wireless options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> channel <number>
+
+  Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n) channels range from
+  1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 173
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> country-code <cc>
+
+  Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed
+  to indicate country in which device is operating. This can limit available
+  channels and transmit power.
+
+  .. note:: This option is mandatory in Access-Point mode.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> disable-broadcast-ssid
+
+  Send empty SSID in beacons and ignore probe request frames that do not specify
+  full SSID, i.e., require stations to know SSID.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> expunge-failing-stations
+
+  Disassociate stations based on excessive transmission failures or other
+  indications of connection loss.
+
+  This depends on the driver capabilities and may not be available with all
+  drivers.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> isolate-stations
+
+  Client isolation can be used to prevent low-level bridging of frames between
+  associated stations in the BSS.
+
+  By default, this bridging is allowed.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> max-stations
+
+  Maximum number of stations allowed in station table. New stations will be
+  rejected after the station table is full. IEEE 802.11 has a limit of 2007
+  different association IDs, so this number should not be larger than that.
+
+  This defaults to 2007.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> mgmt-frame-protection
+
+  Management Frame Protection (MFP) according to IEEE 802.11w
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> mode <a | b | g | n | ac>
+
+  Operation mode of wireless radio.
+
+  * ``a`` - 802.11a - 54 Mbits/sec
+  * ``b`` - 802.11b - 11 Mbits/sec
+  * ``g`` - 802.11g - 54 Mbits/sec (default)
+  * ``n`` - 802.11n - 600 Mbits/sec
+  * ``ac`` - 802.11ac - 1300 Mbits/sec
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> physical-device <device>
+
+  Wireless hardware device used as underlay radio.
+
+  This defaults to phy0.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> reduce-transmit-power <number>
+
+  Add Power Constraint element to Beacon and Probe Response frames.
+
+  This option adds Power Constraint element when applicable and Country element
+  is added. Power Constraint element is required by Transmit Power Control.
+
+  Valid values are 0..255.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> ssid <ssid>
+
+  SSID to be used in IEEE 802.11 management frames
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> type
+   <access-point | station | monitor>
+
+  Wireless device type for this interface
+
+  * ``access-point`` - Access-point forwards packets between other nodes
+  * ``station`` - Connects to another access point
+  * ``monitor`` - Passively monitor all packets on the frequency/channel
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-per-client-thread.txt
+   :var0: wireless
+   :var1: wlan0
+```
+
+#### PPDU
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities require-ht
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities require-hvt
+```
+
+##### HT (High Throughput) capabilities (802.11n)
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht 40mhz-incapable
+
+  Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]``
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht auto-powersave
+
+  WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD]
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht
+   channel-set-width <ht20 | ht40+ | ht40->
+
+  Supported channel width set.
+
+  * ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary
+    channel
+  * ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary
+    channel
+
+  .. note:: There are limits on which channels can be used with HT40- and HT40+.
+    Following table shows the channels that may be available for HT40- and HT40+
+    use per IEEE 802.11n Annex J:
+
+    Depending on the location, not all of these channels may be available for
+    use!
+
+    .. code-block:: none
+
+      freq              HT40-           HT40+
+      2.4 GHz           5-13            1-7 (1-9 in Europe/Japan)
+      5 GHz             40,48,56,64     36,44,52,60
+
+  .. note:: 40 MHz channels may switch their primary and secondary channels if
+    needed or creation of 40 MHz channel maybe rejected based on overlapping
+    BSSes. These changes are done automatically when hostapd is setting up the
+    40 MHz channel.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht
+   delayed-block-ack
+
+  Enable HT-delayed Block Ack ``[DELAYED-BA]``
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht dsss-cck-40
+
+  DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]``
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht greenfield
+
+  This enables the greenfield option which sets the ``[GF]`` option
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht ldpc
+
+  Enable LDPC coding capability
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht lsig-protection
+
+  Enable L-SIG TXOP protection capability
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht max-amsdu
+   <3839 | 7935>
+
+  Maximum A-MSDU length 3839 (default) or 7935 octets
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht
+   short-gi <20 | 40>
+
+  Short GI capabilities for 20 and 40 MHz
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht
+   smps <static | dynamic>
+
+  Spatial Multiplexing Power Save (SMPS) settings
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc rx <num>
+
+  Enable receiving PPDU using STBC (Space Time Block Coding)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc tx
+
+  Enable sending PPDU using STBC (Space Time Block Coding)
+```
+
+##### VHT (Very High Throughput) capabilities (802.11ac)
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count
+
+  Number of antennas on this card
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   antenna-pattern-fixed
+
+  Set if antenna pattern does not change during the lifetime of an association
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht beamform
+  <single-user-beamformer | single-user-beamformee | multi-user-beamformer |
+  multi-user-beamformee>
+
+  Beamforming capabilities:
+
+  * ``single-user-beamformer`` - Support for operation as single user beamformer
+  * ``single-user-beamformee`` - Support for operation as single user beamformee
+  * ``multi-user-beamformer`` - Support for operation as single user beamformer
+  * ``multi-user-beamformee`` - Support for operation as single user beamformer
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   center-channel-freq <freq-1 | freq-2> <number>
+
+  VHT operating channel center frequency - center freq 1
+  (for use with 80, 80+80 and 160 modes)
+
+  VHT operating channel center frequency - center freq 2
+  (for use with the 80+80 mode)
+
+  <number> must be from 34 - 173. For 80 MHz channels it should be channel + 6.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   channel-set-width <0 | 1 | 2 | 3>
+
+   * ``0`` - 20 or 40 MHz channel width (default)
+   * ``1`` - 80 MHz channel width
+   * ``2`` - 160 MHz channel width
+   * ``3`` - 80+80 MHz channel width
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht ldpc
+
+  Enable LDPC (Low Density Parity Check) coding capability
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht link-adaptation
+
+  VHT link adaptation capabilities
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   max-mpdu <value>
+
+  Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   max-mpdu-exp <value>
+
+  Set the maximum length of A-MPDU pre-EOF padding that the station can receive
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   short-gi <80 | 160>
+
+  Short GI capabilities
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc rx <num>
+
+  Enable receiving PPDU using STBC (Space Time Block Coding)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc tx
+
+  Enable sending PPDU using STBC (Space Time Block Coding)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht tx-powersave
+
+  Enable VHT TXOP Power Save Mode
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht vht-cf
+
+  Station supports receiving VHT variant HT Control field
+```
+
+### Wireless options (Station/Client)
+
+The example creates a wireless station (commonly referred to as Wi-Fi client)
+that accesses the network through the WAP defined in the above example. The
+default physical device (`phy0`) is used.
+
+```none
+set interfaces wireless wlan0 type station
+set interfaces wireless wlan0 address dhcp
+set interfaces wireless wlan0 country-code de
+set interfaces wireless wlan0 ssid Test
+set interfaces wireless wlan0 security wpa passphrase '12345678'
+```
+
+Resulting in
+
+```none
+interfaces {
+  [...]
+  wireless wlan0 {
+    address dhcp
+    country-code de
+    security {
+      wpa {
+        passphrase "12345678"
+      }
+    }
+    ssid TEST
+    type station
+  }
+```
+
+### Security
+
+{abbr}`WPA (Wi-Fi Protected Access)` and WPA2 Enterprise in combination with
+802.1x based authentication can be used to authenticate users or computers
+in a domain.
+
+The wireless client (supplicant) authenticates against the RADIUS server
+(authentication server) using an {abbr}`EAP (Extensible Authentication
+Protocol)` method configured on the RADIUS server. The WAP (also referred
+to as authenticator) role is to send all authentication messages between the
+supplicant and the configured authentication server, thus the RADIUS server
+is responsible for authenticating the users.
+
+The WAP in this example has the following characteristics:
+
+- IP address `192.168.2.1/24`
+- Network ID (SSID) `Enterprise-TEST`
+- WPA passphrase `12345678`
+- Use 802.11n protocol
+- Wireless channel `1`
+- RADIUS server at `192.168.3.10` with shared-secret `VyOSPassword`
+
+```none
+set interfaces wireless wlan0 address '192.168.2.1/24'
+set interfaces wireless wlan0 country-code de
+set interfaces wireless wlan0 type access-point
+set interfaces wireless wlan0 channel 1
+set interfaces wireless wlan0 mode n
+set interfaces wireless wlan0 ssid 'TEST'
+set interfaces wireless wlan0 security wpa mode wpa2
+set interfaces wireless wlan0 security wpa cipher CCMP
+set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword'
+set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812
+```
+
+Resulting in
+
+```none
+interfaces {
+  [...]
+  wireless wlan0 {
+        address 192.168.2.1/24
+        country-code de
+        channel 1
+        mode n
+        security {
+            wpa {
+                cipher CCMP
+                mode wpa2
+                radius {
+                    server 192.168.3.10 {
+                        key 'VyOSPassword'
+                        port 1812
+                    }
+                }
+            }
+        }
+        ssid "Enterprise-TEST"
+        type access-point
+    }
+}
+```
+
+### VLAN
+
+#### Regular VLANs (802.1q)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: wireless
+   :var1: wlan0
+```
+
+#### QinQ (802.1ad)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021ad.txt
+   :var0: wireless
+   :var1: wlan0
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless info
+```
+
+Use this command to view operational status and wireless-specific information
+about all wireless interfaces.
+
+```none
+vyos@vyos:~$ show interfaces wireless info
+Interface  Type          SSID                         Channel
+wlan0      access-point  VyOS-TEST-0                        1
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless detail
+```
+
+Use this command to view operational status and details wireless-specific
+information about all wireless interfaces.
+
+```none
+vyos@vyos:~$ show interfaces wireless detail
+wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+    link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff
+    inet xxx.xxx.99.254/24 scope global wlan0
+       valid_lft forever preferred_lft forever
+    inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link
+       valid_lft forever preferred_lft forever
+
+    RX:  bytes    packets     errors    dropped    overrun      mcast
+         66072        282          0          0          0          0
+    TX:  bytes    packets     errors    dropped    carrier collisions
+         83413        430          0          0          0          0
+
+wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+    link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff
+    inet xxx.xxx.100.254/24 scope global wlan0
+       valid_lft forever preferred_lft forever
+    inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link
+       valid_lft forever preferred_lft forever
+
+    RX:  bytes    packets     errors    dropped    overrun      mcast
+         166072      5282          0          0          0          0
+    TX:  bytes    packets     errors    dropped    carrier collisions
+         183413      5430          0          0          0          0
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless <wlanX>
+```
+
+This command shows both status and statistics on the specified wireless
+interface. The wireless interface identifier can range from wlan0 to wlan999.
+
+```none
+vyos@vyos:~$ show interfaces wireless wlan0
+wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+    link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff
+    inet xxx.xxx.99.254/24 scope global wlan0
+       valid_lft forever preferred_lft forever
+    inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link
+       valid_lft forever preferred_lft forever
+
+    RX:  bytes    packets     errors    dropped    overrun      mcast
+         66072        282          0          0          0          0
+    TX:  bytes    packets     errors    dropped    carrier collisions
+         83413        430          0          0          0          0
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless <wlanX> brief
+```
+
+This command gives a brief status overview of a specified wireless interface.
+The wireless interface identifier can range from wlan0 to wlan999.
+
+```none
+vyos@vyos:~$ show interfaces wireless wlan0 brief
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+wlan0            192.168.2.254/24                    u/u
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless <wlanX> queue
+```
+
+Use this command to view wireless interface queue information.
+The wireless interface identifier can range from wlan0 to wlan999.
+
+```none
+vyos@vyos:~$ show interfaces wireless wlan0 queue
+qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1
+ Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0)
+ rate 0bit 0pps backlog 0b 0p requeues 0
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless <wlanX> scan
+```
+
+This command is used to retrieve information about WAP within the range of your
+wireless interface. This command is useful on wireless interfaces configured
+in station mode.
+
+:::{note}
+Scanning is not supported on all wireless drivers and wireless
+hardware. Refer to your driver and wireless hardware documentation for
+further details.
+:::
+
+```none
+vyos@vyos:~$ show interfaces wireless wlan0 scan
+Address            SSID                          Channel  Signal (dbm)
+00:53:3b:88:6e:d8  WLAN-576405                         1  -64.00
+00:53:3b:88:6e:da  Telekom_FON                         1  -64.00
+00:53:00:f2:c2:a4  BabyView_F2C2A4                     6  -60.00
+00:53:3b:88:6e:d6  Telekom_FON                       100  -72.00
+00:53:3b:88:6e:d4  WLAN-576405                       100  -71.00
+00:53:44:a4:96:ec  KabelBox-4DC8                      56  -81.00
+00:53:d9:7a:67:c2  WLAN-741980                         1  -75.00
+00:53:7c:99:ce:76  Vodafone Homespot                   1  -86.00
+00:53:44:a4:97:21  KabelBox-4DC8                       1  -78.00
+00:53:44:a4:97:21  Vodafone Hotspot                    1  -79.00
+00:53:44:a4:97:21  Vodafone Homespot                   1  -79.00
+00:53:86:40:30:da  Telekom_FON                         1  -86.00
+00:53:7c:99:ce:76  Vodafone Hotspot                    1  -86.00
+00:53:44:46:d2:0b  Vodafone Hotspot                    1  -87.00
+```
+
+## Examples
+
+The following example creates a WAP. When configuring multiple WAP interfaces,
+you must specify unique IP addresses, channels, Network IDs commonly referred
+to as {abbr}`SSID (Service Set Identifier)`, and MAC addresses.
+
+The WAP in this example has the following characteristics:
+
+- IP address `192.168.2.1/24`
+- Network ID (SSID) `TEST`
+- WPA passphrase `12345678`
+- Use 802.11n protocol
+- Wireless channel `1`
+
+```none
+set interfaces wireless wlan0 address '192.168.2.1/24'
+set interfaces wireless wlan0 type access-point
+set interfaces wireless wlan0 channel 1
+set interfaces wireless wlan0 mode n
+set interfaces wireless wlan0 ssid 'TEST'
+set interfaces wireless wlan0 security wpa mode wpa2
+set interfaces wireless wlan0 security wpa cipher CCMP
+set interfaces wireless wlan0 security wpa passphrase '12345678'
+set interfaces wireless wlan0 country-code de
+```
+
+Resulting in
+
+```none
+interfaces {
+  [...]
+  wireless wlan0 {
+        address 192.168.2.1/24
+        channel 1
+        country-code de
+        mode n
+        security {
+            wpa {
+                cipher CCMP
+                mode wpa2
+                passphrase "12345678"
+            }
+        }
+        ssid "TEST"
+        type access-point
+    }
+}
+system {
+  [...]
+  wifi-regulatory-domain DE
+}
+```
+
+To get it to work as an access point with this configuration you will need
+to set up a DHCP server to work with that network. You can - of course - also
+bridge the Wireless interface with any configured bridge
+({ref}`bridge-interface`) on the system.
+
+(wireless-interface-intel-ax200)=
+
+### Intel AX200
+
+The Intel AX200 card does not work out of the box in AP mode, see
+<https://unix.stackexchange.com/questions/598275/intel-ax200-ap-mode>. You can
+still put this card into AP mode using the following configuration:
+
+
+```none
+set interfaces wireless wlan0 channel '1'
+set interfaces wireless wlan0 country-code 'us'
+set interfaces wireless wlan0 mode 'n'
+set interfaces wireless wlan0 physical-device 'phy0'
+set interfaces wireless wlan0 ssid 'VyOS'
+set interfaces wireless wlan0 type 'access-point'
+```
+
diff --git a/docs/configuration/interfaces/wwan.md b/docs/configuration/interfaces/wwan.md
new file mode 100644
index 00000000..ac096259
--- /dev/null
+++ b/docs/configuration/interfaces/wwan.md
@@ -0,0 +1,372 @@
+---
+lastproofread: '2023-01-27'
+---
+
+(wwan-interface)=
+
+# WWAN - Wireless Wide-Area-Network
+
+The Wireless Wide-Area-Network interface provides access (through a wireless
+modem/wwan) to wireless networks provided by various cellular providers.
+
+VyOS uses the `interfaces wwan` subsystem for configuration.
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-address-with-dhcp.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable-link-detect.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-mtu.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-ip.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-ipv6.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vrf.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+**DHCP(v6)**
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-dhcp-options.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-dhcpv6-options.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-dhcpv6-prefix-delegation.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+### WirelessModem (WWAN) options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wwan <interface> apn <apn>
+
+  Every WWAN connection requires an {abbr}`APN (Access Point Name)` which is
+  used by the client to dial into the ISPs network. This is a mandatory
+  parameter. Contact your Service Provider for correct APN.
+
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface>
+
+  Show detailed information on given `<interface>`
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0
+    wwan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000
+        link/ether 02:c2:f3:00:01:02 brd ff:ff:ff:ff:ff:ff
+        inet 10.155.144.12/30 brd 10.155.144.15 scope global dynamic wwan0
+           valid_lft 7012sec preferred_lft 7012sec
+        inet6 fe80::c2:f3ff:fe00:0102/64 scope link
+           valid_lft forever preferred_lft forever
+
+        RX:  bytes  packets  errors  dropped  overrun       mcast
+               640        2       0        0        0           0
+        TX:  bytes  packets  errors  dropped  carrier  collisions
+              3229       16       0        0        0           0
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> summary
+
+  Show detailed information summary on given `<interface>`
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0 summary
+      --------------------------------
+      General  |            dbus path: /org/freedesktop/ModemManager1/Modem/0
+               |            device id: 79f4e9cc2e9fc8d4a3b8c8f6327c2e363170194d
+      --------------------------------
+      Hardware |         manufacturer: Sierra Wireless, Incorporated
+               |                model: MC7710
+               |             revision: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15
+               |         h/w revision: 1.0
+               |            supported: gsm-umts, lte
+               |              current: gsm-umts, lte
+               |         equipment id: 358xxxxxxxxxxxx
+      --------------------------------
+      System   |               device: /sys/devices/pci0000:00/0000:00:13.0/usb3/3-1/3-1.3
+               |              drivers: qcserial, qmi_wwan
+               |               plugin: Generic
+               |         primary port: cdc-wdm0
+               |                ports: ttyUSB0 (qcdm), ttyUSB2 (at), cdc-wdm0 (qmi), wwan0 (net)
+      --------------------------------
+      Numbers  |                  own: 4917xxxxxxxx
+      --------------------------------
+      Status   |                 lock: sim-pin2
+               |       unlock retries: sim-pin (3), sim-pin2 (3), sim-puk (10), sim-puk2 (10)
+               |                state: connected
+               |          power state: on
+               |          access tech: lte
+               |       signal quality: 63% (recent)
+      --------------------------------
+      Modes    |            supported: allowed: 2g; preferred: none
+               |                       allowed: 3g; preferred: none
+               |                       allowed: 4g; preferred: none
+               |                       allowed: 2g, 3g; preferred: 3g
+               |                       allowed: 2g, 3g; preferred: 2g
+               |                       allowed: 2g, 4g; preferred: 4g
+               |                       allowed: 2g, 4g; preferred: 2g
+               |                       allowed: 3g, 4g; preferred: 3g
+               |                       allowed: 3g, 4g; preferred: 4g
+               |                       allowed: 2g, 3g, 4g; preferred: 4g
+               |                       allowed: 2g, 3g, 4g; preferred: 3g
+               |                       allowed: 2g, 3g, 4g; preferred: 2g
+               |              current: allowed: 2g, 3g, 4g; preferred: 2g
+      --------------------------------
+      Bands    |            supported: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3,
+               |                       eutran-7, eutran-8, eutran-20
+               |              current: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3,
+               |                       eutran-7, eutran-8, eutran-20
+      --------------------------------
+      IP       |            supported: ipv4, ipv6, ipv4v6
+      --------------------------------
+      3GPP     |                 imei: 358xxxxxxxxxxxx
+               |          operator id: 26201
+               |        operator name: Telekom.de
+               |         registration: home
+      --------------------------------
+      3GPP EPS | ue mode of operation: ps-1
+      --------------------------------
+      SIM      |            dbus path: /org/freedesktop/ModemManager1/SIM/0
+      --------------------------------
+      Bearer   |            dbus path: /org/freedesktop/ModemManager1/Bearer/0
+
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> capabilities
+
+  Show WWAN module hardware capabilities.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0 capabilities
+    Max TX channel rate: '50000000'
+    Max RX channel rate: '100000000'
+    Data Service: 'simultaneous-cs-ps'
+    SIM: 'supported'
+    Networks: 'gsm, umts, lte'
+    Bands: 'gsm-dcs-1800, gsm-900-extended, gsm-900-primary, gsm-pcs-1900, wcdma-2100, wcdma-900'
+    LTE bands: '1, 3, 7, 8, 20'
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> firmware
+
+  Show WWAN module firmware.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0 firmware
+    Model: MC7710
+    Boot version: SWI9200X_03.05.29.03bt r6485 CNSHZ-ED-XP0031 2014/12/02 17:33:08
+    AMSS version: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15
+    SKU ID: unknown
+    Package ID: unknown
+    Carrier ID: 0
+    Config version: unknown
+
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> imei
+
+  Show WWAN module IMEI.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0 imei
+    ESN: '0'
+    IMEI: '358xxxxxxxxxxxx'
+    MEID: 'unknown'
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> imsi
+
+  Show WWAN module IMSI.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0 imsi
+    IMSI: '262xxxxxxxxxxxx'
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> model
+
+  Show WWAN module model.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0 model
+    Model: 'MC7710'
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> msisdn
+
+  Show WWAN module MSISDN.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0 msisdn
+    MSISDN: '4917xxxxxxxx'
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> revision
+
+  Show WWAN module hardware revision.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0 revision
+    Revision: 'SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15'
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> signal
+
+  Show WWAN module signal strength.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0 signal
+    LTE:
+    RSSI: '-74 dBm'
+    RSRQ: '-7 dB'
+    RSRP: '-100 dBm'
+    SNR: '13.0 dB'
+    Radio Interface:   'lte'
+    Active Band Class: 'eutran-3'
+    Active Channel:    '1300'
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> sim
+
+  Show WWAN module SIM card information.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0 sim
+    Provisioning applications:
+    Primary GW:   slot '1', application '1'
+    Primary 1X:   session doesn't exist
+    Secondary GW: session doesn't exist
+    Secondary 1X: session doesn't exist
+    Slot [1]:
+    Card state: 'present'
+    UPIN state: 'not-initialized'
+    UPIN retries: '0'
+    UPUK retries: '0'
+    Application [1]:
+    Application type:  'usim (2)'
+    Application state: 'ready'
+    Application ID:
+    A0:00:00:00:87:10:02:FF:49:94:20:89:03:10:00:00
+    Personalization state: 'ready'
+    UPIN replaces PIN1: 'no'
+    PIN1 state: 'disabled'
+    PIN1 retries: '3'
+    PUK1 retries: '10'
+    PIN2 state: 'enabled-not-verified'
+    PIN2 retries: '3'
+    PUK2 retries: '10'
+```
+
+## 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`.
+
+```none
+set interfaces wwan wwan0 apn 'internet.telekom'
+set interfaces wwan wwan0 address 'dhcp'
+```
+
+## Supported Modules
+
+The following hardware modules have been tested successfully in an
+{ref}`pc-engines-apu4` board:
+
+- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE)
+- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE)
+- 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)
+- HP LT4120 Snapdragon X5 LTE
+
+## Firmware Update
+
+All available WWAN cards have a build in, reprogrammable firmware. Most of the
+vendors provide a regular update to the firmware used in the baseband chip.
+
+As VyOS makes use of the QMI interface to connect to the WWAN modem cards, also
+the firmware can be reprogrammed.
+
+To update the firmware, VyOS also ships the `qmi-firmware-update` binary. To
+upgrade the firmware of an e.g. Sierra Wireless MC7710 module to the firmware
+provided in the file `9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe`
+use the following command:
+
+```bash
+$ sudo qmi-firmware-update --update -d 1199:68a2 \
+   9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe
+```