docs/specs/acl-stats.rst

   1 .. contents:: Table of Contents
   2    :depth: 3
   3
   4 ==============
   5 ACL Statistics
   6 ==============
   7
   8 https://git.opendaylight.org/gerrit/#/q/topic:acl-stats
   9
  10 This feature is to provide additional operational support for ACL through statistical counters.
  11 ACL rules provide security to VMs by filtering packets in either directions (ingress/egress).
  12 Using OpenFlow statistical counters, ODL will provide additional information on the number of
  13 packets dropped by the ACL rules. This information is made available to the operator “on demand”.
  14
  15 Drop statistics will be provided for below cases:
  16
  17 * Packets dropped due to ACL rules
  18 * Packets dropped due to INVALID state. The INVALID state means that the packet can't be identified
  19   or that it does not have any state. This may be due to several reasons, such as the system
  20   running out of memory or ICMP error messages that do not respond to any known connections.
  21
  22 The packet drop information provided through the statistical counters enable operators to
  23 trouble shoot any misbehavior and take appropriate actions through automated or manual
  24 intervention.
  25
  26 Collection and retrieval of information on the number of packets dropped by the SG rules
  27
  28 * Done for all (VM) ports in which SG is configured
  29 * Flow statistical counters (in OpenFlow) are used for this purpose
  30 * The information in these counters are made available to the operator, on demand, through an API
  31
  32 This feature will only be supported with Stateful ACL mode.
  33
  34 Problem description
  35 ===================
  36 With only ACL support, operators would not be able to tell how many packets dropped by ACL rules.
  37 This enhancement planned is about ACL module supporting aforementioned limitation.
  38
  39 Use Cases
  40 ---------
  41 Collection and retrieval of information on the number of packets dropped by the ACL rules
  42
  43 * Done for all (VM) ports in which ACL is configured
  44 * The information in these counters are made available to the operator, on demand, through an API
  45 * Service Orchestrator/operator can also specify ports selectively where ACL rules are configured
  46
  47 Proposed change
  48 ===============
  49
  50 ACL Changes
  51 -----------
  52 Current Stateful ACL implementation has drop flows for all ports combined for a device. This needs
  53 to be modified to have drop flows for each of the OF ports connected to VMs (Neutron Ports).
  54
  55 With the current implementation, drop flows are as below:
  56
  57 .. code-block:: bash
  58
  59    cookie=0x6900000, duration=938.964s, table=252, n_packets=0, n_bytes=0, priority=62020,
  60            ct_state=+inv+trk actions=drop
  61
  62    cookie=0x6900000, duration=938.969s, table=252, n_packets=0, n_bytes=0, priority=50,
  63            ct_state=+new+trk actions=drop
  64
  65 Now, for supporting Drop packets statistics per port, ACL will be updated to replace above
  66 flows with new DROP flows with lport tag as metadata for each of the VM (Neutron port) being
  67 added to OVS as specified below:
  68
  69 .. code-block:: bash
  70
  71    cookie=0x6900001, duration=938.964s, table=252, n_packets=0, n_bytes=0, priority=62015,
  72            metadata=0x10000000000/0xffffff0000000000, ct_state=+inv+trk actions=drop
  73
  74    cookie=0x6900001, duration=938.969s, table=252, n_packets=0, n_bytes=0, priority=50,
  75            metadata=0x10000000000/0xffffff0000000000, ct_state=+new+trk actions=drop
  76
  77 Drop flows details explained above are for pipeline egress direction. For ingress side,
  78 similar drop flows would be added with ``table=41``.
  79
  80 Also, new cookie value ``0x6900001`` would be added with drop flows to identify it uniquely and
  81 priority ``62015`` would be used with +inv+trk flows to give higher priority for +est and +rel
  82 flows.
  83
  84 Drop packets statistics support
  85 -------------------------------
  86 ODL Controller will be updated to provide a new RPC/NB REST API ``<get-acl-port-statistics>`` in
  87 ACL module with ``ACL Flow Stats Request`` and ``ACL Flow Stats Response`` messages. This RPC/API
  88 will retrieve details of dropped packets by Security Group rules for all the neutron ports
  89 specified as part of ``ACL Flow Stats Request``. The retrieved information (instantaneous) received
  90 in the OF reply message is formatted as ``ACL Flow Stats Response`` message before sending it as a
  91 response towards the NB.
  92
  93 ``<get-acl-port-statistics>`` RPC/API implementation would be triggering
  94 ``opendaylight-direct-statistics:get-flow-statistics`` request of OFPlugin towards OVS to get the
  95 flow statistics of ACL tables (ingress / egress) for the required ports.
  96
  97 ACL Flow Stats Request/Response messages are explained in subsequent sections.
  98
  99 Pipeline changes
 100 ----------------
 101 No changes needed in OF pipeline. But, new flows as specified in above section would be added for
 102 each of the Neutron ports being added.
 103
 104 Yang changes
 105 ------------
 106 New yang file will be created with RPC as specified below:
 107
 108 .. code-block:: none
 109    :caption: acl-live-statistics.yang
 110
 111     module acl-live-statistics {
 112         namespace "urn:opendaylight:netvirt:acl:live:statistics";
 113
 114         prefix "acl-stats";
 115
 116         import ietf-interfaces {prefix if;}
 117         import aclservice {prefix aclservice; revision-date "2016-06-08";}
 118
 119         description "YANG model describes RPC to retrieve ACL live statistics.";
 120
 121         revision "2016-11-29" {
 122             description "Initial revision of ACL live statistics";
 123         }
 124
 125         typedef direction {
 126             type enumeration {
 127                 enum ingress;
 128                 enum egress;
 129                 enum both;
 130             }
 131         }
 132
 133         grouping acl-drop-counts {
 134             leaf drop-count {
 135                 description "Packets/Bytes dropped by ACL rules";
 136                 type uint64;
 137             }
 138             leaf invalid-drop-count {
 139                 description "Packets/Bytes identified as invalid";
 140                 type uint64;
 141             }
 142         }
 143
 144         grouping acl-stats-output {
 145             description "Output for ACL port statistics";
 146             list acl-interface-stats {
 147                 key "interface-name";
 148                 leaf interface-name {
 149                     type leafref {
 150                         path "/if:interfaces/if:interface/if:name";
 151                     }
 152                 }
 153                 list acl-drop-stats {
 154                     max-elements "2";
 155                     min-elements "0";
 156                     leaf direction {
 157                         type identityref {
 158                             base "aclservice:direction-base";
 159                         }
 160                     }
 161                     container packets {
 162                         uses acl-drop-counts;
 163                     }
 164                     container bytes {
 165                         uses acl-drop-counts;
 166                     }
 167                 }
 168                 container error {
 169                     leaf error-message {
 170                         type string;
 171                     }
 172                 }
 173             }
 174         }
 175
 176         grouping acl-stats-input {
 177             description "Input parameters for ACL port statistics";
 178
 179             leaf direction {
 180                 type identityref {
 181                     base "aclservice:direction-base";
 182                 }
 183                 mandatory "true";
 184             }
 185             leaf-list interface-names {
 186                 type leafref {
 187                     path "/if:interfaces/if:interface/if:name";
 188                 }
 189                 max-elements "unbounded";
 190                 min-elements "1";
 191             }
 192         }
 193
 194         rpc get-acl-port-statistics {
 195             description "Get ACL statistics for given list of ports";
 196
 197             input {
 198                 uses acl-stats-input;
 199             }
 200             output {
 201                 uses acl-stats-output;
 202             }
 203         }
 204     }
 205
 206 Configuration impact
 207 ---------------------
 208 No configuration parameters being added/deprecated for this feature
 209
 210 Clustering considerations
 211 -------------------------
 212 No additional changes required to be done as only one RPC is being supported as part of
 213 this feature.
 214
 215 Other Infra considerations
 216 --------------------------
 217 N.A.
 218
 219 Security considerations
 220 -----------------------
 221 N.A.
 222
 223 Scale and Performance Impact
 224 ----------------------------
 225 N.A.
 226
 227 Targeted Release
 228 -----------------
 229 Carbon
 230
 231 Alternatives
 232 ------------
 233 Dispatcher table (table 17 and table 220) based approach of querying drop packets count was
 234 considered. ie., arriving drop packets count by below rule:
 235
 236 **<total packets entered ACL tables> - <total packets entered subsequent service>**
 237
 238 This approach was not selected as this only provides total packets dropped count per port by ACL
 239 services and does not provide details of whether it’s dropped by ACL rules or for some other
 240 reasons.
 241
 242 Usage
 243 =====
 244 Features to Install
 245 -------------------
 246 odl-netvirt-openstack
 247
 248 REST API
 249 --------
 250 Get ACL statistics
 251 ^^^^^^^^^^^^^^^^^^
 252 Following API gets ACL statistics for given list of ports.
 253
 254 **Method**: POST
 255
 256 **URI**: /operations/acl-live-statistics:get-acl-port-statistics
 257
 258 **Parameters**:
 259
 260 =================     ===================     =================================     ==============
 261 Parameter             Type                    Possible Values                       Comments
 262 =================     ===================     =================================     ==============
 263 "direction"           Enum                    ingress/egress/both                   Required
 264
 265 "interface-names"     Array [UUID String]     [<UUID String>,<UUID String>,.. ]     Required (1,N)
 266 =================     ===================     =================================     ==============
 267
 268 **Example**:
 269
 270 .. code-block:: json
 271
 272     {
 273         "input":
 274         {
 275              "direction": "both",
 276              "interface-names": [
 277                  "4ae8cd92-48ca-49b5-94e1-b2921a2661c5",
 278                  "6c53df3a-3456-11e5-a151-feff819cdc9f"
 279              ]
 280         }
 281     }
 282
 283 **Possible Responses**:
 284
 285 **RPC Success**:
 286
 287 .. code-block:: json
 288
 289     {
 290         "output": {
 291         "acl-port-stats": [
 292         {
 293             "interface-name": "4ae8cd92-48ca-49b5-94e1-b2921a2661c5",
 294             "acl-drop-stats": [
 295             {
 296                 "direction": "ingress",
 297                 "bytes": {
 298                     "invalid-drop-count": "0",
 299                     "drop-count": "300"
 300                 },
 301                 "packets": {
 302                     "invalid-drop-count": "0",
 303                     "drop-count": "4"
 304                 }
 305             },
 306             {
 307                 "direction": "egress",
 308                 "bytes": {
 309                     "invalid-drop-count": "168",
 310                     "drop-count": "378"
 311                 },
 312                 "packets": {
 313                     "invalid-drop-count": "2",
 314                     "drop-count": "9"
 315                 }
 316             }]
 317         },
 318         {
 319             "interface-name": "6c53df3a-3456-11e5-a151-feff819cdc9f",
 320             "acl-drop-stats": [
 321             {
 322                 "direction": "ingress",
 323                 "bytes": {
 324                     "invalid-drop-count": "1064",
 325                     "drop-count": "1992"
 326                 },
 327                 "packets": {
 328                     "invalid-drop-count": "18",
 329                     "drop-count": "23"
 330                  }
 331             },
 332             {
 333                 "direction": "egress",
 334                 "bytes": {
 335                     "invalid-drop-count": "462",
 336                     "drop-count": "476"
 337                  },
 338                 "packets": {
 339                     "invalid-drop-count": "11",
 340                     "drop-count": "6"
 341                 }
 342             }]
 343         }]
 344     }
 345
 346 **RPC Success (with error for one of the interface)**:
 347
 348 .. code-block:: json
 349
 350     {
 351         "output":
 352         {
 353             "acl-port-stats": [
 354             {
 355                 "interface-name": "4ae8cd92-48ca-49b5-94e1-b2921a2661c5",
 356                 "acl-drop-stats": [
 357                 {
 358                     "direction": "ingress",
 359                     "bytes": {
 360                         "invalid-drop-count": "0",
 361                         "drop-count": "300"
 362                     },
 363                     "packets": {
 364                         "invalid-drop-count": "0",
 365                         "drop-count": "4"
 366                     }
 367                 },
 368                 {
 369                     "direction": "egress",
 370                     "bytes": {
 371                         "invalid-drop-count": "168",
 372                         "drop-count": "378"
 373                     },
 374                     "packets": {
 375                         "invalid-drop-count": "2",
 376                         "drop-count": "9"
 377                     }
 378                 },
 379                 {
 380                     "interface-name": "6c53df3a-3456-11e5-a151-feff819cdc9f",
 381                     "error": {
 382                         "error-message": "Interface not found in datastore."
 383                     }
 384                 }]
 385             }]
 386         }
 387     }
 388
 389 .. Note::
 390    Below are error messages for the interface:
 391
 392    (a) "Interface not found in datastore."
 393    (b) "Failed to find device for the interface."
 394    (c) "Unable to retrieve drop counts due to error: <<error message>>”
 395    (d) "Unable to retrieve drop counts as interface is not configured for statistics collection."
 396    (e) "Operation not supported for ACL <<Stateless/Transparent/Learn>> mode"
 397
 398 CLI
 399 ---
 400 No CLI being added for this feature
 401
 402 Implementation
 403 ==============
 404 Assignee(s)
 405 -----------
 406 Primary assignee:
 407   <Somashekar Byrappa>
 408
 409 Other contributors:
 410   <Shashidhar R>
 411
 412 Work Items
 413 ----------
 414 #. Adding new drop rules per port (in table 41 and 252)
 415 #. Yang changes
 416 #. Supporting new RPC
 417
 418 Dependencies
 419 ============
 420 This doesn't add any new dependencies.
 421
 422 This feature has dependency on below bug reported in OF Plugin:
 423
 424 `Bug 7232 - Problem observed with "get-flow-statistics" RPC call <https://bugs.opendaylight.org/show_bug.cgi?id=7232>`__
 425
 426 Testing
 427 =======
 428 Unit Tests
 429 ----------
 430 Following test cases will need to be added/expanded
 431
 432 #. Verify ACL STAT RPC with single Neutron port
 433 #. Verify ACL STAT RPC with multiple Neutron ports
 434 #. Verify ACL STAT RPC with invalid Neutron port
 435 #. Verify ACL STAT RPC with mode set to "transparent/learn/stateless"
 436
 437 Also, existing unit tests will be updated to include new drop flows.
 438
 439 Integration Tests
 440 -----------------
 441 Integration tests will be added, once IT framework is ready
 442
 443 CSIT
 444 ----
 445 Following test cases will need to be added/expanded
 446
 447 #. Verify ACL STAT RPC with single Neutron port with different directions (ingress, egress, both)
 448 #. Verify ACL STAT RPC with multiple Neutron ports with different
 449    directions (ingress, egress, both)
 450 #. Verify ACL STAT RPC with invalid Neutron port
 451 #. Verify ACL STAT RPC with combination of valid and invalid Neutron ports
 452 #. Verify ACL STAT RPC with combination of Neutron ports with few having port-security-enabled as
 453    true and others having false
 454
 455 Documentation Impact
 456 ====================
 457 This will require changes to User Guide. User Guide needs to be updated with details about new RPC
 458 being supported and also about its REST usage.
 459
 460 References
 461 ==========
 462 N.A.
 463
 464 .. note::
 465
 466   This work is licensed under a Creative Commons Attribution 3.0 Unported License.
 467   http://creativecommons.org/licenses/by/3.0/legalcode