From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-pf0-x22b.google.com (mail-pf0-x22b.google.com [IPv6:2607:f8b0:400e:c00::22b]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.bufferbloat.net (Postfix) with ESMTPS id C198B3BA8E for ; Fri, 17 Nov 2017 16:25:01 -0500 (EST) Received: by mail-pf0-x22b.google.com with SMTP id q4so2797788pfg.13 for ; Fri, 17 Nov 2017 13:25:01 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=FccIr5uqXykKty+4KTeJ7xRt8rUfPjNgNy/7YKYx/Zg=; b=NfYGNuvwvstulhVXp13JphbIl61nooYrCFqScAw6HkRIHmAPSUKkSoRfE8gwlXmzZH huz83r9N+qabJUZIs7RvQ0E7e+XX9zT67z2XqDnwAZjmLw6bI89T0fjC4QTeh/Li8alW G08OT2hok8BQA5fCrQ8G5N/W7OJ19ttqq+8nPTx1AGqgWMThEAmahTNY0kKR35ah+35b x3Ya+CdCMiMfLywAqYfN0QN933/v30Xutm8qAgT/Q5NVLuHKohXihd9Q3ed7PrdbL98u W49+ZygHWfRdUcfpcUnQSll33vNPf1gU+FqPiK3WeiepMwPWaEUeCz0l+23SnhMCrXQ1 LrdQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=FccIr5uqXykKty+4KTeJ7xRt8rUfPjNgNy/7YKYx/Zg=; b=VjBRz+y2XL0YAJMgzBFyKwvIkSDD4UVrC70okHEEnudWnY+bhIITfY2ijni5DM3KWM IRXsqo6GdnuGevyaU3rI3m46SskGO3qOX9fN/Cy2y/qPv1kSqIyqdZbFRdqSKz80pKZE oVaByQNQe4jQsyCPcUqwO4ZnwW6CjMIomTYKaaiY1kQW3zZ+g2xs3UA2RW+dva+lrmNr J8PY0O9a7WJ30DmW8vKDIfJUnFyeALWwge5zgvnNaI5ml0wn1aOfd6Z4wchyDEw/LL3M 0ZKyON+h9ENMMH1QGqkxaXSe2G+E05PgRBUxUWCZwWwk2sXGE1T8qXtbfq1Vfz7O/jiq uUMA== X-Gm-Message-State: AJaThX6v17lASOZsZKdlr/ni++sGWJtIFR+n5cRtXFcLsNObqNJU5EQL 0LC7sNsBBIK2d8YK8O/BwCkKEQ== X-Google-Smtp-Source: AGs4zMbLRHhUXoxphJ1MRvoBZC24R2NmDxR/bBle9/+q2A4g9BgxqrktICUjvtup/Ef6P+nyFBb6+A== X-Received: by 10.84.128.73 with SMTP id 67mr6377564pla.96.1510953900504; Fri, 17 Nov 2017 13:25:00 -0800 (PST) Received: from nemesis.lab.teklibre.com (c-24-6-113-161.hsd1.ca.comcast.net. [24.6.113.161]) by smtp.gmail.com with ESMTPSA id l14sm8133880pgn.35.2017.11.17.13.24.58 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 17 Nov 2017 13:24:58 -0800 (PST) From: Dave Taht To: cake@lists.bufferbloat.net Date: Fri, 17 Nov 2017 13:24:51 -0800 Message-Id: <1510953891-11984-3-git-send-email-dave.taht@gmail.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1510953891-11984-1-git-send-email-dave.taht@gmail.com> References: <1510953891-11984-1-git-send-email-dave.taht@gmail.com> Subject: [Cake] [RFC PATCH 2/2] add cake man page X-BeenThere: cake@lists.bufferbloat.net X-Mailman-Version: 2.1.20 Precedence: list List-Id: Cake - FQ_codel the next generation List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 17 Nov 2017 21:25:02 -0000 --- 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 . -- 2.7.4