GRE Tunnels

The GRE module connects the Virtual Router to a remote IPv4 router through a GRE tunnel. It uses source-based routing to send traffic from selected virtual networks through the remote router, for example when an upstream provider routes a public address block to your OpenNebula network over GRE.

The module manages one tunnel per Virtual Router instance and integrates with Keepalived failover. It is disabled by default. Use a VR appliance image that includes the GRE module.

Quick Start

Network Requirements

The two routers need reachable outer endpoints on the transport network and a separate pair of inner addresses for the tunnel. The inner subnet does not require an additional OpenNebula NIC or virtual network.

This example uses the following addresses. Replace the documentation addresses with your own:

Address	Virtual Router	Remote router
Outer endpoint	192.0.2.10	192.0.2.20
Inner tunnel address	172.31.160.66/30	172.31.160.65/30

The source network behind the VR is 198.51.100.0/24. Its VMs use the VR as their gateway.

VMs: 198.51.100.0/24
          |
    Virtual Router                  Remote router
    outer: 192.0.2.10               outer: 192.0.2.20
    inner: 172.31.160.66 === GRE === inner: 172.31.160.65
                                           |
                                    Upstream network

Allow GRE (IP protocol 47, not a TCP or UDP port) between the outer endpoints in the relevant firewalls and security groups. The local outer address must be available on the active VR, and the remote outer endpoint must be reachable through the transport network. If the transport path uses NAT, it must support GRE and the remote endpoint configuration must account for the translated address.

GRE provides encapsulation without encryption. For an encrypted VPN, see WireGuard.

Virtual Router Configuration

Add the following attributes to the CONTEXT section of the associated VM template:

CONTEXT = [
  ...
  ONEAPP_VNF_ROUTER4_ENABLED = "YES",
  ONEAPP_VNF_GRE_ENABLED    = "YES",
  ONEAPP_VNF_GRE_INTERFACE  = "gre1",
  ONEAPP_VNF_GRE_LOCAL      = "192.0.2.10",
  ONEAPP_VNF_GRE_REMOTE     = "192.0.2.20",
  ONEAPP_VNF_GRE_ADDRESS    = "172.31.160.66/30",
  ONEAPP_VNF_GRE_GATEWAY    = "172.31.160.65",
  ONEAPP_VNF_GRE_NETWORKS   = "198.51.100.0/24",
  ONEAPP_VNF_GRE_TTL        = "255",
  ...
]

Router4 must enable forwarding on the NICs carrying routed traffic. If you restrict ONEAPP_VNF_ROUTER4_INTERFACES, include the required NICs. GRE enables forwarding on its own tunnel interface after creating it.

[!IMPORTANT] ONEAPP_VNF_GRE_NETWORKS selects source networks, not remote destination networks. The module does not assign these networks to NICs, configure VM gateways, or create return routes on the remote router.

Remote Router Configuration

Configure a matching unkeyed IPv4 GRE tunnel on the remote router, with the outer endpoints reversed and 172.31.160.65/30 as its inner address. Add a return route for 198.51.100.0/24 through 172.31.160.66.

For a Linux peer, run as root, using an unused interface name:

ip tunnel add gre1 mode gre local 192.0.2.20 remote 192.0.2.10 ttl 255
ip address add 172.31.160.65/30 dev gre1
ip link set gre1 up
ip route replace 198.51.100.0/24 via 172.31.160.66 dev gre1

These commands configure the peer temporarily; make the configuration persistent using the peer's network management tools. Enable IPv4 forwarding and allow forwarded traffic on the peer as appropriate for its network configuration. Its upstream network must also provide the required return routing, or NAT if your deployment uses private addresses.

Routing and Failover

The module uses routing table 10000. For each configured source prefix, it installs a policy rule selecting that table. The table contains a default route through the remote inner gateway and a throw route for each configured source prefix. A throw route lets traffic destined for those prefixes continue to later routing rules, normally reaching the main routing table. See the Linux routing reference for this behavior.

Traffic from other sources continues to follow its existing routing policy. The main default route is unchanged. Source networks must remain reachable through the VR's normal routes, and the outer endpoint route must not recurse through the GRE tunnel.

The module owns table 10000 and the configured tunnel interface. Starting or stopping it clears that table and its associated policy rules; starting it recreates the tunnel. Do not share those resources with manually configured routing.

The failover service starts one-gre on the active instance when GRE is enabled and stops it on backup instances. Startup is ordered after sysctl and Router4 when they start together. In an HA deployment, ensure the configured local outer endpoint is available on the active instance, for example through an appropriately configured floating address, and that the remote peer can reach it after failover.

Context Configuration Attributes

Parameter	Default	Description
ONEAPP_VNF_GRE_ENABLED	NO	Enable or disable GRE (YES/NO).
ONEAPP_VNF_GRE_INTERFACE	gre1	Tunnel interface name, 1–15 ASCII characters. Start with a letter, digit, or underscore; remaining characters may also include dots and hyphens. all, default, and gre0 are reserved.
ONEAPP_VNF_GRE_LOCAL	—	Required when enabled. Local outer IPv4 address, without a prefix.
ONEAPP_VNF_GRE_REMOTE	—	Required when enabled. Remote outer IPv4 address, without a prefix.
ONEAPP_VNF_GRE_ADDRESS	—	Required when enabled. Local inner IPv4 address with a numeric CIDR prefix, such as 172.31.160.66/30.
ONEAPP_VNF_GRE_GATEWAY	—	Required when enabled. Remote inner IPv4 gateway, without a prefix. Use a gateway reachable on the tunnel subnet.
ONEAPP_VNF_GRE_NETWORKS	—	Required when enabled. Source IPv4 prefixes separated by whitespace, commas, or semicolons. Host bits are normalized and duplicate prefixes removed.
ONEAPP_VNF_GRE_TTL	255	Outer packet TTL, an integer from 1 to 255.

Use numeric prefixes such as /24; dotted netmasks such as /255.255.255.0 are not accepted. This module does not expose IPv6 tunnels, GRE keys, or multiple tunnel configurations.

For multiple source networks:

ONEAPP_VNF_GRE_NETWORKS = "198.51.100.0/24, 203.0.113.0/24"

Verification and Troubleshooting

Run these commands as root on the active VR, adjusting the interface name if necessary:

rc-service one-gre status
ip tunnel show gre1
ip -4 address show dev gre1
sysctl net/ipv4/conf/gre1/forwarding
ip -4 rule show
ip -4 route show table 10000
ping -c 3 -I gre1 172.31.160.65

For the example configuration, table 10000 should contain:

throw 198.51.100.0/24
default via 172.31.160.65 dev gre1

Test traffic from a VM in the configured source network as well: a ping from the VR's tunnel address alone does not exercise source-based forwarding. If the tunnel is up but traffic fails, check protocol 47 filtering, peer return routes, forwarding on both routers, and any NAT or reverse-path filtering rules. If small packets work but larger transfers stall, check the transport MTU and path MTU discovery.

Inspect service errors with:

tail -n 100 /var/log/one-appliance/one-gre.log

one-gre is a one-shot service: a started state means setup completed, not that the peer is reachable. See OpenRC Services for lifecycle and contextualization details.