docs/user-guide/packetcable-user-guide.rst

   1 PacketCable User Guide
   2 ======================
   3
   4 Overview
   5 --------
   6
   7 These components introduce a DOCSIS QoS Gates management using the PCMM
   8 protocol. The driver component is responsible for the PCMM/COPS/PDP
   9 functionality required to service requests from PacketCable Provider and
  10 FlowManager. Requests are transposed into PCMM Gate Control messages and
  11 transmitted via COPS to the CMTS. This plugin adheres to the
  12 PCMM/COPS/PDP functionality defined in the CableLabs specification.
  13 PacketCable solution is an MDSAL compliant component.
  14
  15 PacketCable Components
  16 ----------------------
  17
  18 PacketCable is comprised of two OpenDaylight bundles:
  19
  20 +--------------------------------------+--------------------------------------+
  21 | Bundle                               | Description                          |
  22 +======================================+======================================+
  23 | odl-packetcable-policy-server        | Plugin that provides PCMM model      |
  24 |                                      | implementation based on CMTS         |
  25 |                                      | structure and COPS protocol.         |
  26 +--------------------------------------+--------------------------------------+
  27 | odl-packetcable-policy-model         | The Model provided provides a direct |
  28 |                                      | mapping to the underlying QoS Gates  |
  29 |                                      | of CMTS.                             |
  30 +--------------------------------------+--------------------------------------+
  31
  32 See the PacketCable `YANG
  33 Models <https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-policy-model/src/main/yang>`__.
  34
  35 Installing PacketCable
  36 ----------------------
  37
  38 To install PacketCable, run the following ``feature:install`` command
  39 from the Karaf CLI
  40
  41 ::
  42
  43     feature:install odl-packetcable-policy-server-all odl-restconf odl-mdsal-apidocs
  44
  45 Explore and exercise the PacketCable REST API
  46 ---------------------------------------------
  47
  48 To see the PacketCable APIs, browse to this URL:
  49 http://localhost:8181/apidoc/explorer/index.html
  50
  51 Replace localhost with the IP address or hostname where OpenDaylight is
  52 running if you are not running OpenDaylight locally on your machine.
  53
  54 .. note::
  55
  56     Prior to setting any PCMM gates, a CCAP must first be added.
  57
  58 Postman
  59 -------
  60
  61 `Install the Chrome
  62 extension <https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en>`__
  63
  64 `Download and import sample packetcable
  65 collection <https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-policy-server/doc/restconf-samples>`__
  66
  67 Postman Operations
  68 ^^^^^^^^^^^^^^^^^^
  69
  70 .. figure:: ./images/packetcable-postman.png
  71    :alt: Postman Operations
  72
  73    Postman Operations
  74
  75
  76
  77 PacketCable REST API Usage Examples
  78 -----------------------------------
  79
  80 * CCAP "CONFIG" DATASTORE API STRUCTURE
  81
  82   * Add and view CCAPConfigDatastore(add triggers also the CCAP COPS connection)::
  83
  84      PUT http://localhost:8181/restconf/config/packetcable:ccaps/ccap/CMTS-1
  85
  86      {"ccap":[
  87         {"ccapId":"CMTS-1",
  88          "amId": {
  89                "am-tag": 51930,
  90                "am-type": 1
  91          },
  92          "connection": {
  93                "ipAddress": "10.20.30.40",
  94                "port":3918
  95          },"subscriber-subnets": [
  96                "2001:4978:030d:1000:0:0:0:0/52",
  97                "44.137.0.0/16"
  98          ],"upstream-scns": [
  99                "SCNA",
 100                "extrm_up"
 101          ],"downstream-scns": [
 102                "extrm_dn",
 103                "ipvideo_dn",
 104                "SCNC"
 105          ]}
 106      ]}
 107
 108      GET http://localhost:8181/restconf/config/packetcable:ccaps/ccap/CMTS-1
 109
 110
 111 * CCAP OPERATIONAL STATUS - GET CCAP (COPS) CONNECTION STATUS
 112
 113   * Shows the Operational Datastorecontents for the CCAP COPS connection.
 114   * The status is updated when the COPS connection is initiated or after an RPC poll::
 115
 116      GET http://localhost:8181/restconf/operational/packetcable:ccaps/ccap/CMTS-1/
 117      Response: 200 OK
 118
 119      {
 120        "ccap": [
 121              {
 122                   "ccapId": "CMTS-1",
 123                   "connection": {
 124                        "error": [
 125                              "E6-CTO: CCAP client is connected"
 126                        ],
 127                        "timestamp": "2016-03-23T14:15:54.129-05:00",
 128                        "connected": true
 129                   }
 130              }
 131          ]
 132      }
 133
 134
 135 * CCAP OPERATIONAL STATUS - RPC CCAP POLL CONNECTION
 136
 137   * A CCAP RPC poll returns the COPS connectivity status info and also triggers an Operational Datastore status update with the same data::
 138
 139      POST http://localhost:8181/restconf/operations/packetcable:ccap-poll-connection
 140      {
 141           "input": {
 142                 "ccapId": "/packetcable:ccaps/packetcable:ccap[packetcable:ccapId='CMTS-1']"
 143           }
 144      }
 145      Response: 200 OK
 146      {
 147      "output": {
 148            "response": "CMTS-1: CCAP poll complete",
 149            "timestamp": "2016-03-23T14:15:54.131-05:00",
 150            "ccap": {
 151                  "ccapId": "CMTS-1",
 152                  "connection": {
 153                        "connection": {
 154                               "error": [
 155                                      "CMTS-1: CCAP client is connected"
 156                               ],
 157                               "timestamp": "2016-03-23T14:15:54.129-05:00",
 158                               "connected": true
 159                        }
 160                   }
 161              }
 162          }
 163      }
 164
 165 * CCAP OPERATIONAL STATUS - RPC CCAP POLL CONNECTION (2) - CONNECTION DOWN::
 166
 167      POST http://localhost:8181/restconf/operations/packetcable:ccap-poll-connection
 168      {
 169           "input": {
 170                 "ccapId": "/packetcable:ccaps/packetcable:ccap[packetcable:ccapId='CMTS-1']"
 171           }
 172      }
 173      Response: 200 OK
 174      {
 175      "output": {
 176            "response": "CMTS-1: CCAP poll complete",
 177            "timestamp": "2016-03-23T14:15:54.131-05:00",
 178            "ccap": {
 179                  "ccapId": "CMTS-1",
 180                  "connection": {
 181                        "error": [
 182                              "CMTS-1: CCAP client is disconnected with error: null",
 183                              "CMTS-1: CCAP Cops socket is closed"],
 184                        "timestamp": "2016-03-23T14:15:54.129-05:00",
 185                        "connected": false
 186                   }
 187              }
 188          }
 189      }
 190
 191
 192 * CCAP OPERATIONAL STATUS - RPC CCAP SET CONNECTION
 193
 194   * A CCAP RPC sets the CCAP COPS connection; possible values true or false meaning that the connection should be up or down.
 195   * RPC responds with the same info as RPC POLL CONNECTION, and also updates the Operational Datastore::
 196
 197      POST http://localhost:8181/restconf/operations/packetcable:ccap-set-connection
 198      {
 199           "input": {
 200                 "ccapId": "/packetcable:ccaps/packetcable:ccap[packetcable:ccapId='CMTS-1']",
 201                  "connection": {
 202                        "connected": true
 203                 }
 204           }
 205      }
 206      Response: 200 OK
 207      {
 208             "output": {
 209
 210                    "response": "CMTS-1: CCAP set complete",
 211                    "timestamp": "2016-03-23T17:47:29.446-05:00",
 212                    "ccap": {
 213                           "ccapId": "CMTS-1",
 214                           "connection": {
 215                                   "error": [
 216                                           "CMTS-1: CCAP client is connected",
 217                                           "CMTS-1: CCAP COPS socket is already open"],
 218                                   "timestamp": "2016-03-23T17:47:29.436-05:00",
 219                                   "connected": true
 220                           }
 221                    }
 222             }
 223      }
 224
 225 * CCAP OPERATIONAL STATUS - RPC CCAP SET CONNECTION (2) - SHUTDOWN COPS CONNECTION::
 226
 227      POST http://localhost:8181/restconf/operations/packetcable:ccap-set-connection
 228      {
 229           "input": {
 230                 "ccapId": "/packetcable:ccaps/packetcable:ccap[packetcable:ccapId='E6-CTO']",
 231                  "connection": {
 232                        "connected": false
 233                 }
 234           }
 235      }
 236      Response: 200 OK
 237      {
 238             "output": {
 239                    "response": "E6-CTO: CCAP set complete",
 240                    "timestamp": "2016-03-23T17:47:29.446-05:00",
 241                    "ccap": {
 242                           "ccapId": "E6-CTO",
 243                           "connection": {
 244                                   "error": [
 245                                           "E60CTO: CCAP client is disconnected with error: null"],
 246                                   "timestamp": "2016-03-23T17:47:29.436-05:00",
 247                                   "connected": false
 248                           }
 249                    }
 250             }
 251      }
 252
 253 .. note::
 254     A "null" in the error information means that the CCAP connection has been disconnected as a result of a RPC SET.
 255
 256 * GATES "CONFIG" DATASTORE API STRUCTURE CHANGED
 257
 258   * A CCAP RPC poll returns the gate status info, and also triggers a Operational Datastorestatus update.
 259   * At a minimum the appIdneeds to be included in the input, subscriberIdand gateIdare optional.
 260   * A gate status response is only included if the RPC request is done for a specific gate (subscriberIdand gateIdincluded in input).
 261   * Add and retrieve gates to/from the Config Datastore::
 262
 263      PUT http://localhost:8181/restconf/config/packetcable:qos/apps/app/cto-app/subscribers/subscriber/44.137.0.12/gates/gate/gate88/
 264
 265      {
 266        "gate": [
 267          {
 268            "gateId": "gate88",
 269            "gate0spec": {
 270              "dscp-tos-overwrite": "0xa0",
 271              "dscp-tos-mask": "0xff"
 272            },
 273            "traffic-profile": {
 274              "service-class-name": "extrm_dn"
 275            },
 276            "classifiers": {
 277              "classifier-container": [
 278                {
 279                  "classifier-id": "1",
 280                  "classifier": {
 281                    "srcIp": "44.137.0.0",
 282                    "dstIp": "44.137.0.11",
 283                    "protocol": "0",
 284                    "srcPort": "1234",
 285                    "dstPort": "4321",
 286                    "tos-byte": "0xa0",
 287                    "tos-mask": "0xe0"
 288                  }
 289                }
 290              ]
 291            }
 292          }
 293        ]
 294      }
 295
 296      GET http://localhost:8181/restconf/config/packetcable:qos/apps/app/cto-app/subscribers/subscriber/44.137.0.12/gates/gate/gate88/
 297
 298
 299 * GATES SUPPORT MULTIPLE (UP TO FOUR) CLASSIFIERS
 300
 301   * Please note that there is a classifier container now that can have up to four classifiers::
 302
 303      PUT http://localhost:8181/restconf/config/packetcable:qos/apps/app/cto-app/subscribers/subscriber/44.137.0.12/gates/gate/gate88/
 304      { "gate":{
 305          "gateId": "gate44",
 306          "gate-spec": {
 307          "dscp-tos-overwrite": "0xa0",
 308                    "dscp-tos-mask": "0xff" },
 309          "traffic-profile": {
 310                    "service-class-name": "extrm_dn"},
 311          "classifiers":
 312                    { "classifier-container":[
 313                               { "classifier-id": "1",
 314                                        "ipv6-classifier": {
 315                                                  "srcIp6": "2001:4978:030d:1100:0:0:0:0/64",
 316                                                                      "dstIp6": "2001:4978:030d:1000:0:0:0:0/64",
 317                                                  "flow-label": "102",
 318                                                  "tc-low": "0xa0",
 319                                                  "tc-high": "0xc0",
 320                                                  "tc-mask": "0xe0",
 321                                                  "next-hdr": "256",
 322                                                  "srcPort-start": "4321",
 323                                                  "srcPort-end": "4322",
 324                                                  "dstPort-start": "1234",
 325                                                  "dstPort-end": "1235"
 326                               }},
 327                               { "classifier-id": "2",
 328                                         "ext-classifier" : {
 329                                                   "srcIp": "44.137.0.12",
 330                                                   "srcIpMask": "255.255.255.255",
 331                                                   "dstIp": "10.10.10.0",
 332                                                   "dstIpMask": "255.255.255.0",
 333                                                   "tos-byte": "0xa0",
 334                                                   "tos-mask": "0xe0",
 335                                                   "protocol": "0",
 336                                                   "srcPort-start": "4321",
 337                                                   "srcPort-end": "4322",
 338                                                   "dstPort-start": "1234",
 339                                                   "dstPort-end": "1235"
 340                                         }
 341                               }]
 342                    }
 343          }
 344      }
 345
 346
 347 * CCAP OPERATIONAL STATUS - GET GATE STATUS FROM OPERATIONAL DATASTORE
 348
 349   * Shows the Operational Datastore contents for the gate.
 350   * The gate status is updated at the time when the gate is configured or during an RPC poll::
 351
 352      GET http://localhost:8181/restconf/operational/packetcable:qos/apps/app/cto-app/subscribers/subscriber/44.137.0.12/gates/gate/gate88
 353
 354      Response: 200
 355      {
 356          "gate":[{
 357                 "gateId":"gate88",
 358                 "cops-gate-usage-info": "0",
 359                 "cops-gate-state": "Committed(4)/Other(-1)",
 360                 "gatePath": "cto-app/44.137.0.12/gate88",
 361                 "cops-gate-time-info": "0",
 362                 "cops-gateId": "3e0800e9",
 363                 "timestamp": "2016-03-24T10:30:18.763-05:00",
 364                 "ccapId": "E6-CTO"
 365          }]
 366      }
 367
 368
 369 * CCAP OPERATIONAL STATUS - RPC GATE STATUS POLL
 370
 371   * A CCAP RPC poll returns the gate status info and also triggers an Operational Datastore status update.
 372   * At a minimum, the appId needs to be included in the input; subscriberId and gateId are optional.
 373   * A gate status response is only included if the RPC request is done for a specific gate (subscriberId and gateId included in input)::
 374
 375      POST http://localhost:8181/restconf/operations/packetcable:qos-poll-gates
 376      {
 377           "input": {
 378                 "appId": "/packetcable:apps/packetcable:apps[packetcable:appId='cto-app]",
 379                 "subscriberId": "44.137.0.11",
 380                 "gateId": "gate44"
 381           }
 382      }
 383      Response: 200 OK
 384      {
 385           "output": {
 386                      "gate": {
 387                               "cops-gate-usage-info": "0",
 388                               "cops-gate-state": "Committed(4)/Other(-1)",
 389                               "gatePath": "ctoapp/44.137.0.12/gate88",
 390                               "cops-gate-time-info": "0",
 391                               "cops-gateId": "1ceb0001",
 392                               "error": [""],
 393                               "timestamp": "2016-03-24T13:22:59.900-05:00",
 394                               "ccapId": "E6-CTO"
 395                      },
 396                      "response": "cto-app/44.137.0.12/gate88: gate poll complete",
 397                      "timestamp": "2016-03-24T13:22:59.906-05:00"
 398           }
 399      }
 400
 401   * When multiple gates are polled (only appId or appId and subscriberId are provided), a generic response is returned and the Operational Datastore is updated in the background::
 402
 403      {  "output": {
 404             "gate": {},
 405             "response": "cto-app/: gate subtree poll in progress",
 406             "timestamp": "2016-03-24T13:25:30.471-05:00"
 407         }
 408      }
 409
 410