TC(8) Linux TC(8) NAME tbf−TokenBucketFilter SYNOPSIS tcqdisc...tbfraterateburstbytes/cell(latencyms|limitbytes)[mpubytes[ peakrateratemtubytes/cell]] burstisalsoknownasbufferandmaxburst.mtuisalsoknownasminburst. DESCRIPTION TheTokenBucketFilterisaclasslessqueueingdisciplineavailablefortrafficcontrolwiththe tc(8)command. TBFisapureshaperandneverschedulestraffic.Itisnon-work-conservingandmaythrottle itself,althoughpacketsareavailable,toensurethattheconfiguredrateisnotexceeded.Onall platformsexceptforAlpha,itisabletoshapeupto1mbit/sofnormaltrafficwithidealminimal burstiness,sendingoutdataexactlyattheconfiguredrates. Muchhigherratesarepossiblebutatthecostoflosingtheminimalburstiness.Inthatcase,data isonaveragedequeuedattheconfiguredratebutmaybesentmuchfasteratmillisecond timescales.Becauseoffurtherqueueslivinginnetworkadaptors,thisisoftennotaproblem. Kernelswithahigher’HZ’canachievehigherrateswithperfectburstiness.OnAlpha,HZisten timeshigher,leadingtoa10mbit/slimittoperfection.Thesecalculationsholdforpacketsofon average1000bytes. ALGORITHM Asthenameimplies,trafficisfilteredbasedontheexpenditureoftokens.Tokensroughlycorrespondtobytes,withtheadditionalconstraintthateachpacketconsumessometokens,nomatter howsmallitis.Thisreflectsthefactthatevenazero-sizedpacketoccupiesthelinkforsometime. Oncreation,theTBFisstockedwithtokenswhichcorrespondtotheamountoftrafficthatcan beburstinonego.Tokensarriveatasteadyrate,untilthebucketisfull. Ifnotokensareavailable,packetsarequeued,uptoaconfiguredlimit.TheTBFnowcalculates thetokendeficit,andthrottlesuntilthefirstpacketinthequeuecanbesent. Ifitisnotacceptabletoburstoutpacketsatmaximumspeed,apeakratecanbeconfiguredto limitthespeedatwhichthebucketempties.ThispeakrateisimplementedasasecondTBFwith averysmallbucket,sothatitdoesn’tburst. Toachieveperfection,thesecondbucketmaycontainonlyasinglepacket,whichleadstotheearliermentioned1mbit/slimit. Thislimitiscausedbythefactthatthekernelcanonlythrottleforatminimum1’jiffy’,which dependsonHZas1/HZ.Forperfectshaping,onlyasinglepacketcangetsentperjiffy-for HZ=100,thismeans100packetsofonaverage1000byteseach,whichroughlycorrespondsto 1mbit/s. PARAMETERS Seetc(8)forhowtospecifytheunitsofthesevalues. limitorlatency Limitisthenumberofbytesthatcanbequeuedwaitingfortokenstobecomeavailable. Youcanalsospecifythistheotherwayaroundbysettingthelatencyparameter,which specifiesthemaximumamountoftimeapacketcansitintheTBF.Thelattercalculation iproute2 13December2001 1 TC(8) Linux TC(8) takesintoaccountthesizeofthebucket,therateandpossiblythepeakrate(ifset).These twoparametersaremutuallyexclusive. burstAlsoknownasbufferormaxburst.Sizeofthebucket,inbytes.Thisisthemaximum amountofbytesthattokenscanbeavailableforinstantaneously.Ingeneral,largershapingratesrequirealargerbuffer.For10mbit/sonIntel,youneedatleast10kbytebufferif youwanttoreachyourconfiguredrate! Ifyourbufferistoosmall,packetsmaybedroppedbecausemoretokensarrivepertimer tickthanfitinyourbucket.Theminimumbuffersizecanbecalculatedbydividingthe ratebyHZ. Tokenusagecalculationsareperformedusingatablewhichbydefaulthasaresolutionof 8packets.Thisresolutioncanbechangedbyspecifyingthecellsizewiththeburst.For example,tospecifya6000bytebufferwitha16bytecellsize,setaburstof6000/16.You willprobablyneverhavetosetthis.Mustbeanintegralpowerof2. mpuAzero-sizedpacketdoesnotusezerobandwidth.Forethernet,nopacketuseslessthan 64bytes.TheMinimumPacketUnitdeterminestheminimaltokenusage(specifiedin bytes)forapacket.Defaultstozero. rateThespeedknob.Seeremarksaboveaboutlimits!Seetc(8)forunits. Furthermore,ifapeakrateisdesired,thefollowingparametersareavailable: peakrate Maximumdepletionrateofthebucket.Limitedto1mbit/sonIntel,10mbit/sonAlpha. Thepeakratedoesnotneedtobeset,itisonlynecessaryifperfectmillisecondtimescale shapingisrequired. mtu/minburst Specifiesthesizeofthepeakratebucket.Forperfectaccuracy,shouldbesettotheMTU oftheinterface.Ifapeakrateisneeded,butsomeburstinessisacceptable,thissizecan beraised.A3000byteminburstallowsaround3mbit/sofpeakrate,given1000bytepackets. Liketheregularburstsizeyoucanalsospecifyacellsize. EXAMPLE&USAGE ToattachaTBFwithasustainedmaximumrateof0.5mbit/s,apeakrateof1.0mbit/s,a5kilobytebuffer,withapre-bucketqueuesizelimitcalculatedsotheTBFcausesatmost70msof latency,withperfectpeakratebehaviour,issue: #tcqdiscadddeveth0roottbfrate0.5mbit\ burst5kblatency70mspeakrate1mbit\ minburst1540 SEEALSO tc(8) AUTHOR AlexeyN.Kuznetsov,<kuznet@ms2.inr.ac.ru>.Thismanpagemaintainedbyberthubert <ahu@ds9a.nl> iproute2 13December2001 2