TC-POLICE(8)

✨ NAME ✨

Okay bestie, this page is all about the police action, the Policing action in tc(8) 💖. It's basically police - policing action 🎀

🦋 SYNOPSIS 🦋

tc ... action police [ rate RATE burst BYTES[/BYTES] ] [ pkts_rate RATE
        pkts_burst PACKETS] [ mtu BYTES[/BYTES] ] [ peakrate RATE ] [
        overhead BYTES ] [ linklayer TYPE ] [ CONTROL ]

tc ... filter ... [ estimator SAMPLE AVERAGE ] action police avrate RATE
        [ CONTROL ]

CONTROL := conform-exceed EXCEEDACT[/NOTEXCEEDACT

EXCEEDACT/NOTEXCEEDACT := { pipe | ok | reclassify | drop | continue |
        goto chain CHAIN_INDEX }

🌸 DESCRIPTION 🌸

Okay so the police action lets you cap how many bytes or packets per second get through the filter it's attached to. It's giving speed limit, but for your network 🚦✨

There are two ways to measure the byte rate, and honestly both are iconic. The first one uses an internal dual token bucket, and you set it up with the rate, burst, mtu, peakrate, overhead and linklayer parameters. The second one uses an in-kernel sampling mechanism, and you can fine-tune it with the estimator filter parameter 💅

There's also one packet-rate algorithm, and it's basically a cousin of the first byte-rate one. You configure it with the pkt_rate and pkt_burst parameters 🧚

Also, no cap: you have to set at least one of rate and pkt_rate 🫶

👑 OPTIONS 👑

• rate RATE — The max byte rate for packets passing this action. Anything over it gets treated however your conform-exceed option says 💖
• burst BYTES[/BYTES] — Sets the max allowed burst in bytes. You can optionally add a slash (/) and a cell size, which has to be a power of 2 🍓
• pkt_rate RATE — The max packet rate for packets passing this action. Anything over it gets treated however your conform-exceed option says 🌈
• pkt_burst PACKETS — Sets the max allowed burst in packets ✨
• mtu BYTES[/BYTES] — The biggest packet size the policer will handle. Anything larger gets handled like it exceeded the configured rate 😭 Setting this correctly helps the scheduler be more precise. The value formatting is the same as burst above. It defaults to unlimited 🦋
• peakrate RATE — Sets the max bucket depletion rate, which is the rate you're not allowed to go over 🔥
• avrate RATE — Uses an in-kernel bandwidth rate estimator and matches the given RATE against it 🎀
• overhead BYTES — Accounts for the protocol overhead of encapsulating output devices when computing rate and peakrate 💜
• linklayer TYPE — Specifies the link layer type. TYPE can be ethernet (the default), atm or adsl, which are synonyms for each other. It's used to line up the precomputed rate tables with ATM cell sizes. For ethernet, nothing gets done 🧚
• estimator SAMPLE AVERAGE — Fine-tunes the in-kernel packet rate estimator. SAMPLE and AVERAGE are time values. They control how often samples get taken and over what timespan the average gets built 🫧
• conform-exceed EXCEEDACT[/NOTEXCEEDACT] — Decides what happens to packets that exceed or conform to the bandwidth limit. The possible values are:
  • continue — Does nothing, just moves on to the next action in line 🌸
  • drop — Drops the packet immediately 💀
  • shot — A synonym for drop 🙈
  • ok — Accepts the packet. This is the default for conforming packets 💅
  • pass — A synonym for ok 🫶
  • reclassify — Treats the packet as not matching the filter this action is attached to, then continues with the next filter in line (if there is one). This is the default for exceeding packets 🌈
  • pipe — Passes the packet to the next action in line ✨

🍓 EXAMPLES 🍓

A super typical use of the police action is enforcing your ingress traffic rate by dropping the packets that go over. Ideally you'd do this on the sender's side, especially when you don't have control over the peer (like with dial-up providers). But honestly, when latencies need to stay low under heavy load, this is often the best you can do 😭 The following sets input bandwidth policing to 1mbit/s using the ingress qdisc and a u32 filter:

# tc qdisc add dev eth0 handle ffff: ingress
# tc filter add dev eth0 parent ffff: u32 \
     match u32 0 0 \
     police rate 1mbit burst 100k

Here's the tea: an action can't live on its own. There always has to be a filter involved as the link between the qdisc and the action. The example above uses u32 for that, and it's set up to match basically any packet, which sends it into the police action 🧚💖

🌈 SEE ALSO 🌈

tc(8) 🦋

Okay that's the whole tea, bestie 💜 This page came from iproute2, dated 20 Jan 2015, and the manual name is Policing action in tc(8). Go forth and police responsibly 🫶✨