TC-ACTIONS(8)

🎀 NAME 🎀

okay so bestie, this is the page for actions — independently defined actions in tc. yes that tc, the traffic control one, from the tc(8) manual. we're doing kernel networking today, sit down, hydrate. 💅

---

✨ SYNOPSIS ✨

tc [ TC_OPTIONS ] actions add | change | replace ACTSPEC

tc [ TC_OPTIONS ] actions get | delete ACTISPEC

tc [ TC_OPTIONS ] actions flush ACTNAMESPEC

tc [ TC_OPTIONS ] actions ls | list ACTNAMESPEC [ ACTFILTER ]

        ACTSPEC := action ACTDETAIL [ INDEXSPEC ] [ COOKIESPEC ] [ FLAGS
        ] [ HWSTATSSPEC ] [ CONTROL ] [ SKIPSPEC ]

        ACTISPEC := ACTNAMESPEC INDEXSPEC

        ACTNAMESPEC := action ACTNAME

        INDEXSPEC := index INDEX

        ACTFILTER := since MSTIME

        COOKIESPEC := cookie COOKIE

        FLAGS := no_percpu

        HWSTATSSPEC := hw_stats { immediate | delayed | disabled }

        ACTDETAIL := ACTNAME ACTPARAMS

        ACTNAME may be any valid action type: gact, mirred, bpf,
        connmark, csum, police, etc.

        MSTIME Time since last update.

        CONTROL := { reclassify | pipe | drop | continue | ok }

        SKIPSPEC := { skip_sw | skip_hw }

        TC_OPTIONS These are the options that are specific to tc and not
        only the options. Refer to tc(8) for more information.

fr fr, that TC_OPTIONS line is telling you to go read tc(8) too, bestie. it's giving "see also but in the synopsis".

---

🦋 DESCRIPTION 🦋

so the actions object in tc lets you define actions independently of a classifier (aka a filter). once you've made them, you can hand them out to one or more filters, and any packet that matches that classifier's criteria gets that action performed on it. iconic. 👑

every action type (mirred, police, etc.) gets its own table to store all the created actions in. so they don't mix, no drama, no crossover episodes. 🌈

---

💖 OPERATIONS 💖

• add — Create a new action in that action's table.
• change, replace — Make modifications to an existing action.
• get — Display the action with the specified index value. when you combine it with the -s option for tc, it displays the statistics for that action. ✨
• delete — Delete the action with the specified index value. heads up though: if the action is already associated with a classifier, it does not delete the classifier. the action leaves, the filter stays. they're not a package deal. 💀
• ls, list — List all the actions in the specified table. combined with the -s option for tc? you get the statistics for all actions in that specified table. and combined with the since option, it lets you do a millisecond time-filter since the last time an action was used in the datapath. obsessed.
• flush — Delete all actions stored in the specified table. all of them. gone. 🫶

---

🌸 ACTION OPTIONS 🌸

quick vibe check: these options are available to all action types.

• index INDEX — Specify the table index value of an action. INDEX is a 32-bit value that is unique to the specific type of action referenced.

for add, change, and replace operations, the index is optional. when you're adding a new action, specifying an index value will assign the action to that index — unless that index value has already been assigned, in which case, no. and if you omit the index value for an add operation, the kernel itself will assign a value to the new action. letting the kernel pick, very demure.

for get and delete operations, the index is required, because that's literally how you identify which specific action to display or delete. no index, no service. 💅

• cookie COOKIE — In addition to the specific action, mark the matching packet with the value specified by COOKIE. the COOKIE is a 128-bit value that will not be interpreted by the kernel whatsoever. so it's yours, it's free real estate — use it as a correlating value for maintaining user state. the value you store is completely arbitrary, no specific format required, it just lives inside the action structure itself. 🍓
• FLAGS — Action-specific flags. currently the only supported flag is no_percpu, which indicates that the action is expected to have minimal software data-path traffic and doesn't need to allocate stat counters with the percpu allocator. this option is intended to be used by hardware-offloaded actions. 🤖
• hw_stats HW_STATS — Specifies the type of HW stats of the new action. if you omit it, any stats counter type is going to be used, according to the driver and its resources. HW_STATS indicates the type, and any of these are valid:
  • immediate — Means that in dump, the user gets the current HW stats state from the device, queried at the dump time. fresh out the oven. ✨
  • delayed — Means that in dump, the user gets HW stats that might be out of date for some time, maybe a couple of seconds. this is the case when the driver polls stats updates periodically, or when it gets async stats updates from the device. it's giving "seen 2 seconds ago".
  • disabled — No HW stats are going to be available in dump. nada. zero. 🙈
• since MSTIME — When dumping a large number of actions, you can specify a millisecond time-filter, MSTIME. MSTIME is a millisecond count since the last time a packet hit the action. for example, specifying "since 20000" implies dumping all actions that have seen packets in the last 20 seconds. super useful when the kernel has a huge number of actions and you only care about the recently used ones. main character actions only. 👑
• CONTROL — CONTROL indicates how tc should proceed after executing the action. any of these are valid:
  • reclassify — Restart the classification by jumping back to the first filter attached to the action's parent. 🔁
  • pipe — Continue with the next action. this is the default control.
  • drop — Drop the packet without running any further actions. bye bestie 💀
  • continue — Continue the classification with the next filter.
  • pass — Return to the calling qdisc for packet processing, and end classification of this packet.
• SKIPSPEC — The SKIPSPEC indicates how tc should proceed when executing the action. any of these are valid:
  • skip_sw — Do not process action by software. and if hardware has no offload support for this action, the operation will fail. so like, know your hardware first. 😭
  • skip_hw — Do not process action by hardware.

---

🫶 SEE ALSO 🫶

tc(8), tc-bpf(8), tc-connmark(8), tc-csum(8), tc-ife(8), tc-mirred(8), tc-nat(8), tc-pedit(8), tc-police(8), tc-simple(8), tc-skbedit(8), tc-skbmod(8), tc-tunnel_key(8), tc-vlan(8), tc-xt(8)

go read those too, iykyk, the whole friend group is worth knowing. 🧚

---

and that's the page, bestie!! this one's from iproute2, dated 1 Aug 2017. mwah, slay, periodt. 💜✨