User Tools

Site Tools


docs:guide-user:network:tunneling_interface_protocols

Tunnelling interface protocols

This page describes all available tunnelling protocol usable in /etc/config/network and their options. Some example configurations are provided at the end of the page.

Note that, for most protocols, installing an opkg package is required for protocol support.

Most OpenWrt protocol handlers add a protocol-specific prefix to the UCI interface names. There is a default 15-character limit for interface names in the Linux kernel.

With prefixes seen at least as long as gre4t- and allowing possibility of using .VLAN notation, declared names should be kept under four (4) characters.

abcd.NNNNgre4t-abcd.NNNN (15 characters)

Protocol "pptp" (Point-to-Point Tunneling Protocol)

:!: The package pptp must be installed to use PPtP. You need to have another section to configure the “parent” device, and you might need to add “<vpn>” to your “wan” zone in the firewall (<vpn> being the “logical interface name” of this section).

Name Type Required Default Description
server ip address yes (none) Remote PPtP server
username string no(?) (none) Username for PAP/CHAP authentication
password string no(?) (none) Password for PAP/CHAP authentication
buffering boolean no 1 Enables buffering and reordering of packets, 0 disables it (–nobuffer) pptp buffering option removed in r32482
keepalive integer no ? Number of attempts to reconnect
defaultroute boolean no 1 Whether to create a default route over the tunnel
peerdns boolean no 1 Use PPTP-provided DNS server(s)
delegate boolean no ? Use builtin IPv6-management
iface string no(?) pptp-<vpn> Name of the physical interface. Defaults to pptp-<vpn> no matter what you use

Protocol "relay" (Relayd Pseudo Bridge)

:!: The package relayd must be installed to use this protocol.

Name Type Required Default Description
network list of logical interface names yes (none) Specifies the networks between which traffic is relayed
gateway IPv4 address no (network default) Override the gateway address sent to clients within DHCP responses
expiry integer no 30 Host expiry timeout in seconds
retry integer no 5 Number of ARP ping retries before a host is considered dead
table integer no 16800 Table ID for automatically added routes
forward_bcast boolean no 1 Enables forwarding of broadcast traffic, 0 disables it
forward_dhcp boolean no 1 Enables forwarding of DHCP requests and responses, 0 disables it

Common options for GRE protocols

:!: The package gre must be installed to use GRE. Additionally, you need kmod-gre and/or kmod-gre6.

GRE support has been introduced in Barrier Breaker. Four protocols are defined (“gre”, “gretap”, grev6“, and “grev6tap”), which will generate GRE interfaces named:

Protocol GRE type Interface name
gre IPv4 GRE gre4-<logical interface name>
gretap GRE-TAP IPv4 gre4t-<logical interface name>
grev6 GRE IPv6 gre6-<logical interface name>
grev6tap GRE-TAP IPv6 gre6t-<logical interface name>

All four protocols accept the following common options:

Name Type Required Default Description
mtu integer no 1280 MTU
ttl integer no 64 TTL of the encapsulating packets
tunlink logical interface name no (none) Bind the tunnel to this interface (dev option of “ip tunnel”)
zone zone name no “wan” Firewall zone to which the interface will be added
tos string no (none) Type of Service (IPv4), Traffic Class (IPv6): either “inherit” (the outer header inherits the value of the inner header) or an hexadecimal value (Chaos Calmer and later only)
ikey integer no 0 key for incoming packets
okey integer no 0 key for outgoing packets
icsum boolean no false require incoming checksum
ocsum boolean no false compute outgoing checksum
iseqno boolean no false require incoming packets serialization
oseqno boolean no false perform outgoing packets serialization

Protocol "gre" (GRE tunnel over IPv4)

The following options are supported, in addition to all common options above:

Name Type Required Default Description
ipaddr IPv4 address no WAN IP Local endpoint
peeraddr IPv4 address yes (none) Remote endpoint
df boolean no true Set “Don't Fragment” flag on encapsulating packets

Protocol "gretap" (Ethernet GRE tunnel over IPv4)

The following options are supported, in addition to all common options above:

Name Type Required Default Description
ipaddr IPv4 address no WAN IP Local endpoint
peeraddr IPv4 address yes (none) Remote endpoint
df boolean no true Set “Don't Fragment” flag on encapsulating packets
network logical interface name no (none) Logical network to which the tunnel will be added (bridged)

ipaddr may be required in some setups. Repeated log entries about “setting up now” and “now down” may be related to this.

