[Cake] [RFC PATCH 2/2] add cake man page

Dave Taht dave.taht at gmail.com
Fri Nov 17 16:24:51 EST 2017


---
 man/man8/tc-cake.8 | 530 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 530 insertions(+)
 create mode 100644 man/man8/tc-cake.8

diff --git a/man/man8/tc-cake.8 b/man/man8/tc-cake.8
new file mode 100644
index 0000000..92b4e41
--- /dev/null
+++ b/man/man8/tc-cake.8
@@ -0,0 +1,530 @@
+.TH CAKE 8 "15 October 2015" "iproute2" "Linux"
+.SH NAME
+CAKE \- COMMON Applications Kept Enhanced (CAKE)
+.SH SYNOPSIS
+.B tc qdisc ... cake
+.br
+	[
+.B bandwidth RATE
+|
+.B unlimited
+|
+.B autorate_ingress
+]
+.br
+	[
+.B rtt
+TIME |
+.B datacenter
+|
+.B lan
+|
+.B metro
+|
+.B regional
+|
+.B internet
+|
+.B oceanic
+|
+.B satellite
+|
+.B interplanetary
+]
+.br
+	[
+.B besteffort
+|
+.B squash
+|
+.B precedence
+|
+.B diffserv8
+|
+.B diffserv4
+|
+.B diffserv3
+|
+.B diffserv-llt
+]
+.br
+	[
+.B flowblind
+|
+.B srchost
+|
+.B dsthost
+|
+.B hosts
+|
+.B flows
+|
+.B dual-srchost
+|
+.B dual-dsthost
+|
+.B triple-isolate
+]
+.br
+	[
+.B nat
+|
+.B nonat
+]
+.br
+	[
+.B ptm
+|
+.B atm
+|
+.B noatm
+]
+.br
+	[
+.B overhead BYTES
+|
+.B conservative
+|
+.B raw
+]
+.br
+	[
+.B mpu
+BYTES
+]
+.br
+	[
+.B memlimit
+SIZE
+]
+
+.SH DESCRIPTION
+CAKE (Common Applications Kept Enhanced) is a shaping queue discipline which uses both AQM and FQ.
+It combines COBALT, which is an AQM algorithm combining Codel and BLUE,
+a shaper which operates in deficit mode, and a variant of DRR for flow isolation.
+An 8-way set-associative hashing is used to virtually eliminate hash collisions.
+Priority queuing is available through a simplified diffserv implementation.
+Overhead compensation for various encapsulation schemes is tightly integrated.
+
+All settings are optional; the default settings are chosen to be sensible in most common deployments.
+Most people will only need to set the
+.B bandwidth
+parameter to get useful results, but reading the
+.B Overhead Compensation
+and
+.B Round Trip Time
+sections is strongly encouraged.
+
+
+.SH SHAPER PARAMETERS
+CAKE uses a deficit-mode shaper, which does not exhibit the initial burst typical of token-bucket shapers.
+It will automatically burst precisely as much as required to maintain the configured throughput.
+As such, it is very straightforward to configure.
+.PP
+.B unlimited
+(default)
+.br
+	No limit on the bandwidth.
+.PP
+.B bandwidth
+RATE
+.br
+	Set the shaper bandwidth.  See
+.BR tc(8)
+or examples below for details of the RATE value.
+.PP
+.B autorate_ingress
+.br
+	Automatic capacity estimation based on traffic arriving at this qdisc.
+This is most likely to be useful with cellular links, which tend to change quality randomly.  A
+.B bandwidth
+parameter can be used in conjunction to specify an initial estimate.
+The shaper will periodically be set to a bandwidth slightly below the estimated rate.
+This estimator cannot estimate the bandwidth of links downstream of itself.
+
+.SH OVERHEAD COMPENSATION PARAMETERS
+The size of each packet on the wire may differ from that seen by Linux.
+The following parameters allow CAKE to compensate for this difference by internally considering
+each packet to be bigger than Linux informs it.
+To assist users who are not expert network engineers, keywords have been provided
+to represent a number of common link technologies.
+
+.SS	Manual Overhead Specification
+.B overhead
+BYTES
+.br
+	Adds BYTES to the size of each packet.  BYTES may be negative; values between -64 and 256 (inclusive) are accepted.
+.PP
+.B mpu
+BYTES
+.br
+	Rounds each packet (including overhead) up to a minimum length BYTES. BYTES may not be negative; values between 0 and 256 (inclusive) are accepted.
+.PP
+.B atm
+.br
+	Compensates for ATM cell framing, which is normally found on ADSL links.  This is performed after the
+.B overhead
+parameter above.  ATM uses fixed 53-byte cells, each of which can carry 48 bytes payload.
+.PP
+.B ptm
+.br
+	Compensates for PTM encoding, which is normally found on VDSL2 links and uses a 64b/65b encoding scheme.
+.PP
+.B noatm
+.br
+	Disables ATM and PTM compensation.
+
+.SS	Failsafe Overhead Keywords
+These two keywords are provided for quick-and-dirty setup.  Use them if you can't be bothered to read the rest of this section.
+.PP
+.B raw
+(default)
+.br
+	Turns off all overhead compensation in CAKE.  The packet size reported by Linux will be used directly.
+.PP
+	Other overhead keywords may be added after "raw".  The effect of this is to make the overhead compensation operate
+relative to the reported packet size, not the underlying IP packet size.
+.PP
+.B conservative
+.br
+	Compensates for more overhead than is likely to occur on any widely-deployed link technology.
+.br
+	Equivalent to
+.B overhead 48 atm.
+
+.SS ADSL Overhead Keywords
+Most ADSL modems have a way to check which framing scheme is in use.
+Often this is also specified in the settings document provided by the ISP.
+The keywords in this section are intended to correspond with these sources of information.
+All of them implicitly set the
+.B atm
+flag.
+.PP
+.B pppoa-vcmux
+.br
+	Equivalent to
+.B overhead 10 atm
+.PP
+.B pppoa-llc
+.br
+	Equivalent to
+.B overhead 14 atm
+.PP
+.B pppoe-vcmux
+.br
+	Equivalent to
+.B overhead 32 atm
+.PP
+.B pppoe-llcsnap
+.br
+	Equivalent to
+.B overhead 40 atm
+.PP
+.B bridged-vcmux
+.br
+	Equivalent to
+.B overhead 24 atm
+.PP
+.B bridged-llcsnap
+.br
+	Equivalent to
+.B overhead 32 atm
+.PP
+.B ipoa-vcmux
+.br
+	Equivalent to
+.B overhead 8 atm
+.PP
+.B ipoa-llcsnap
+.br
+	Equivalent to
+.B overhead 16 atm
+.PP
+See also the Ethernet Correction Factors section below.
+
+.SS VDSL2 Overhead Keywords
+ATM was dropped from VDSL2 in favour of PTM, which is a much more straightforward framing scheme.
+Some ISPs retained PPPoE for compatibility with their existing back-end systems.
+.PP
+.B pppoe-ptm
+.br
+	Equivalent to
+.B overhead 27 ptm
+.PP
+.B bridged-ptm
+.br
+	Equivalent to
+.B overhead 19 ptm
+.PP
+See also the Ethernet Correction Factors section below.
+
+.SS DOCSIS Cable Overhead Keyword
+DOCSIS is the universal standard for providing Internet service over cable-TV infrastructure.
+
+In this case, the actual on-wire overhead is less important than the packet size the head-end equipment uses for shaping and metering.
+This is specified to be an Ethernet frame including the CRC (aka FCS).
+.PP
+.B docsis
+.br
+	Equivalent to
+.B overhead 18 mpu 64 noatm
+
+.SS Ethernet Overhead Keywords
+.PP
+.B ethernet
+.br
+	Accounts for Ethernet's preamble, inter-frame gap, and Frame Check Sequence.  Use this keyword when the bottleneck being shaped for is an actual Ethernet cable.
+.br
+	Equivalent to
+.B overhead 38 mpu 84 noatm
+.PP
+.B ether-vlan
+.br
+	Adds 4 bytes to the overhead compensation, accounting for a VLAN header appended to the Ethernet frame header.  NB: Some ISPs use one or even two of these within PPPoE; this keyword may be repeated as necessary to express this.
+
+.SH ROUND TRIP TIME PARAMETERS
+Active Queue Management (AQM) consists of embedding congestion signals in the packet flow, which
+receivers use to instruct senders to slow down when the queue is persistently occupied.  CAKE
+uses ECN signalling when available, and packet drops otherwise, according to a combination of the
+Codel and BLUE AQM algorithms called COBALT.
+
+Very short latencies require a very rapid AQM response to adequately control latency.
+However, such a rapid response tends to impair throughput when the actual RTT is relatively long.
+CAKE allows specifying the RTT it assumes for tuning various parameters.  Actual RTTs within
+an order of magnitude of this will generally work well for both throughput and latency management.
+.PP
+.B rtt
+TIME
+.br
+	Manually specify an RTT.
+.PP
+.B datacenter
+.br
+	For extremely high-performance networks only.  Equivalent to
+.B rtt 100us.
+.PP
+.B lan
+.br
+	For typical Ethernet and Wi-Fi networks, at home or in the office.  Don't use this
+when shaping for an Internet access link.  Equivalent to
+.B rtt 1ms.
+.PP
+.B metro
+.br
+	For traffic mostly within a single city.  Equivalent to
+.B rtt 10ms.
+.PP
+.B regional
+.br
+	For traffic mostly within a European-sized country.  Equivalent to
+.B rtt 30ms.
+.PP
+.B internet
+(default)
+.br
+	This is suitable for typical Internet traffic.  Equivalent to
+.B rtt 100ms.
+.PP
+.B oceanic
+.br
+	For Internet traffic with generally above-average latency, such as that suffered by Australasian residents.  Equivalent to
+.B rtt 300ms.
+.PP
+.B satellite
+.br
+	For traffic via geostationary satellites.  Equivalent to
+.B rtt 1000ms.
+.PP
+.B interplanetary
+.br
+	So named because Jupiter is about 1 light-hour from Earth.  Use this to (almost) completely disable AQM actions.  Equivalent to
+.B rtt 3600s.
+
+.SH FLOW ISOLATION PARAMETERS
+With flow isolation enabled, CAKE places packets from different flows into different queues,
+each of which carries its own AQM state.  Packets from each queue are then delivered fairly,
+according to a DRR++ algorithm which minimises latency for "sparse" flows.  CAKE uses a set-associative
+hashing algorithm to minimise flow collisions.
+
+These keywords specify whether fairness based on source address, destination address,
+individual flows, or any combination of those is desired.
+.PP
+.B flowblind
+.br
+	Disables flow isolation; all traffic passes through a single queue for each tin.
+.PP
+.B srchost
+.br
+	Flows are defined only by source address.  Could be useful on the egress path of an ISP backhaul.
+.PP
+.B dsthost
+.br
+	Flows are defined only by destination address.  Could be useful on the ingress path of an ISP backhaul.
+.PP
+.B hosts
+.br
+	Flows are defined by source-destination host pairs.  This is host isolation, rather than flow isolation.
+.PP
+.B flows
+.br
+	Flows are defined by the entire 5-tuple of source address, destination address, transport
+protocol, source port and destination port.  This is the type of flow isolation performed by
+SFQ and fq_codel.
+.PP
+.B dual-srchost
+.br
+	Flows are defined by the 5-tuple, and fairness is applied first over source addresses, then
+over individual flows.  Good for use on egress traffic from a LAN to the internet, where it'll
+prevent any one LAN host from monopolising the uplink, regardless of the number of flows they use.
+.PP
+.B dual-dsthost
+.br
+	Flows are defined by the 5-tuple, and fairness is applied first over destination addresses, then
+over individual flows.  Good for use on ingress traffic to a LAN from the internet, where it'll
+prevent any one LAN host from monopolising the downlink, regardless of the number of flows they use.
+.PP
+.B triple-isolate
+(default)
+.br
+	Flows are defined by the 5-tuple, and fairness is applied over source *and* destination addresses
+intelligently (ie. not merely by host-pairs), and also over individual flows.  Use this if you're
+not certain whether to use dual-srchost or dual-dsthost; it'll do both jobs at once, preventing
+any one host on *either* side of the link from monopolising it with a large number of flows.
+.PP
+.B nat
+.br
+	Instructs Cake to perform a NAT lookup before applying flow-isolation rules, to determine the true
+addresses and port numbers of the packet, to improve fairness between hosts "inside" the NAT.  This
+has no practical effect in "flowblind" or "flows" modes, or if NAT is performed on a different host.
+.PP
+.B nonat
+(default)
+.br
+	Cake will not perform a NAT lookup.  Flow isolation will be performed using the addresses and
+port numbers directly visible to the interface Cake is attached to.
+
+.SH PRIORITY QUEUE PARAMETERS
+CAKE can divide traffic into "tins" based on the Diffserv field.  Each tin has its own independent
+set of flow-isolation queues, and is serviced based on a WRR algorithm.  To avoid perverse Diffserv
+marking incentives, tin weights have a "priority sharing" value when bandwidth used by that tin is
+below a threshold, and a lower "bandwidth sharing" value when above.  Bandwidth is compared against
+the threshold using the same algorithm as the deficit-mode shaper.
+
+Detailed customisation of tin parameters is not provided.  The following presets perform all necessary
+tuning, relative to the current shaper bandwidth and RTT settings.
+.PP
+.B besteffort
+.br
+	Disables priority queuing by placing all traffic in one tin.
+.PP
+.B precedence
+.br
+	Enables legacy interpretation of TOS "Precedence" field.  Use of this preset on the modern Internet is firmly discouraged.
+.PP
+.B diffserv-llt
+.br
+	Provides a "Latency-Loss Tradeoff" implementation with five tins:
+.br
+		Low Loss (TOS1, TOS2), 100% threshold, increased Codel target.
+.br
+		Best Effort (general), 100% threshold, normal Codel target & interval.
+.br
+		Low Latency (TOS4, TOS5, VA, EF), 100% threshold, reduced Codel interval.
+.br
+		Bulk (CS1), 6.25% threshold, normal Codel target & interval.
+.br
+		Net Control (CS6, CS7), 6.25% threshold, increased Codel target & interval.
+.PP
+.B diffserv4
+.br
+	Provides a general-purpose Diffserv implementation with four tins:
+.br
+		Bulk (CS1), 6.25% threshold, generally low priority.
+.br
+		Best Effort (general), 100% threshold.
+.br
+		Video (AF4x, AF3x, CS3, AF2x, CS2, TOS4, TOS1), 50% threshold.
+.br
+		Voice (CS7, CS6, EF, VA, CS5, CS4), 25% threshold.
+.PP
+.B diffserv3
+(default)
+.br
+	Provides a simple, general-purpose Diffserv implementation with three tins:
+.br
+		Bulk (CS1), 6.25% threshold, generally low priority.
+.br
+		Best Effort (general), 100% threshold.
+.br
+		Voice (CS7, CS6, EF, VA, TOS4), 25% threshold, reduced Codel interval.
+
+.SH OTHER PARAMETERS
+.B memlimit
+LIMIT
+.br
+	Limit the memory consumed by Cake to LIMIT bytes. Note that this does not
+translate directly to queue size, as there is some overhead in the data
+structures containing the packets, especially for small packets.
+
+	By default, the limit is calculated based on the bandwidth and RTT settings.
+
+
+.SH EXAMPLES
+#tc qdisc add dev enp3s0 root cake bandwidth 30mbit
+.br
+#tc -s qdisc show dev enp3s0
+.br
+qdisc cake 8001: root refcnt 2 bandwidth 30Mbit diffserv4 flows rtt 100.0ms raw
+ Sent 0 bytes 0 pkt (dropped 0, overlimits 0 requeues 0)
+ backlog 0b 0p requeues 0
+capacity estimate: 30Mbit
+.br
+             Tin 0       Tin 1       Tin 2       Tin 3
+.br
+  thresh      30Mbit   28125Kbit   22500Kbit    7500Kbit
+.br
+  target       5.0ms       5.0ms       5.0ms       5.0ms
+.br
+interval     100.0ms     100.0ms     100.0ms     100.0ms
+.br
+Pk-delay         0us         0us         0us         0us
+.br
+Av-delay         0us         0us         0us         0us
+.br
+Sp-delay         0us         0us         0us         0us
+.br
+  pkts             0           0           0           0
+.br
+  bytes            0           0           0           0
+.br
+way-inds           0           0           0           0
+.br
+way-miss           0           0           0           0
+.br
+way-cols           0           0           0           0
+.br
+  drops            0           0           0           0
+.br
+  marks            0           0           0           0
+.br
+Sp-flows           0           0           0           0
+.br
+Bk-flows           0           0           0           0
+.br
+last-len           0           0           0           0
+.br
+max-len            0           0           0           0
+.br
+
+
+.SH SEE ALSO
+.BR tc (8),
+.BR tc-codel (8),
+.BR tc-fq_codel (8),
+.BR tc-red (8)
+
+.SH AUTHORS
+CAKE was implemented by Jonathan Morton, with contributions from Dave Taht,
+Kevin Darbyshire-Bryant, Toke Hoiland-Jorgensen and Loganaden Velvindron.
+This manual page was written by Loganaden Velvindron. Please report corrections
+to the Linux Networking mailing list <netdev at vger.kernel.org>.
-- 
2.7.4



More information about the Cake mailing list