CBS(8)

✨ NAME ✨

okay bestie, this page is all about CBS, the Credit Based Shaper 💖 It's a qdisc (a queueing discipline), and it's lowkey iconic for traffic control on Linux 🐧

🎀 SYNOPSIS 🎀

tc qdisc ... dev dev parent classid [ handle major: ] cbs idleslope
idleslope sendslope sendslope hicredit hicredit locredit locredit [
offload 0|1 ]

🦋 DESCRIPTION 🦋

so the CBS (Credit Based Shaper) qdisc runs the shaping algorithm from IEEE 802.1Q-2014 Section 8.6.8.2. It's a well-defined way to rate limit your traffic, and it's giving precision 💅

this one is made for TSN (Time Sensitive Networking) apps 🧚 The CBS parameters come straight from Annex L of the IEEE 802.1Q-2014 spec. The algorithm and how it affects latency are explained there, so go read it if you're curious 🌸

CBS is supposed to sit under another qdisc that maps packet flows to traffic classes. One example is mqprio(8) ✨

👑 PARAMETERS 👑

idleslope

ok this is the main tunable of the whole CBS algorithm 🔥 idleslope is the rate at which credits pile up, measured in kilobits per second, whenever there's at least one packet waiting to go. Packets get transmitted when the current credits are equal to or greater than zero. If there's nothing to send, the credits get reset to zero. This value basically decides how much bandwidth gets eaten.

⚠️ also, when you calculate idleslope, you have to count the entire packet size, including headers from every layer (MAC framing plus any physical layer overhead). See IEEE 802.1Q-2014 section 34.4.

here's an example 🎀 Say you've got an ethernet frame with 284 bytes of payload and no VLAN tags. You add 14 bytes for the Ethernet headers, 4 bytes for the Frame check sequence (CRC), and 20 bytes for the L1 overhead (that's 12 bytes of interpacket gap, 7 bytes of preamble, and 1 byte of start of frame delimiter). That gives you 322 bytes total, and that's the number used for the idleslope calculation 💅

sendslope

sendslope is the rate at which credits get used up while a transmission is happening 📉 It should be a negative number of kilobits per second. You calculate it like this (IEEE 802.1Q-2014 Section 8.6.8.2 item g):

sendslope = idleslope - port_transmit_rate

hicredit

hicredit is the maximum amount of credits (in bytes) that can build up 💜 It depends on the traffic that's interfering with you. max_interference_size is the biggest burst of traffic that can hold up a frame waiting to go out for this traffic class (IEEE 802.1Q-2014 Annex L, Equation L-3):

hicredit = max_interference_size * (idleslope / port_transmit_rate)

locredit

locredit is the minimum amount of credits that can be reached 🌈 It depends on the traffic going through this qdisc (IEEE 802.1Q-2014 Annex L, Equation L-2):

locredit = max_frame_size * (sendslope / port_transmit_rate)

offload

when offload is 1, cbs(8) will try to configure the network interface so the CBS algorithm runs on the controller 🧚 The default is 0.

🍓 EXAMPLES 🍓

CBS is how you enforce Quality of Service by limiting the data rate of a traffic class 🎀 To split packets into traffic classes, you can use mqprio(8), and you set it up like this:

# tc qdisc add dev eth0 handle 100: parent root mqprio num_tc 3 \
     map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 \
     queues 1@0 1@1 2@2 \
     hw 0

Next, to replace the current queueing discipline on traffic class number 0 with CBS, run:

# tc qdisc replace dev eth0 parent 100:4 cbs \
     locredit -1470 hicredit 30 sendslope -980000 idleslope 20000

those values come from these parameters: idleslope is 20mbit/s, the transmission rate is 1Gbit/s, and the maximum interfering frame size is 1500 bytes 🫶

💅 AUTHORS 💅

Vinicius Costa Gomes <vinicius.gomes@intel.com> 🌸

okay that's the whole CBS tea ☕ From iproute2, dated 18 Sept 2017. Go forth and shape your traffic, bestie 💖🦋✨