Additionally, the resolveip package may also be needed. ./gre.sh: eval: line 1: resolveip: not found in the logs are an indication of the need.

Protocol "grev6" (GRE tunnel over IPv6)

The following options are supported, in addition to all common options above:

Name Type Required Default Description
ip6addr IPv6 address no WAN IP Local endpoint
peer6addr IPv6 address yes (none) Remote endpoint
weakif logical interface name no lan Logical network from which to select the local endpoint if ip6addr parameter is empty and no WAN IP is available

Protocol "grev6tap" (Ethernet GRE tunnel over IPv6)

The following options are supported, in addition to all common options above:

Name Type Required Default Description
ip6addr IPv6 address no WAN IP Local endpoint
peer6addr IPv6 address yes (none) Remote endpoint
weakif logical interface name no lan Logical network from which to select the local endpoint if ip6addr is empty and no WAN IP is available
network logical interface name no (none) Logical network to which the tunnel will be added (bridged)

Protocol "vti" (VTI tunnel over IPv4)

VTI Tunnels are IPsec policies with a fwmark set. The traffic is redirected to the matching VTI interface.

Name Type Required Default Description
ipaddr IPv4 address no WAN IP Local endpoint
peeraddr IPv4 address yes (none) Remote endpoint
mtu integer no 1280 MTU
tunlink logical interface name no (none) Bind the tunnel to this interface (dev option of “ip tunnel”)
zone zone name no “wan” Firewall zone to which the interface will be added
ikey integer no 0 key/fwmark for incoming packets
okey integer no 0 key/fwmark for outgoing packets

Protocol "vtiv6" (VTI tunnel over IPv6)

The following options are supported, in addition to all common options above:

Name Type Required Default Description
ip6addr IPv6 address no WAN IP Local endpoint
peer6addr IPv6 address yes (none) Remote endpoint
mtu integer no 1280 MTU
tunlink logical interface name no (none) Bind the tunnel to this interface (dev option of “ip tunnel”)
zone zone name no “wan” Firewall zone to which the interface will be added
ikey integer no 0 key/fwmark for incoming packets
okey integer no 0 key/fwmark for outgoing packets

Protocol "vxlan" (VXLAN layer 2 virtualization over layer 3 network)

A working VXLAN configuration consists of two interface definitions. One is the actual VXLAN interface, the other one is an alias interface. The following options can be used in the VXLAN interface definition (with option proto 'vxlan'):

Name Type Required Default Description
peeraddr string yes (none) IP address of the peer to connect to or a multicast address for a group of peers
port integer yes 8472 or 4789 Port for VXLAN connection, IANA-assigned default is '4789', several Linux distros use '8472' for historical reasons 
vid integer yes (none) VXLAN identifier used to identify a VXLAN network and properly convey frames
tunlink logical interface name yes (none) Bind the VXLAN tunnel to this interface
macaddr MAC address no (dynamically generated) Specify the MAC address of this interface manually
mtu integer no 1280 Manually specify the Maximum Transmission Unit of the VXLAN interface (VXLAN extends the length of the network frame, make sure it still fits the MTU of the underlying network)
ttl integer no 64 TTL of the encapsulation packets
tos integer no ? Type of Service (IPv4) or Traffic Class (IPv6)
rxcsum boolean no 1 Use checksum validation in RX (receiving) direction (0 = inactive, 1 = active)
txcsum boolean no 1 Use checksum validation in TX (transmission) direction (0 = inactive, 1 = active)
force_link boolean no 0 Set interface properties regardless of the link carrier (If set, carrier sense events do not invoke hotplug handlers) (0 = inactive, 1 = active)
delegate boolean no 1 Use built-in IPv6 management (0 = inactive, 1 = active)

Be careful: option ipaddr can be specified, but it does not have the effect of setting the IP address of the VXLAN interface. For correct configuration see the example VXLAN example configuration at the end of the page.

Protocol "xfrm" (XFRM tunnel interface)

XFRM Tunnel interfaces are bound to if_id set in the sa policy.

Name Type Required Default Description
ifid integer yes (none) if_id set in ipsec sa policy
tunlink logical interface name yes (none) Bind the tunnel to this interface (dev option of “ip tunnel”)
mtu integer no 1280 MTU
zone zone name no “wan” Firewall zone to which the interface will be added

Protocol "wireguard" (Wireguard VPN)

:!: The packages wireguard-tools and kmod-wireguard must be installed to use wireguard.

