[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