man/man8/tc-pedit.8

   1 .TH "Generic packet editor action in tc" 8 "12 Jan 2015" "iproute2" "Linux"
   2
   3 .SH NAME
   4 pedit - generic packet editor action
   5 .SH SYNOPSIS
   6 .in +8
   7 .ti -8
   8 .BR tc " ... " "action pedit [ex] munge " {
   9 .IR RAW_OP " | " LAYERED_OP " | " EXTENDED_LAYERED_OP " } [ " CONTROL " ]"
  10
  11 .ti -8
  12 .IR RAW_OP " := "
  13 .BI offset " OFFSET"
  14 .RB "{ " u8 " | " u16 " | " u32 " } ["
  15 .IR AT_SPEC " ] " CMD_SPEC
  16
  17 .ti -8
  18 .IR AT_SPEC " := "
  19 .BI at " AT " offmask " MASK " shift " SHIFT"
  20
  21 .ti -8
  22 .IR LAYERED_OP " := { "
  23 .BI ip " IPHDR_FIELD"
  24 |
  25 .BI ip " BEYOND_IPHDR_FIELD"
  26 .RI } " CMD_SPEC"
  27
  28 .ti -8
  29 .IR EXTENDED_LAYERED_OP " := { "
  30 .BI eth " ETHHDR_FIELD"
  31 |
  32 .BI ip " IPHDR_FIELD"
  33 |
  34 .BI ip " EX_IPHDR_FIELD"
  35 |
  36 .BI ip6 " IP6HDR_FIELD"
  37 |
  38 .BI tcp " TCPHDR_FIELD"
  39 |
  40 .BI udp " UDPHDR_FIELD"
  41 .RI } " CMD_SPEC"
  42
  43 .ti -8
  44 .IR ETHHDR_FIELD " := { "
  45 .BR src " | " dst " | " type " }"
  46
  47 .ti -8
  48 .IR IPHDR_FIELD " := { "
  49 .BR src " | " dst " | " tos " | " dsfield " | " ihl " | " protocol " |"
  50 .BR precedence " | " nofrag " | " firstfrag " | " ce " | " df " }"
  51
  52 .ti -8
  53 .IR BEYOND_IPHDR_FIELD " := { "
  54 .BR dport " | " sport " | " icmp_type " | " icmp_code " }"
  55
  56 .ti -8
  57 .IR EX_IPHDR_FIELD " := { "
  58 .BR ttl " }"
  59
  60
  61 .ti -8
  62 .IR IP6HDR_FIELD " := { "
  63 .BR src " | " dst " | " traffic_class " | " flow_lbl " | " payload_len " | "
  64 .BR nexthdr " | " hoplimit " }"
  65
  66 .ti -8
  67 .IR TCPHDR_FIELD " := { "
  68 .BR sport " | " dport " | " flags " }"
  69
  70 .ti -8
  71 .IR UDPHDR_FIELD " := { "
  72 .BR sport " | " dport " }"
  73
  74 .ti -8
  75 .IR CMD_SPEC " := {"
  76 .BR clear " | " invert " | " set
  77 .IR VAL " | "
  78 .BR add
  79 .IR VAL " | "
  80 .BR preserve " } [ " retain
  81 .IR RVAL " ]"
  82
  83 .ti -8
  84 .IR CONTROL " := {"
  85 .BR reclassify " | " pipe " | " drop " | " shot " | " continue " | " pass " | " goto " " chain " " CHAIN_INDEX " }"
  86 .SH DESCRIPTION
  87 The
  88 .B pedit
  89 action can be used to change arbitrary packet data. The location of data to
  90 change can either be specified by giving an offset and size as in
  91 .IR RAW_OP ,
  92 or for header values by naming the header and field to edit the size is then
  93 chosen automatically based on the header field size. Currently this is supported
  94 only for IPv4 headers.
  95 .SH OPTIONS
  96 .TP
  97 .B ex
  98 Use extended pedit.
  99 .I EXTENDED_LAYERED_OP
 100 and the add
 101 .I CMD_SPEC
 102 are allowed only in this mode.
 103 .TP
 104 .BI offset " OFFSET " "\fR{ \fBu32 \fR| \fBu16 \fR| \fBu8 \fR}"
 105 Specify the offset at which to change data.
 106 .I OFFSET
 107 is a signed integer, it's base is automatically chosen (e.g. hex if prefixed by
 108 .B 0x
 109 or octal if prefixed by
 110 .BR 0 ).
 111 The second argument specifies the length of data to change, that is four bytes
 112 .RB ( u32 ),
 113 two bytes
 114 .RB ( u16 )
 115 or a single byte
 116 .RB ( u8 ).
 117 .TP
 118 .BI at " AT " offmask " MASK " shift " SHIFT"
 119 This is an optional part of
 120 .IR RAW_OP
 121 which allows to have a variable
 122 .I OFFSET
 123 depending on packet data at offset
 124 .IR AT ,
 125 which is binary ANDed with
 126 .I MASK
 127 and right-shifted by
 128 .I SHIFT
 129 before adding it to
 130 .IR OFFSET .
 131 .TP
 132 .BI eth " ETHHDR_FIELD"
 133 Change an ETH header field. The supported keywords for
 134 .I ETHHDR_FIELD
 135 are:
 136 .RS
 137 .TP
 138 .B src
 139 .TQ
 140 .B dst
 141 Source or destination MAC address in the standard format: XX:XX:XX:XX:XX:XX
 142 .TP
 143 .B type
 144 Ether-type in numeric value
 145 .RE
 146 .TP
 147 .BI ip " IPHDR_FIELD"
 148 Change an IPv4 header field. The supported keywords for
 149 .I IPHDR_FIELD
 150 are:
 151 .RS
 152 .TP
 153 .B src
 154 .TQ
 155 .B dst
 156 Source or destination IP address, a four-byte value.
 157 .TP
 158 .B tos
 159 .TQ
 160 .B dsfield
 161 .TQ
 162 .B precedence
 163 Type Of Service field, an eight-bit value.
 164 .TP
 165 .B ihl
 166 Change the IP Header Length field, a four-bit value.
 167 .TP
 168 .B protocol
 169 Next-layer Protocol field, an eight-bit value.
 170 .TP
 171 .B nofrag
 172 .TQ
 173 .B firstfrag
 174 .TQ
 175 .B ce
 176 .TQ
 177 .B df
 178 .TQ
 179 .B mf
 180 Change IP header flags. Note that the value to pass to the
 181 .B set
 182 command is not just a bit value, but the full byte including the flags field.
 183 Though only the relevant bits of that value are respected, the rest ignored.
 184 .RE
 185 .TP
 186 .BI ip " BEYOND_IPHDR_FIELD"
 187 Supported only for non-extended layered op. It is passed to the kernel as
 188 offsets relative to the beginning of the IP header and assumes the IP header is
 189 of minimum size (20 bytes). The supported keywords for
 190 .I BEYOND_IPHDR_FIELD
 191 are:
 192 .RS
 193 .TP
 194 .B dport
 195 .TQ
 196 .B sport
 197 Destination or source port numbers, a 16-bit value. Indeed, IPv4 headers don't
 198 contain this information. Instead, this will set an offset which suits at least
 199 TCP and UDP if the IP header is of minimum size (20 bytes). If not, this will do
 200 unexpected things.
 201 .TP
 202 .B icmp_type
 203 .TQ
 204 .B icmp_code
 205 Again, this allows to change data past the actual IP header itself. It assumes
 206 an ICMP header is present immediately following the (minimal sized) IP header.
 207 If it is not or the latter is bigger than the minimum of 20 bytes, this will do
 208 unexpected things. These fields are eight-bit values.
 209 .RE
 210 .TP
 211 .BI ip " EX_IPHDR_FIELD"
 212 Supported only when
 213 .I ex
 214 is used. The supported keywords for
 215 .I EX_IPHDR_FIELD
 216 are:
 217 .RS
 218 .TP
 219 .B ttl
 220 .RE
 221 .TP
 222 .BI ip6 " IP6HDR_FIELD"
 223 The supported keywords for
 224 .I IP6HDR_FIELD
 225 are:
 226 .RS
 227 .TP
 228 .B src
 229 .TQ
 230 .B dst
 231 .TQ
 232 .B traffic_class
 233 .TQ
 234 .B flow_lbl
 235 .TQ
 236 .B payload_len
 237 .TQ
 238 .B nexthdr
 239 .TQ
 240 .B hoplimit
 241 .RE
 242 .TP
 243 .BI tcp " TCPHDR_FIELD"
 244 The supported keywords for
 245 .I TCPHDR_FIELD
 246 are:
 247 .RS
 248 .TP
 249 .B sport
 250 .TQ
 251 .B dport
 252 Source or destination TCP port number, a 16-bit value.
 253 .TP
 254 .B flags
 255 .RE
 256 .TP
 257 .BI udp " UDPHDR_FIELD"
 258 The supported keywords for
 259 .I UDPHDR_FIELD
 260 are:
 261 .RS
 262 .TP
 263 .B sport
 264 .TQ
 265 .B dport
 266 Source or destination TCP port number, a 16-bit value.
 267 .RE
 268 .TP
 269 .B clear
 270 Clear the addressed data (i.e., set it to zero).
 271 .TP
 272 .B invert
 273 Swap every bit in the addressed data.
 274 .TP
 275 .BI set " VAL"
 276 Set the addressed data to a specific value. The size of
 277 .I VAL
 278 is defined by either one of the
 279 .BR u32 ", " u16 " or " u8
 280 keywords in
 281 .IR RAW_OP ,
 282 or the size of the addressed header field in
 283 .IR LAYERED_OP .
 284 .TP
 285 .BI add " VAL"
 286 Add the addressed data by a specific value. The size of
 287 .I VAL
 288 is defined by the size of the addressed header field in
 289 .IR EXTENDED_LAYERED_OP .
 290 This operation is supported only for extended layered op.
 291 .TP
 292 .B preserve
 293 Keep the addressed data as is.
 294 .TP
 295 .BI retain " RVAL"
 296 This optional extra part of
 297 .I CMD_SPEC
 298 allows to exclude bits from being changed. Supported only for 32 bits fields
 299 or smaller.
 300 .TP
 301 .I CONTROL
 302 The following keywords allow to control how the tree of qdisc, classes,
 303 filters and actions is further traversed after this action.
 304 .RS
 305 .TP
 306 .B reclassify
 307 Restart with the first filter in the current list.
 308 .TP
 309 .B pipe
 310 Continue with the next action attached to the same filter.
 311 .TP
 312 .B drop
 313 .TQ
 314 .B shot
 315 Drop the packet.
 316 .TP
 317 .B continue
 318 Continue classification with the next filter in line.
 319 .TP
 320 .B pass
 321 Finish classification process and return to calling qdisc for further packet
 322 processing. This is the default.
 323 .RE
 324 .SH EXAMPLES
 325 Being able to edit packet data, one could do all kinds of things, such as e.g.
 326 implementing port redirection. Certainly not the most useful application, but
 327 as an example it should do:
 328
 329 First, qdiscs need to be set up to attach filters to. For the receive path, a simple
 330 .B ingress
 331 qdisc will do, for transmit path a classful qdisc
 332 .RB ( HTB
 333 in this case) is necessary:
 334
 335 .RS
 336 .EX
 337 tc qdisc replace dev eth0 root handle 1: htb
 338 tc qdisc add dev eth0 ingress handle ffff:
 339 .EE
 340 .RE
 341
 342 Finally, a filter with
 343 .B pedit
 344 action can be added for each direction. In this case,
 345 .B u32
 346 is used matching on the port number to redirect from, while
 347 .B pedit
 348 then does the actual rewriting:
 349
 350 .RS
 351 .EX
 352 tc filter add dev eth0 parent 1: u32 \\
 353         match ip dport 23 0xffff \\
 354         action pedit pedit munge ip dport set 22
 355 tc filter add dev eth0 parent ffff: u32 \\
 356         match ip sport 22 0xffff \\
 357         action pedit pedit munge ip sport set 23
 358 tc filter add dev eth0 parent ffff: u32 \\
 359         match ip sport 22 0xffff \\
 360         action pedit ex munge ip dst set 192.168.1.199
 361 tc filter add dev eth0 parent ffff: u32 \\
 362         match ip sport 22 0xffff \\
 363         action pedit ex munge ip6 dst set fe80::dacb:8aff:fec7:320e
 364 tc filter add dev eth0 parent ffff: u32 \\
 365         match ip sport 22 0xffff \\
 366         action pedit ex munge eth dst set 11:22:33:44:55:66
 367 tc filter add dev eth0 parent ffff: u32 \\
 368         match ip dport 23 0xffff \\
 369         action pedit ex munge tcp dport set 22
 370 .EE
 371 .RE
 372 .SH SEE ALSO
 373 .BR tc (8),
 374 .BR tc-htb (8),
 375 .BR tc-u32 (8)