Each wireguard interface is configured in two parts:

  • the configuration relative to the interface itself (private key, MTU, UDP port to bind to, etc)
  • configuration relative to each peer (public key, IP address, etc)

Interface configuration (using proto wireguard):

Name Type Required Default Description
private_key string yes (none) Wireguard private key, generated with wg genkey
listen_port int no wireguard-specific UDP port used for outgoing and incoming packets
addresses list of IPs no (none) IPv4 or IPv6 addresses to assign to this interface
mtu integer no wireguard-specific Interface MTU
fwmark string no derived from listen_port Firewall mark to apply to tunnel endpoint packets
ip6prefix list of prefixes no (none) IPv6 prefixes to delegate to other interfaces
nohostroute boolean no 0 Do not add routes to ensure the tunnel endpoints are routed via non-tunnel device

Peer configuration, for each peer:

Name Type Required Default Description
public_key string yes (none) Public key of the peer
preshared_key string no (none) Optional shared secret, to provide an additional layer of symmetric-key cryptography for post-quantum resistance
allowed_ips list of prefixes yes (none) IP addresses and prefixes that this peer is allowed to use inside the tunnel, also used for Wireguard's internal routing table. Works for both IPv4 and IPv6
route_allowed_ips boolean no false Automatically create a route for each Allowed IPs for this peer
endpoint_host string no (none) IP address or hostname of the peer. If not specified, Wireguard will wait for connections from the peer
endpoint_port int no 51820 UDP port of the peer
persistent_keepalive int no 0 Number of second between keepalive messages, 0 means disabled

The name of a peer section must be wireguard_XX where XX is the name of the wireguard interface section.

Examples

Below are a few examples for special, non-standard interface configurations.

VPN-interfaces

:!: Avoid OpenVPN tunnel interface declaration to prevent the race condition with netifd service.

If you still want to manage VPN-interface such as tun0 via UCI-configuration and LuCI:

# /etc/config/network
config interface 'vpn'
        option ifname 'tun0'
        option proto 'none'

6in4 Tunnel

L2TPv3 Pseudowire bridged to LAN

This example establishes a Pseudowire Tunnel and bridges it to the LAN ports. The existing lan interface is reused with protocol l2tp instead of static.

config interface 'lan'
        option proto     'l2tp'
        option type      'bridge'
        option ifname    'eth0'
        option ipaddr    '192.168.1.1'
        option netmask   '255.255.255.0'
        option localaddr '178.24.154.19'
        option peeraddr  '89.44.33.61'
        option encap     'udp'
        option sport     '4000'
        option dport     '5410'

Relay between LAN and Wireless Station

This example sets up a relayd pseudo bridge between a wireless client network and LAN, so that it works similarly to the Broadcom Bridged Client mode.

Wireless configuration (excerpt):

config wifi-iface
        option device     'radio0'
        option mode       'sta'
        option ssid       'Some Wireless Network'
        option encryption 'psk2'
        option key        '12345678'
        option network    'wwan'

Network configuration (excerpt):
:!: Note that the LAN subnet must be different from the one used by wireless network's DHCP.

config interface 'lan'
        option ifname     'eth0.1'
        option proto      'static'
        option ipaddr     '192.168.1.1'
        option netmask    '255.255.255.0'
 
config interface 'wwan'
        option proto      'dhcp'
 
config interface 'stabridge'
        option proto      'relay'
        option network    'lan wwan'

In contrast to true bridging, traffic forwarded in this manner is affected by firewall rules, therefore both the wireless client network and the lan network should be covered by the same LAN firewall zone with forward policy set to accept to allow traffic flow between both interfaces:

config zone
        option name        'lan'
        option network     'lan wwan'  # Important
        option input       'ACCEPT'
        option forward     'ACCEPT'    # Important
        option output      'ACCEPT'

Static addressing of a GRE tunnel

Create a GRE tunnel with static address 10.42.0.253/30, adding it to an existing firewall zone called tunnels:

See warning on top of page about interface-name length. Previous interface names here were too long and silently fail.

config interface 'tunA'
        option proto    'gre'
        option zone     'tunnels'
        option peeraddr '198.51.100.42'
 
config interface 'tunAA'
        option proto    'static'
        option ifname   '@tunA'
        option ipaddr   '10.42.0.253'
        option netmask  '255.255.255.252'
        # Fixes IPv6 multicast (long-standing bug in kernel).
        # Useful if you run Babel or OSPFv3.
        option ip6addr  'fe80::42/64'

