2 files changed, 52 insertions, 15 deletions
diff --git a/docs/configuration/interfaces/macsec.rst b/docs/configuration/interfaces/macsec.rst
index 0c0c052b..1ab7f361 100644
--- a/docs/configuration/interfaces/macsec.rst
+++ b/docs/configuration/interfaces/macsec.rst
@@ -236,4 +236,50 @@ the unencrypted but authenticated content.
   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'
-\ No newline at end of file
+  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**
+
+.. code-block:: 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**
+
+.. code-block:: 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/vxlan.rst b/docs/configuration/interfaces/vxlan.rst
index af00fdec..831870c5 100644
--- a/docs/configuration/interfaces/vxlan.rst
+++ b/docs/configuration/interfaces/vxlan.rst
@@ -31,10 +31,6 @@ 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.
 
-.. note:: As VyOS is based on Linux and there was no official IANA port assigned
-   for VXLAN, VyOS uses a default port of 8472. You can change the port on a
-   per VXLAN interface basis to get it working across multiple vendors.
-
 Configuration
 =============
 
@@ -58,11 +54,7 @@ VXLAN specific options
 
   Configure port number of remote VXLAN endpoint.
 
-  .. note:: As VyOS is Linux based the default port used is not using 4789
-     as the default IANA-assigned destination UDP port number. Instead VyOS
-     uses the Linux default port of 8472.
-
-.. cfgcmd:: set interfaces vxlan <interface> source-address <interface>
+.. 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.
@@ -331,10 +323,9 @@ multicast-address.
 
   set interfaces vxlan vxlan241 port 12345
 
-The destination port used for creating a VXLAN interface in Linux defaults to
-its pre-standard value of 8472 to preserve backward compatibility. A
-configuration directive to support a user-specified destination port to override
-that behavior is available using the above command.
+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
 =============
@@ -354,5 +345,5 @@ set directly. Let's change the Multicast example from above:
   # leaf3
   set interface vxlan vxlan241 remote 10.1.2.2
 
-The default port udp is set to 8472.
+The default port udp is set to 4789.
 It can be changed with ``set interface vxlan <vxlanN> port <port>``