src/vnet/policer/policer.rst

   1 .. _policer:
   2
   3 Policing
   4 ========
   5
   6 VPP implements several policer types, that don't always conform
   7 to the related RFCs [#rfc2697]_ [#rfc2698]_ [#rfc4115]_.
   8 Only policers implemented in VPP will be presented, along with
   9 the differences they have compared to RFCs.
  10
  11 .. contents:: :local:
  12    :depth: 1
  13
  14
  15 1 rate 2 color (1r2c)
  16 ---------------------
  17
  18 This is the most straightforward policer. There is no RFC describing it,
  19 however we can found its description in many documentation [#juniper]_ [#cisco]_ .
  20
  21 A 1r2c policer is great to classify incoming packets into two categories:
  22 conforming packets (said green), and violating ones (said red).
  23
  24 Parameters
  25 ~~~~~~~~~~
  26
  27 To set-up such a policer, only two parameters are needed:
  28
  29 Committed Information Rate (CIR)
  30   Given in bytes per second, this parameter is the average
  31   throughput allowed by the policer.
  32
  33   It sets the limit between conforming arriving packets (those making the
  34   traffic fall below the CIR), and violating arriving packets
  35   (those making the traffic exceed the CIR).
  36
  37 Committed Burst Size (CBS)
  38   It represents the size (in bytes) of a token bucket used to allow
  39   some burstiness from the incoming traffic.
  40
  41 .. figure:: /_images/policer-1r2c-bucket.png
  42    :align: center
  43    :scale: 25%
  44
  45    Figure 1: 1r2c bucket filling logic
  46
  47 The committed token bucket (C) is filling up at CIR tokens (bytes)
  48 per second, up to CBS tokens. All overflowing tokens are lost.
  49
  50 Color-Blind algorithm
  51 ~~~~~~~~~~~~~~~~~~~~~
  52
  53 .. image:: /_images/policer-1r2c-blind.png
  54    :align: center
  55    :scale: 75%
  56
  57 |
  58
  59 Color-Aware algorithm
  60 ~~~~~~~~~~~~~~~~~~~~~
  61
  62 In online documentation, there is no trace of a color-aware 1r2c policer.
  63 However, VPP implementation allows such a thing.
  64
  65 .. image:: /_images/policer-1r2c-aware.png
  66    :align: center
  67    :scale: 75%
  68
  69 |
  70
  71
  72 1 rate 3 color (1r3c) RFC 2697 [#rfc2697]_
  73 ------------------------------------------
  74
  75 As for the `1 rate 2 color (1r2c)`_ policer, only one rate parameters is required
  76 to setup a 1r3c policer. However, such a policer adds another kind of packet category:
  77 exceeding ones (said yellow).
  78
  79 Parameters
  80 ~~~~~~~~~~
  81
  82 To set-up such a policer, three parameters are needed:
  83
  84 Committed Information Rate (CIR)
  85   As in the `1 rate 2 color (1r2c)`_ policer.
  86
  87 Committed Burst Size (CBS)
  88   As in the `1 rate 2 color (1r2c)`_ policer.
  89
  90 Excess Burst Size (EBS)
  91   It represents the size (in bytes) of a second token bucket used
  92   to allow an additional burstiness from the incoming traffic, when
  93   traffic as been below the CIR for some time.
  94
  95 .. figure:: /_images/policer-1r3c-bucket.png
  96    :align: center
  97    :scale: 25%
  98
  99    Figure 2: 1r3c buckets filling logic
 100
 101 The committed token bucket (C) is filling up at CIR tokens (bytes)
 102 per second, up to CBS tokens. When C is full, tokens are overflowing
 103 into the excess token bucket (E), up to EBS tokens. Only overflowing
 104 tokens from E are lost.
 105
 106 Color-Blind algorithm
 107 ~~~~~~~~~~~~~~~~~~~~~
 108
 109 .. image:: /_images/policer-1r3c-blind.png
 110    :align: center
 111    :scale: 75%
 112
 113 |
 114
 115 Color-Aware algorithm
 116 ~~~~~~~~~~~~~~~~~~~~~
 117
 118 .. image:: /_images/policer-1r3c-aware.png
 119    :align: center
 120    :scale: 75%
 121
 122 |
 123
 124 Notes
 125 ~~~~~
 126
 127 In the RFC 2697 [#rfc2697]_ describing the 1r3c policer, conforming (green) packets
 128 only consume tokens from the token bucket C. Whereas, in VPP, they also consume tokens from E.
 129
 130 One way to stick to the RFC is then to set the EBS parameter to be superior to CBS, so that
 131 EBS - CBS corresponds to the EBS from the RFC.
 132
 133 However, VPP does not enforce setting EBS > CBS, which could result in undesired behavior.
 134
 135 2 rate 3 color (2r3c) RFC 2698 [#rfc2698]_
 136 ------------------------------------------
 137
 138 Instead of setting the limit between yellow and red packets in terms of bursts,
 139 as it is done by `1 rate 3 color (1r3c) RFC 2697`_ policers, two rate policers introduce
 140 another rate parameter to discriminate between those two kinds of packets.
 141
 142 Parameters
 143 ~~~~~~~~~~
 144
 145 To set-up such a policer, four parameters are needed:
 146
 147 Committed Information Rate (CIR)
 148   As in the `1 rate 2 color (1r2c)`_ policer.
 149
 150 Committed Burst Size (CBS)
 151   As in the `1 rate 2 color (1r2c)`_ policer.
 152
 153 Peak Information Rate (PIR)
 154   Given in bytes per second, this parameter is the average
 155   throughput allowed by the policer when there is a peak in
 156   traffic.
 157
 158   It sets a second limit between exceeding arriving packets
 159   (those making the traffic fall below the PIR, but above CIR),
 160   and violating arriving packets (those making the traffic exceed the PIR).
 161
 162 Peak Burst Size (PBS)
 163   It represents the size (in bytes) of a second token bucket used
 164   to allow an additional peak traffic.
 165
 166 .. figure:: /_images/policer-2r3c-bucket.png
 167    :align: center
 168    :scale: 25%
 169
 170    Figure 2: 2r3c-rfc2698 buckets filling logic
 171
 172 The committed token bucket (C) is filling up at CIR tokens (bytes)
 173 per second, up to CBS tokens. In the meantime, the peak token bucket (P)
 174 is filling up at PIR tokens per second, up to PBS. All overflowing tokens
 175 from C and P are lost.
 176
 177 Color-Blind algorithm
 178 ~~~~~~~~~~~~~~~~~~~~~
 179
 180 .. image:: /_images/policer-2r3c-blind.png
 181    :align: center
 182    :scale: 75%
 183
 184 |
 185
 186 Color-Aware algorithm
 187 ~~~~~~~~~~~~~~~~~~~~~
 188
 189 .. image:: /_images/policer-2r3c-aware.png
 190    :align: center
 191    :scale: 50%
 192
 193 |
 194
 195 Notes
 196 ~~~~~
 197
 198 To have a working policer, the condition PIR >= CIR needs to hold.
 199 Indeed, since we assume that peak traffic should have a greater
 200 rate than committed ones.
 201
 202
 203 2 rate 3 color (2r3c) RFC 4115 [#rfc4115]_
 204 ------------------------------------------
 205
 206 The 2r3c-RFC4115 is an allowed choice by VPP. However, there is currently
 207 no implementation of such a policer. Hence, the only two rate policer VPP
 208 implements is the `2 rate 3 color (2r3c) RFC 2698`_ policer.
 209
 210
 211 .. rubric:: References:
 212
 213 .. [#juniper] https://www.juniper.net/documentation/us/en/software/junos/traffic-mgmt-nfx/routing-policy/topics/concept/tcm-overview-cos-qfx-series-understanding.html
 214 .. [#cisco] https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/qos_mqc/configuration/xe-16-8/qos-mqc-xe-16-8-book/qos-pkt-policing.html
 215 .. [#rfc2697] https://www.rfc-editor.org/rfc/rfc2697.html
 216 .. [#rfc2698] https://www.rfc-editor.org/rfc/rfc2698.html
 217 .. [#rfc4115] https://www.rfc-editor.org/rfc/rfc4115.html