# tc-police

## 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).
    


* * *