| 1 |
.TH "Tunnel metadata manipulation action in tc" 8 "10 Nov 2016" "iproute2" "Linux" |
| 2 |
|
| 3 |
.SH NAME |
| 4 |
tunnel_key - Tunnel metadata manipulation |
| 5 |
.SH SYNOPSIS |
| 6 |
.in +8 |
| 7 |
.ti -8 |
| 8 |
.BR tc " ... " "action tunnel_key" " { " unset " | " |
| 9 |
.IR SET " }" |
| 10 |
|
| 11 |
.ti -8 |
| 12 |
.IR SET " := " |
| 13 |
.BR set " " src_ip |
| 14 |
.IR ADDRESS |
| 15 |
.BR dst_ip |
| 16 |
.IR ADDRESS |
| 17 |
.BI id " KEY_ID" |
| 18 |
.BI dst_port " UDP_PORT" |
| 19 |
.BI tos " TOS" |
| 20 |
.BI ttl " TTL" |
| 21 |
.RB "[ " csum " | " nocsum " ]" |
| 22 |
|
| 23 |
.SH DESCRIPTION |
| 24 |
The |
| 25 |
.B tunnel_key |
| 26 |
action combined with a shared IP tunnel device, allows one to perform IP tunnel en- |
| 27 |
or decapsulation on a packet, reflected by |
| 28 |
the operation modes |
| 29 |
.IR UNSET " and " SET . |
| 30 |
The |
| 31 |
.I UNSET |
| 32 |
mode is optional - even without using it, the metadata information will be |
| 33 |
released automatically when packet processing will be finished. |
| 34 |
.IR UNSET |
| 35 |
function could be used in cases when traffic is forwarded between two tunnels, |
| 36 |
where the metadata from the first tunnel will be used for encapsulation done by |
| 37 |
the second tunnel. |
| 38 |
.IR SET |
| 39 |
mode requires the source and destination ip |
| 40 |
.I ADDRESS |
| 41 |
and the tunnel key id |
| 42 |
.I KEY_ID |
| 43 |
which will be used by the ip tunnel shared device to create the tunnel header. The |
| 44 |
.B tunnel_key |
| 45 |
action is useful only in combination with a |
| 46 |
.B mirred redirect |
| 47 |
action to a shared IP tunnel device which will use the metadata (for |
| 48 |
.I SET |
| 49 |
) and unset the metadata created by it (for |
| 50 |
.I UNSET |
| 51 |
). |
| 52 |
|
| 53 |
.SH OPTIONS |
| 54 |
.TP |
| 55 |
.B unset |
| 56 |
Unset the tunnel metadata created by the IP tunnel device. This function is |
| 57 |
not mandatory and might be used only in some specific use cases (as explained |
| 58 |
above). |
| 59 |
.TP |
| 60 |
.B set |
| 61 |
Set tunnel metadata to be used by the IP tunnel device. Requires |
| 62 |
.B src_ip |
| 63 |
and |
| 64 |
.B dst_ip |
| 65 |
options. |
| 66 |
.B id |
| 67 |
, |
| 68 |
.B dst_port |
| 69 |
, |
| 70 |
.B geneve_opts |
| 71 |
, |
| 72 |
.B vxlan_opts |
| 73 |
and |
| 74 |
.B erspan_opts |
| 75 |
are optional. |
| 76 |
.RS |
| 77 |
.TP |
| 78 |
.B id |
| 79 |
Tunnel ID (for example VNI in VXLAN tunnel) |
| 80 |
.TP |
| 81 |
.B src_ip |
| 82 |
Outer header source IP address (IPv4 or IPv6) |
| 83 |
.TP |
| 84 |
.B dst_ip |
| 85 |
Outer header destination IP address (IPv4 or IPv6) |
| 86 |
.TP |
| 87 |
.B dst_port |
| 88 |
Outer header destination UDP port |
| 89 |
.TP |
| 90 |
.B geneve_opts |
| 91 |
Geneve variable length options. |
| 92 |
.B geneve_opts |
| 93 |
is specified in the form CLASS:TYPE:DATA, where CLASS is represented as a |
| 94 |
16bit hexadecimal value, TYPE as an 8bit hexadecimal value and DATA as a |
| 95 |
variable length hexadecimal value. Additionally multiple options may be |
| 96 |
listed using a comma delimiter. |
| 97 |
.TP |
| 98 |
.B vxlan_opts |
| 99 |
Vxlan metadata options. |
| 100 |
.B vxlan_opts |
| 101 |
is specified in the form GBP, as a 32bit number. Multiple options is not |
| 102 |
supported. |
| 103 |
.TP |
| 104 |
.B erspan_opts |
| 105 |
Erspan metadata options. |
| 106 |
.B erspan_opts |
| 107 |
is specified in the form VERSION:INDEX:DIR:HWID, where VERSION is represented |
| 108 |
as a 8bit number, INDEX as an 32bit number, DIR and HWID as a 8bit number. |
| 109 |
Multiple options is not supported. Note INDEX is used when VERSION is 1, |
| 110 |
and DIR and HWID are used when VERSION is 2. |
| 111 |
.TP |
| 112 |
.B tos |
| 113 |
Outer header TOS |
| 114 |
.TP |
| 115 |
.B ttl |
| 116 |
Outer header TTL |
| 117 |
.TP |
| 118 |
.RB [ no ] csum |
| 119 |
Controls outer UDP checksum. When set to |
| 120 |
.B csum |
| 121 |
(which is default), the outer UDP checksum is calculated and included in the |
| 122 |
packets. When set to |
| 123 |
.BR nocsum , |
| 124 |
outer UDP checksum is zero. Note that when using zero UDP checksums with |
| 125 |
IPv6, the other tunnel endpoint must be configured to accept such packets. |
| 126 |
In Linux, this would be the |
| 127 |
.B udp6zerocsumrx |
| 128 |
option for the VXLAN tunnel interface. |
| 129 |
.IP |
| 130 |
If using |
| 131 |
.B nocsum |
| 132 |
with IPv6, be sure you know what you are doing. Zero UDP checksums provide |
| 133 |
weaker protection against corrupted packets. See RFC6935 for details. |
| 134 |
.TP |
| 135 |
.B nofrag |
| 136 |
disallow IP fragmentation. |
| 137 |
.RE |
| 138 |
.SH EXAMPLES |
| 139 |
The following example encapsulates incoming ICMP packets on eth0 into a vxlan |
| 140 |
tunnel, by setting metadata to VNI 11, source IP 11.11.0.1 and destination IP |
| 141 |
11.11.0.2, and by redirecting the packet with the metadata to device vxlan0, |
| 142 |
which will do the actual encapsulation using the metadata: |
| 143 |
|
| 144 |
.RS |
| 145 |
.EX |
| 146 |
#tc qdisc add dev eth0 handle ffff: ingress |
| 147 |
#tc filter add dev eth0 protocol ip parent ffff: \\ |
| 148 |
flower \\ |
| 149 |
ip_proto icmp \\ |
| 150 |
action tunnel_key set \\ |
| 151 |
src_ip 11.11.0.1 \\ |
| 152 |
dst_ip 11.11.0.2 \\ |
| 153 |
id 11 \\ |
| 154 |
action mirred egress redirect dev vxlan0 |
| 155 |
.EE |
| 156 |
.RE |
| 157 |
|
| 158 |
Here is an example of the |
| 159 |
.B unset |
| 160 |
function: Incoming VXLAN traffic with outer IP's and VNI 11 is decapsulated by |
| 161 |
vxlan0 and metadata is unset before redirecting to tunl1 device: |
| 162 |
|
| 163 |
.RS |
| 164 |
.EX |
| 165 |
#tc qdisc add dev eth0 handle ffff: ingress |
| 166 |
#tc filter add dev vxlan0 protocol ip parent ffff: \ |
| 167 |
flower \\ |
| 168 |
enc_src_ip 11.11.0.2 enc_dst_ip 11.11.0.1 enc_key_id 11 \ |
| 169 |
action tunnel_key unset \ |
| 170 |
action mirred egress redirect dev tunl1 |
| 171 |
.EE |
| 172 |
.RE |
| 173 |
|
| 174 |
.SH SEE ALSO |
| 175 |
.BR tc (8) |