GRE Tunnels
===========

Generic Routing Encapsulation (GRE) tunnels provide secure, encrypted connectivity between Cloudflare's edge and the on-premises pfSense router.

Overview
--------

Magic Transit uses GRE tunnels to forward clean traffic from Cloudflare's network to the origin infrastructure. All traffic is inspected and scrubbed at Cloudflare's edge before being encapsulated and sent through the tunnel.

Active Tunnels
--------------

IPv4 Primary Tunnel
~~~~~~~~~~~~~~~~~~~

**Tunnel Configuration**:

- **Name**: MT_GRE_1_TUNNELV4
- **Local Endpoint**: 198.51.100.1 (pfSense WAN example)
- **Remote Endpoint**: 203.0.113.5 (Cloudflare example)
- **Tunnel Interface**: gre0
- **MTU**: 1476 bytes

**IP Addressing**:

- **pfSense**: 198.51.100.1/31 (documentation example)
- **Cloudflare**: 198.51.100.0/31 (documentation example)
- **Network**: Point-to-point /31 subnet

**Health Monitoring**:

- **Monitor IP**: 198.51.100.0 (Cloudflare side example)
- **Source IP**: 198.51.100.1 (pfSense side example)
- **Latency**: 9.308ms average
- **Jitter**: 0.24ms
- **Packet Loss**: 0.0%
- **Status**: Online

IPv6 Tunnel
~~~~~~~~~~~

**Tunnel Configuration**:

- **Name**: MT_GRE_1_TUNNELV6
- **Status**: Online
- **Latency**: 9.343ms average
- **Jitter**: 0.276ms
- **Packet Loss**: 0.0%

**IP Addressing**:

- **pfSense**: fd00:abcd:7:0:a9fe:1b1c:0:3 (obfuscated example)
- **Cloudflare**: fd00:abcd:7:0:a9fe:1b1c:0:2 (obfuscated example)

Tunnel Configuration (pfSense)
-------------------------------

The GRE tunnel is configured on pfSense interface **gre0**:

.. code-block:: none

   Interface: gre0
   Type: GRE tunnel
   Local Address: 198.51.100.1
   Remote Address: 203.0.113.5
   Tunnel Source: 198.51.100.1
   Tunnel Destination: 198.51.100.0
   MTU: 1476
   Status: UP, RUNNING

Traffic Flow
------------

**Inbound (Internet → Origin)**:

1. Internet traffic destined for protected IPs
2. Anycast routing to nearest Cloudflare edge
3. DDoS scrubbing and security filtering
4. GRE encapsulation
5. Tunnel to pfSense (198.51.100.1)
6. pfSense decapsulation and routing to internal networks

**Outbound (Origin → Internet)**:

1. Traffic from internal networks
2. pfSense routing decision
3. GRE encapsulation (if policy requires)
4. Tunnel to Cloudflare
5. Cloudflare edge (203.0.113.5) processes and forwards to destination

Security Considerations
-----------------------

**Tunnel Security**:

- GRE provides encapsulation but not encryption
- IPsec can be layered over GRE for encryption if required
- Cloudflare's network provides DDoS protection upstream
- pfSense firewall rules control what traffic enters the tunnel

**Best Practices**:

- Monitor tunnel health continuously
- Configure automatic failover for tunnel failures
- Use IPsec encryption for sensitive traffic
- Implement strict firewall rules for tunnel endpoints

Troubleshooting
---------------

**Check Tunnel Status**:

.. code-block:: bash

   # On pfSense
   ifconfig gre0
   pfSsh.php playback gatewaystatus

**Common Issues**:

- **Tunnel Down**: Check WAN connectivity, verify remote endpoint reachability
- **High Latency**: Review Cloudflare edge routing, check WAN circuit performance
- **Packet Loss**: Investigate MTU issues, check for interface errors

**Health Check Verification**:

The gateway monitoring system continuously tests tunnel health by sending ICMP probes to the Cloudflare endpoint (198.51.100.0). Failures trigger automatic alerts and can initiate failover procedures.

Performance Monitoring
----------------------

Tunnel performance is monitored via pfSense gateway monitoring:

- **Latency**: Average round-trip time
- **Standard Deviation**: Jitter measurement
- **Packet Loss**: Percentage of lost probes
- **Status**: Online/Offline/Warning states

Current metrics show excellent tunnel performance with sub-10ms latency and zero packet loss.

Maintenance
-----------

**Routine Maintenance**:

- Monitor tunnel statistics daily
- Review gateway health checks weekly
- Test failover procedures monthly
- Verify Cloudflare configuration quarterly

**Change Management**:

Changes to tunnel configuration should be coordinated with Cloudflare support to ensure continuous service availability.