home | help 
MOD_CC(4)		     Kernel Interfaces Manual		       MOD_CC(4)

NAME
     mod_cc -- Modular congestion control

DESCRIPTION
     The  modular  congestion control framework allows the TCP implementation to
     dynamically change the congestion control algorithm used by new and  exist-
     ing connections.  Algorithms are identified by a unique ascii(7) name.  Al-
     gorithm modules can be compiled into the kernel or loaded as kernel modules
     using the kld(4) facility.

     The  default algorithm is CUBIC, and all connections use the default unless
     explicitly overridden using the TCP_CONGESTION socket  option  (see  tcp(4)
     for  details).   The  default can be changed using a sysctl(3) MIB variable
     detailed in the "MIB Variables" section below.

     Algorithm specific parameters can be set or queried using the TCP_CCALGOOPT
     socket option (see tcp(4) for details).  Callers must pass a pointer to  an
     algorithm specific data, and specify its size.

     Unloading	a congestion control module will fail if it is used as a default
     by any Vnet.  When unloading a module, the Vnet default is used to switch a
     connection to an alternate congestion control.  Note that the  new  conges-
     tion  control  module  may fail to initialize its internal memory, if so it
     will fail the module unload.  If this occurs often times retrying	the  un-
     load  will succeed since the temporary memory shortage as the new CC module
     malloc's memory, that prevented the switch is often transient.

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

     available			     Read-only list of currently available  con-
				     gestion control algorithms by name.

     algorithm			     Returns the current default congestion con-
				     trol  algorithm  when read, and changes the
				     default  when  set.   When  attempting   to
				     change the default algorithm, this variable
				     should be set to one of the names listed by
				     the net.inet.tcp.cc.available MIB variable.

     abe			     Enable  support  for RFC 8511, which alters
				     the window decrease factor applied  to  the
				     congestion  window  in  response  to an ECN
				     congestion  signal.   Refer  to  individual
				     congestion  control  man pages to determine
				     if they implement support for ABE	and  for
				     configuration details.

     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.

     hystartplusplus.bblogs	     This  boolean controls if black box logging
				     will be done for hystart++ events.  If  set
				     to  zero  (the  default) no logging is per-
				     formed.  If set to one then black box  logs
				     will be generated on all hystart++ events.

     hystartplusplus.css_rounds      This  value  controls  the number of rounds
				     that  CSS	runs  for.   The  default  value
				     matches the current internet-draft of 5.

     hystartplusplus.css_growth_div  This  value controls the divisor applied to
				     slowstart during CSS.   The  default  value
				     matches the current internet-draft of 4.

     hystartplusplus.n_rttsamples    This  value  controls  how many rtt samples
				     must be collected in each	round  for  hys-
				     tart++  to  be  active.   The default value
				     matches the current internet-draft of 8.

     hystartplusplus.maxrtt_thresh   This value controls the maximum  rtt  vari-
				     ance  clamp  when	considering  if  CSS  is
				     needed.  The default value matches the cur-
				     rent internet-draft of 16000 (in  microsec-
				     onds).   For further explanation please see
				     the internet-draft.

     hystartplusplus.minrtt_thresh   This value controls the minimum  rtt  vari-
				     ance  clamp  when	considering  if  CSS  is
				     needed.  The default value matches the cur-
				     rent internet-draft of 4000  (in  microsec-
				     onds).   For further explanation please see
				     the internet-draft.

     Each congestion control module may also expose other MIB variables to  con-
     trol  their  behaviour.   Note that both NewReno and CUBIC now support Hys-
     tart++ based on the version 3 of the internet-draft.

Kernel Configuration
     All of the available congestion control modules may also be loaded via ker-
     nel configuration options.  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 are not met.

Kernel Configuration Options
     The framework exposes the following 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.

     CC_VEGAS	 This  directive  loads  the vegas congestion control algorithm,
		 note that this algorithm also requires the TCP_HHOOK option  as
		 well.

     CC_CDG	 This directive loads the cdg congestion control algorithm, 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, note
		 that this algorithm also requires the TCP_HHOOK option as well.

     CC_CHD	 This directive loads the chd congestion control algorithm, note
		 that this algorithm also requires the TCP_HHOOK option as well.

     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 Cisco University Research Program
     Fund at Community Foundation Silicon Valley.

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 Stew-
     art whilst working on the NewTCP research project at  Swinburne  University
     of Technology's Centre for Advanced Internet Architectures, Melbourne, Aus-
     tralia,  which  was made possible in part by a grant from the Cisco Univer-
     sity Research Program Fund at Community Foundation  Silicon  Valley.   More
     details are available at:

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

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>.

FreeBSD 15.1		       September 13, 2022		       MOD_CC(4)
home | help