.TH "Tunnel metadata manipulation action in tc" 8 "10 Nov 2016" "iproute2" "Linux"

.SH NAME
tunnel_key - Tunnel metadata manipulation
.SH SYNOPSIS
.in +8
.ti -8
.BR tc " ... " "action tunnel_key" " { " unset " | "
.IR SET " }"

.ti -8
.IR SET " := "
.BR set " " src_ip
.IR ADDRESS
.BR dst_ip
.IR ADDRESS
.BI id " KEY_ID"
.BI dst_port " UDP_PORT"
.BI tos " TOS"
.BI ttl " TTL"
.RB "[ " csum " | " nocsum " ]"

.SH DESCRIPTION
The
.B tunnel_key
action combined with a shared IP tunnel device, allows one to perform IP tunnel en-
or decapsulation on a packet, reflected by
the operation modes
.IR UNSET " and " SET .
The
.I UNSET
mode is optional - even without using it, the metadata information will be
released automatically when packet processing will be finished.
.IR UNSET
function could be used in cases when traffic is forwarded between two tunnels,
where the metadata from the first tunnel will be used for encapsulation done by
the second tunnel.
.IR SET
mode requires the source and destination ip
.I ADDRESS
and the tunnel key id
.I KEY_ID
which will be used by the ip tunnel shared device to create the tunnel header. The
.B tunnel_key
action is useful only in combination with a
.B mirred redirect
action to a shared IP tunnel device which will use the metadata (for
.I SET
) and unset the metadata created by it (for
.I UNSET
).

.SH OPTIONS
.TP
.B unset
Unset the tunnel metadata created by the IP tunnel device.  This function is
not mandatory and might be used only in some specific use cases (as explained
above).
.TP
.B set
Set tunnel metadata to be used by the IP tunnel device. Requires
.B src_ip
and
.B dst_ip
options.
.B id
,
.B dst_port
,
.B geneve_opts
,
.B vxlan_opts
and
.B erspan_opts
are optional.
.RS
.TP
.B id
Tunnel ID (for example VNI in VXLAN tunnel)
.TP
.B src_ip
Outer header source IP address (IPv4 or IPv6)
.TP
.B dst_ip
Outer header destination IP address (IPv4 or IPv6)
.TP
.B dst_port
Outer header destination UDP port
.TP
.B geneve_opts
Geneve variable length options.
.B geneve_opts
is specified in the form CLASS:TYPE:DATA, where CLASS is represented as a
16bit hexadecimal value, TYPE as an 8bit hexadecimal value and DATA as a
variable length hexadecimal value. Additionally multiple options may be
listed using a comma delimiter.
.TP
.B vxlan_opts
Vxlan metadata options.
.B vxlan_opts
is specified in the form GBP, as a 32bit number. Multiple options is not
supported.
.TP
.B erspan_opts
Erspan metadata options.
.B erspan_opts
is specified in the form VERSION:INDEX:DIR:HWID, where VERSION is represented
as a 8bit number, INDEX as an 32bit number, DIR and HWID as a 8bit number.
Multiple options is not supported. Note INDEX is used when VERSION is 1,
and DIR and HWID are used when VERSION is 2.
.TP
.B tos
Outer header TOS
.TP
.B ttl
Outer header TTL
.TP
.RB [ no ] csum
Controls outer UDP checksum. When set to
.B csum
(which is default), the outer UDP checksum is calculated and included in the
packets. When set to
.BR nocsum ,
outer UDP checksum is zero. Note that when using zero UDP checksums with
IPv6, the other tunnel endpoint must be configured to accept such packets.
In Linux, this would be the
.B udp6zerocsumrx
option for the VXLAN tunnel interface.
.IP
If using
.B nocsum
with IPv6, be sure you know what you are doing. Zero UDP checksums provide
weaker protection against corrupted packets. See RFC6935 for details.
.TP
.B nofrag
disallow IP fragmentation.
.RE
.SH EXAMPLES
The following example encapsulates incoming ICMP packets on eth0 into a vxlan
tunnel, by setting metadata to VNI 11, source IP 11.11.0.1 and destination IP
11.11.0.2, and by redirecting the packet with the metadata to device vxlan0,
which will do the actual encapsulation using the metadata:

.RS
.EX
#tc qdisc add dev eth0 handle ffff: ingress
#tc filter add dev eth0 protocol ip parent ffff: \\
  flower \\
    ip_proto icmp \\
  action tunnel_key set \\
    src_ip 11.11.0.1 \\
    dst_ip 11.11.0.2 \\
    id 11 \\
  action mirred egress redirect dev vxlan0
.EE
.RE

Here is an example of the
.B unset
function: Incoming VXLAN traffic with outer IP's and VNI 11 is decapsulated by
vxlan0 and metadata is unset before redirecting to tunl1 device:

.RS
.EX
#tc qdisc add dev eth0 handle ffff: ingress
#tc filter add dev vxlan0 protocol ip parent ffff: \
  flower \\
	  enc_src_ip 11.11.0.2 enc_dst_ip 11.11.0.1 enc_key_id 11 \
	action tunnel_key unset \
	action mirred egress redirect dev tunl1
.EE
.RE

.SH SEE ALSO
.BR tc (8)