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

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