add troubleshooting section to gre

1 files changed, 65 insertions, 4 deletions

diff --git a/docs/interfaces/tunnel.rst b/docs/interfaces/tunnel.rst
index 8fa1c0d7..1f191c16 100644
--- a/docs/interfaces/tunnel.rst
+++ b/docs/interfaces/tunnel.rst
@@ -6,9 +6,19 @@ Tunnel Interfaces
 Generic Routing Encapsulation (GRE)
 -----------------------------------
 
-A GRE tunnel requires a tunnel source (local-ip), a tunnel destination (remote-ip), 
+A GRE tunnel operates at layer 3 of the OSI model and is repsented by IP protocol 47.  The 
+main benefit of a GRE tunnel is that you are able to route traffic across disparate networks.  
+GRE also supports multicast traffic and supports routing protocols that leverage multicast to 
+form neighbor adjacencies.
+
+Configuration
+^^^^^^^^^^^^^
+
+A basic configuration requires a tunnel source (local-ip), a tunnel destination (remote-ip), 
 an encapsulation type (gre), and an address (ipv4/ipv6).  Below is a configuration example 
-taken from a VyOS router and a Cisco IOS router.
+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:**
 
@@ -28,9 +38,60 @@ taken from a VyOS router and a Cisco IOS router.
   tunnel source 198.18.2.2
   tunnel destination 198.18.0.2
 
-The main difference between these two configurations is that VyOS requires you explicitly 
-configure your encapsulation type.  The Cisco router defaults to 'gre ip'.
+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/desintation traffic.
+
+**1. Confirm IP connectivity between tunnel local-ip and remote-ip:**
+
+.. code-block:: sh
+
+  vyos@vyos:~$ ping 198.18.2.2 interface 198.18.0.2 count 4
+  PING 198.18.2.2 (198.18.2.2) from 198.18.0.2 : 56(84) bytes of data.
+  64 bytes from 198.18.2.2: icmp_seq=1 ttl=254 time=0.807 ms
+  64 bytes from 198.18.2.2: icmp_seq=2 ttl=254 time=1.50 ms
+  64 bytes from 198.18.2.2: icmp_seq=3 ttl=254 time=0.624 ms
+  64 bytes from 198.18.2.2: icmp_seq=4 ttl=254 time=1.41 ms
+
+  --- 198.18.2.2 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:**
+
+.. code-block:: sh
+
+  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.18.0.2 peer 198.18.2.2
+    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:**
+
+.. code-block:: sh
+
+  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
 
 Virtual Tunnel Interface (VTI)
 ------------------------------