Tunneling interface protocols

This page describes all available tunneling 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)

:!: The package ppp-mod-pptp must be installed to use this protocol.

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
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-<ifname> Name of the physical interface. Defaults to pptp-<ifname> no matter what you use where <ifname> is the name of the logical interface

Common PPTP and PPP configuration locations:

Name Description
/etc/ppp/options.pptpd PPTP options
/var/etc/options.pptpd
/etc/ppp/chap-secrets PPTP secrets
/var/etc/chap-secrets
/etc/ppp/peers PPTP peers
/etc/ppp/ip-up Tunnel up scripts
/etc/ppp/ip-up.d
/etc/ppp/ip-down Tunnel down scripts
/etc/ppp/ip-down.d

PPTP options are configured using :

Name Description
lcp-echo-failure n Keep-alive, maximum number of echo attempts before considering the link to be dead
lcp-echo-interval n Keep-alive, time between each echo attempt in seconds
idle n Terminated tunnel after n seconds of inactivity, set to 0 to disable
refuse-eap Refuse to authenticate using EAP, needed with some recent servers, try it if you see EAP responses in debug log
persist Do not exit after a connection is terminated; instead try to reopen the connection
mppe required,no40,no56 Forces 128-bit encryption
demand Reconnect on demand
Name Description
[<domain>\\]<user> Matches name in /etc/ppp/peers/<peer_name>
<peer_name> Matches remotename in /etc/ppp/peers/<peer_name>
<password> Matches password given by the owner of the PPTP server, blanks or special characters should be enclosed in double quotes if any
* Allow the tunnel use any IP address, normally the PPTP server determines the address
umask go=
cat << "EOF" > /etc/ppp/chap-secrets
[<domain>\\]<user> <peer_name> <password> *
EOF
Name Description
pty "pptp <hostname_or_ip> --nolaunchpppd" Instruct pppd to launch pptp to connect to the VPN server
mppe required,stateless Require that the connection be encrypted, using stateless encryption
name [<domain>\\]<user> Define the username for the VPN connection, assuming that the password is stored in chap-secrets
remotename <peer_name> Specify the account and password in chap-secrets
replacedefaultroute Redirect default gateway to the VPN
ipparam <peer_name> A parameter for the PPP scripts to distinguish particular peer
file <path> Include PPTP options, e.g. /etc/ppp/options.pptpd
umask go=
mkdir -p /etc/ppp/peers
cat << "EOF" > /etc/ppp/peers/<peer_name>
...
EOF

PPP script parameters:

# Name Description
1 IFNAME Interface name used by pppd, e.g. ppp3
2 DEVICE TTY device name
3 SPEED TTY device speed
4 IPLOCAL Local tunnel IP address
5 IPREMOTE Remote tunnel IP address
6 (none) Client IP address, or ipparam parameter
(none) PEERNAME Client username parameter

An example script to invoke peer-specific code:

cat << "EOF" > /etc/ppp/ip-up
#!/bin/sh
case ${PEERNAME} in
(USERNAME1) ... ;;
(*) ... ;;
esac
EOF
chmod +x /etc/ppp/ip-up

:!: 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

:!: The package gre must be installed to use this protocol. 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 0 require incoming checksum
ocsum boolean no 0 compute outgoing checksum
iseqno boolean no 0 require incoming packets serialization
oseqno boolean no 0 perform outgoing packets serialization

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 1 Set “Don't Fragment” flag on encapsulating packets

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 1 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.

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

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)

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

Name Type Required Default Description
identity string yes(?) (none) Username for IEEE 802.1X authentication
password string yes(?) (none) Password for IEEE 802.1X authentication
ca_cert string no (none) Specifies the path the CA certificate used for authentication
client_cert string no (none) Specifies the client certificate used for the authentication
private_key string no (none) Specifies the path to the private key file used for authentication
private_key_passwd string no (none) Password to unlock the private key file, only works in conjunction with private_key

See alse wpa_enterprise_client.

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

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

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 no (none) IP address of the peer to connect to or a multicast address for a group of peers. Use vxlan_peer as described below for multiple peers
port integer no 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)

:!: 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.

Multiple peers can be configured with config vxlan_peer entries:

config vxlan_peer
        option vxlan vxlan0
        option dst '10.0.0.2'
 
config vxlan_peer
        option vxlan vxlan0
        option dst '10.0.0.3'

All available options for config vxlan_peer:

