MOD_CC(4)

📦
version 15.1 · 2 versions
, in freebsd 15.1, nixpkgs unstable

💖 MOD_CC(4) 💖

okay so bestie, welcome to the Kernel Interfaces Manual for mod_cc — the modular congestion control situation that's genuinely iconic. no cap, this one's a banger. let's get into it 🫶

✨ NAME ✨

mod_cc — the modular congestion control framework, aka the glow-up your TCP connections didn't know they needed 💅

🌸 DESCRIPTION 🌸

okay so here's the vibe: the modular congestion control framework lets the TCP implementation dynamically switch up the congestion control algorithm it's using — for both brand-new connections AND ones that are already out there living their lives. slay.

algorithms are identified by a unique ascii(7) name. algorithm modules can be compiled straight into the kernel OR loaded as kernel modules using the kld(4) facility. versatile queen behavior ✨

the default algorithm is CUBIC (main character energy fr), and all connections use the default unless you explicitly override it with the TCP_CONGESTION socket option (peep tcp(4) for the deets). you can change the default using a sysctl(3) MIB variable — more on that in the "MIB Variables" section below 👇

algorithm-specific params can be set or queried using the TCP_CCALGOOPT socket option (again, tcp(4) has the details). callers have to pass a pointer to algorithm-specific data AND specify its size. no skipping steps bestie 💀

⚠️ unloading a congestion control module will fail if it's being used as a default by any Vnet. when you unload a module, the Vnet default is used to switch a connection over to an alternate congestion control. and here's the tea: the new congestion control module might fail to initialize its internal memory — if that happens, the module unload fails too 😭

if this keeps happening, retrying the unload will eventually succeed, because the temporary memory shortage (the new CC module malloc's memory, and that shortage is what blocked the switch) is usually just a transient lil moment. it's giving "try again bestie" 🌈

🎀 MIB Variables 🎀

the framework exposes these variables in the net.inet.tcp.cc branch of the sysctl(3) MIB:

  • available — read-only list of the congestion control algorithms that are currently available, by name. window shopping energy 🛍️
  • algorithm — when you read it, it returns the current default congestion control algorithm. when you set it, it changes the default. pro tip: when you're trying to change the default, set this variable to one of the names listed by the net.inet.tcp.cc.available MIB variable. iykyk 💅
  • abe — enables support for RFC 8511, which alters the window decrease factor applied to the congestion window in response to an ECN congestion signal. check the individual congestion control man pages to see if they actually implement ABE support and for the config details, bestie 🔍
  • abe_frlossreduce — if non-zero, apply standard beta instead of ABE-beta during ECN-signalled congestion recovery episodes if loss also needs to be repaired. very specific, very demure ✨
  • hystartplusplus.bblogs — this boolean controls whether black box logging happens for hystart++ events. set it to zero (the default) and no logging is performed. set it to one and black box logs get generated on all hystart++ events. choose your fighter 🎀
  • hystartplusplus.css_rounds — controls the number of rounds that CSS runs for. the default value matches the current internet-draft, which is 5 🌸
  • hystartplusplus.css_growth_div — controls the divisor applied to slowstart during CSS. the default value matches the current internet-draft, which is 4 🦋
  • hystartplusplus.n_rttsamples — controls how many rtt samples must be collected in each round for hystart++ to be active. the default value matches the current internet-draft, which is 8 ⭐
  • hystartplusplus.maxrtt_thresh — controls the maximum rtt variance clamp when considering if CSS is needed. the default value matches the current internet-draft, which is 16000 (in microseconds). for further explanation, please see the internet-draft 📖
  • hystartplusplus.minrtt_thresh — controls the minimum rtt variance clamp when considering if CSS is needed. the default value matches the current internet-draft, which is 4000 (in microseconds). again, for further explanation, please see the internet-draft 💜

each congestion control module may also expose other MIB variables to control their behavior — so keep an eye out. and fun fact: both NewReno and CUBIC now support Hystart++ based on version 3 of the internet-draft. we love to see it 👑

🧚 Kernel Configuration 🧚

all of the available congestion control modules can also be loaded via kernel configuration options. here's the rule though, bestie: a kernel configuration is required to have at least one congestion control algorithm built into it via kernel option, and a system default specified. compilation of the kernel will fail if these two conditions aren't met. no exceptions 💀

🌈 Kernel Configuration Options 🌈

the framework exposes these kernel configuration options:

  • CC_NEWRENO — this directive loads the NewReno congestion control algorithm 💖
  • CC_CUBIC — this directive loads the CUBIC congestion control algorithm, and is included in GENERIC by default. she's the blueprint fr 🔥
  • CC_VEGAS — this directive loads the vegas congestion control algorithm. heads up: this algorithm also requires the TCP_HHOOK option as well 🫶
  • CC_CDG — this directive loads the cdg congestion control algorithm. again, note that this algorithm also requires the TCP_HHOOK option as well 💅
  • CC_DCTCP — this directive loads the dctcp congestion control algorithm ✨
  • CC_HD — this directive loads the hd congestion control algorithm. yep, you guessed it — this algorithm also requires the TCP_HHOOK option as well 🎀
  • CC_CHD — this directive loads the chd congestion control algorithm. and yes, this one also requires the TCP_HHOOK option as well, bestie 🦋
  • CC_HTCP — this directive loads the htcp congestion control algorithm 🌸
  • CC_DEFAULT — this directive specifies the string that represents the name of the system default algorithm. the GENERIC kernel defaults this to CUBIC ⭐

👀 SEE ALSO 👀

cc_cdg(4), cc_chd(4), cc_cubic(4), cc_dctcp(4), cc_hd(4), cc_htcp(4), cc_newreno(4), cc_vegas(4), tcp(4), config(5), config(8), mod_cc(9)

🏆 ACKNOWLEDGEMENTS 🏆

development and testing of this software were made possible in part by grants from the FreeBSD Foundation and the Cisco University Research Program Fund at Community Foundation Silicon Valley. absolute legends, no notes 🫡💜

📜 HISTORY 📜

the mod_cc modular congestion control framework first appeared in FreeBSD 9.0 ⭐

the framework was first released in 2007 by James Healy and Lawrence Stewart whilst working on the NewTCP research project at Swinburne University of Technology's Centre for Advanced Internet Architectures, Melbourne, Australia — which was made possible in part by a grant from the Cisco University Research Program Fund at Community Foundation Silicon Valley. more details are available at:

http://caia.swin.edu.au/urp/newtcp/

history really said "we been iconic" 💅

🌟 AUTHORS 🌟

the mod_cc facility was written by Lawrence Stewart <lstewart@FreeBSD.org>, James Healy <jimmy@deefa.com>, and David Hayes <david.hayes@ieee.org> 🫶

this manual page was written by David Hayes <david.hayes@ieee.org> and Lawrence Stewart <lstewart@FreeBSD.org> ✨

💌 and that's the whole thing, bestie! this page is from Debian, dated September 13, 2022, page MOD_CC(4) — now go forth and configure your congestion control like the absolute icon you are 💅🎀🦋
📦 where this page comes from