Static addressing of a IPSEC VTI tunnel

This adds support for configuring VTI interfaces within /etc/config/network. VTI interfaces are used to create IPsec tunnel interfaces. These interfaces may be used for routing and other purposes.

config interface 'vti1'
	option proto 'vti'
	option mtu '1500'
	option tunlink 'wan'
	option peeraddr '192.168.5.16'
	option zone 'VPN'
	option ikey 2
	option okey 2
 
config interface 'vti1_static'
	option proto 'static'
	option ifname '@vti1'
	option ipaddr '192.168.7.2/24'

The options ikey and okey correspond to the fwmark value of a ipsec policy. The may be null if you do not want fwmarks. Also peeraddr may be 0.0.0 if you want all ESP packets go through the interface.

Example strongswan config:

conn vti
	left=%any
	leftcert=peer2.test.der
	leftid=@peer2.test
	right=192.168.5.16
	rightid=@peer3.test
	leftsubnet=0.0.0.0/0
	rightsubnet=0.0.0.0/0
	mark=2
	auto=route

Static addressing of WireGuard tunnel

An example of WireGuard server and client configurations.

# Server
config interface 'vpn'
	option proto 'wireguard'
	option private_key 'SERVER_PRIVATE_KEY'
	option listen_port '51820'
	list addresses '192.168.9.1/24'
	list addresses 'fdf1:e8a1:8d3f:9::1/64'
 
config wireguard_vpn 'wgclient'
	option public_key 'CLIENT_PUBLIC_KEY'
	option preshared_key 'PRESHARED_KEY'
	list allowed_ips '192.168.9.2'
	list allowed_ips 'fdf1:e8a1:8d3f:9::2'
 
# Client
config interface 'vpn'
	option proto 'wireguard'
	option private_key 'CLIENT_PRIVATE_KEY'
	list addresses '192.168.9.2/24'
	list addresses 'fdf1:e8a1:8d3f:9::2/64'
 
config wireguard_vpn 'wgserver'
	option public_key 'SERVER_PUBLIC_KEY'
	option preshared_key 'PRESHARED_KEY'
	option endpoint_host 'SERVER_NAME_OR_IP_ADDRESS'
	option endpoint_port '51820'
	option route_allowed_ips '1'
	option persistent_keepalive '25'
	list allowed_ips '0.0.0.0/0'
	list allowed_ips '::/0'
 
config interface 'wan'
	option metric '100'
	...
 
config interface 'wan6'
	option metric '100'
	...

Create a WireGuard tunnel interface named foo that connects to one peer (VPN server at vpn.example.com) and allows another peer (e.g. road warrior) to connect. Peer configurations are managed via one or more wireguard_<ifname> sections.

config interface 'foo'
	option proto 'wireguard'
	option private_key 'qLvQnx5CpXPDo6oplzdIvXLNqkbgpXip3Yv4ouHWZ0Q='
	list addresses 'fd00:13:37:ffff::1/64'
 
config wireguard_foo
	option public_key '9mD+mTiOp7SGIkB4t3ZfWAcfp5iA/WwQRdVypKKwrjY='
	option route_allowed_ips '1'
	list allowed_ips 'fd00:13:37::/64'
	option endpoint_host 'vpn.example.com'
	option persistent_keepalive '25'
 
config wireguard_foo
	option public_key '4mLeSytW6/y4UcOT6rNorw1Ae9nXSxhXUjxsdzMWkUA='
	option preshared_key 'M1IbkkDVwXsQbFbURiMXiVe/iUCjC5TKHCmemVs+oLQ='
	list allowed_ips 'fd00:13:37:ffff::2'

VXLAN example configuration

Here is an example configuration for a VXLAN tunnel. Only the required options are used, optional ones can be specified additionally.

VXLAN interface definition:

config interface 'vxlan0'
        option proto 'vxlan'
        option peeraddr '10.10.222.1'
        option port '4789'
        option vid '8'
        option tunlink 'eth0'

Now it is necessary to create an alias interface for vxlan0 to assign an IP address as this is not possible with option ipaddr:

config interface 'l2vpn'
        option ifname '@vxlan0'        # Define as alias for 'vxlan0' interface
        option proto 'static'
        option ipaddr '10.10.0.1'
        option netmask '255.255.255.0'
        option layer '2'
This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website.More information about cookies
docs/guide-user/network/tunneling_interface_protocols.txt · Last modified: 2020/09/27 11:32 by vgaetera