Name Type Required Default Description
vxlan string yes (none) which vxlan interface to add peer to
lladdr MAC address no 00:00:00:00:00:00 L2 (MAC) address of peer. Uses source-address learning when 00:00:00:00:00:00 is specified
dst IP address yes (none) the IP address of the remote VXLAN tunnel endpoint where the MAC address (lladdr) resides or a multicast address for a group of peers. For multicast, an outgoing interface needs to be specified (via)
port integer no (none) the UDP destination port number to use to connect to the remote VXLAN tunnel endpoint
via logical interface name no (none) name of the outgoing interface to reach the remote VXLAN tunnel endpoint
vni integer no (none) the VXLAN VNI Network Identifier (or VXLAN Segment ID) to use to connect to the remote VXLAN tunnel endpoint
src_vni integer no (none) the source VNI Network Identifier (or VXLAN Segment ID) this entry belongs to. Used only when the vxlan device is in external or collect metadata mode

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

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

Name OpenConnect CLI option Description
server (always required) The server's FQDN or IP
port (part of server) Server port number. Default is 443
juniper --juniper Connect to a Juniper server. DEPRECATED, 8.0 uses --protocol=nc instead.
serverhash --servercert=; --no-system-trust Force trust of server's certificate based only on hash matching
authgroup --authgroup= Group membership to request from the server
username --user= Login username for user/pass authentication
password (passed via stdin) Password for user/pass authentication
password2 (passed via stdin) Second password for 2 factor
token_mode --token-mode= rsa, totp or hotp to internally compute a two-factor token as passwd2
token_secret --token-secret= Crypto secret required by token_mode
token_script --token-script= Local shell script that will dynamically produce passwd2
os --os= Operating system to report to the server. Default is Linux
interface N/A Outgoing local interface (used to create a netifd host dependency)
csd_wrapper --csd-wrapper= Run this instead of any binary or script that the server pushes us to run
defaultroute N/A Create default route over the tunnel, boolean, default is 1
peerdns N/A Use provided DNS servers, boolean, default is 1

Most of these options are passed directly to the OpenConnect executive, so see openconnect for details.

Certificates and keys files must be in the PEM format and named as shown below where <ifname> is the name of the logical interface.

Name OpenConnect CLI option Description
/etc/openconnect/ca-vpn-<ifname>.pem --cafile= CA certificate used to verify the server's certificate.
/etc/openconnect/user-cert-vpn-<ifname>.pem --certificate= Client certificate, signed by a CA that the server knows.
/etc/openconnect/user-key-vpn-<ifname>.pem --sslkey= Private key of the client certificate, Must not be encrypted.

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

Name Type Required Default Description
server string yes (none) SSH server name
port integer no 22 SSH server port
sshuser string yes (none) SSH login username
identity list no ~/.ssh/id_{rsa,dsa} list of client private key files. The defaults will be used if no identity file was specified and at least one of them must be valid for the public key authentication to proceed.
ipaddr string yes (none) local ip address to be assigned
peeraddr string yes (none) peer ip address to be assigned
ssh_options list yes (none) peer ip address to be assigned
use_hostdep bool no 1 set it to 0 to disable the use of proto_add_host_dependency. This is mainly for the case that the appropriate route to server is not registered to netifd and thus causing a incorrect route being setup

For configuration see current README.

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

For configuration see current README.

:!: The package wireguard-tools must be installed to use this protocol.

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
tunlink string no (none) Bind the tunnel to the specified interface, OpenWrt 21.02+

The name of the network interface will be the name of the configuration section.

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 0 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_<ifname> where <ifname> is the name of the logical interface.

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

:!: 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 device 'tun0'
	option proto 'none'

Support for L2TP is provided by xl2tpd package. The username and password are for PPP authentication.

config interface 'l2tpwan'
	option proto 'l2tp'
	option server '1.2.3.4'
	option username 'mylogin'
	option password 'mypassword'
	option keepalive '30'

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'

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'

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'

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

An example of WireGuard server configuration.

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 'fd00: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 'fd00:9::2'

An example of WireGuard client configuration.

config interface 'vpn'
	option proto 'wireguard'
	option private_key 'CLIENT_PRIVATE_KEY'
	list addresses '192.168.9.2/24'
	list addresses 'fd00:9::2/64'
 
config wireguard_vpn 'wgserver'
	option public_key 'SERVER_PUBLIC_KEY'
	option preshared_key 'PRESHARED_KEY'
	option endpoint_host 'SERVER_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'

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'

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'
	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
  • Last modified: 2024/02/12 10:36
  • by patrickh