NAME

       police - policing action

SYNOPSIS

       tc  ...  action  police  [  rate  RATE  burst  BYTES[/BYTES] ] [ pkts_rate RATE pkts_burst
               PACKETS] [ mtu BYTES[/BYTES] ] [ peakrate RATE ] [ overhead BYTES  ]  [  linklayer
               TYPE ] [ CONTROL ]

       tc ... filter ... [ estimator SAMPLE AVERAGE ] action police avrate RATE [ CONTROL ]

       CONTROL := conform-exceed EXCEEDACT[/NOTEXCEEDACT

       EXCEEDACT/NOTEXCEEDACT  :=  {  pipe  |  ok  |  reclassify  |  drop | continue | goto chain
               CHAIN_INDEX }

DESCRIPTION

       The police action allows limiting of the byte or packet rate of  traffic  matched  by  the
       filter it is attached to.

       There  are two different algorithms available to measure the byte rate: The first one uses
       an internal dual token bucket and is configured using  the  rate,  burst,  mtu,  peakrate,
       overhead and linklayer parameters. The second one uses an in-kernel sampling mechanism. It
       can be fine-tuned using the estimator filter parameter.

       There is one algorithm available to measure packet rate and it is  similar  to  the  first
       algorithm  described  for  byte  rate.  It  is configured using the pkt_rate and pkt_burst
       parameters.

       At least one of the rate and pkt_rate parameters must be configured.

OPTIONS

       rate RATE
              The maximum byte rate of packets passing this action. Those exceeding  it  will  be
              treated as defined by the conform-exceed option.

       burst BYTES[/BYTES]
              Set  the  maximum allowed burst in bytes, optionally followed by a slash ('/') sign
              and cell size which must be a power of 2.

       pkt_rate RATE
              The maximum packet rate or packets passing this action. Those exceeding it will  be
              treated as defined by the conform-exceed option.

       pkt_burst PACKETS
              Set the maximum allowed burst in packets.

       mtu BYTES[/BYTES]
              This is the maximum packet size handled by the policer (larger ones will be handled
              like they exceeded the configured rate). Setting this value correctly will  improve
              the  scheduler's precision.  Value formatting is identical to burst above. Defaults
              to unlimited.

       peakrate RATE
              Set the maximum bucket depletion rate, exceeding rate.

       avrate RATE
              Make use of an in-kernel bandwidth rate estimator and match the given RATE  against
              it.

       overhead BYTES
              Account  for  protocol overhead of encapsulating output devices when computing rate
              and peakrate.

       linklayer TYPE
              Specify the link layer type.  TYPE may be one of ethernet  (the  default),  atm  or
              adsl  (which  are synonyms). It is used to align the precomputed rate tables to ATM
              cell sizes, for ethernet no action is taken.

       estimator SAMPLE AVERAGE
              Fine-tune the in-kernel packet rate estimator.  SAMPLE and AVERAGE are time  values
              and  control  the  frequency  in  which samples are taken and over what timespan an
              average is built.

       conform-exceed EXCEEDACT[/NOTEXCEEDACT]
              Define how to handle packets which  exceed  or  conform  the  configured  bandwidth
              limit. Possible values are:

              continue
                     Don't do anything, just continue with the next action in line.

              drop   Drop the packet immediately.

              shot   This is a synonym to drop.

              ok     Accept the packet. This is the default for conforming packets.

              pass   This is a synonym to ok.

              reclassify
                     Treat  the  packet  as non-matching to the filter this action is attached to
                     and continue with the next filter in line (if any). This is the default  for
                     exceeding packets.

              pipe   Pass the packet to the next action in line.

EXAMPLES

       A  typical application of the police action is to enforce ingress traffic rate by dropping
       exceeding packets. Although better done on the sender's side, especially in scenarios with
       lack  of  peer  control (e.g. with dial-up providers) this is often the best one can do in
       order to keep latencies low under high load. The  following  establishes  input  bandwidth
       policing to 1mbit/s using the ingress qdisc and u32 filter:

              # tc qdisc add dev eth0 handle ffff: ingress
              # tc filter add dev eth0 parent ffff: u32 \
                   match u32 0 0 \
                   police rate 1mbit burst 100k

       As  an  action  can not live on it's own, there always has to be a filter involved as link
       between qdisc and action. The example above uses u32 for  that,  which  is  configured  to
       effectively match any packet (passing it to the police action thereby).

SEE ALSO

       tc(8)