manuals/developer-guide/src/main/asciidoc/pcmm.adoc

   1 == Packet Cable MultiMedia (PCMM)
   2
   3 === Checking out the Packetcable PCMM project
   4  git clone https://git.opendaylight.org/gerrit/p/packetcable.git
   5
   6 The above command will create a directory called "packetcable" with the project.
   7
   8 === System Overview
   9
  10 These components introduce a DOCSIS QoS Service Flow management using the PCMM protocol.  The driver component is responsible for the PCMM/COPS/PDP functionality required to service requests from PacketCable Provider and FlowManager.  Requests are transposed into PCMM Gate Control messages and transmitted via COPS to the CMTS. This plugin adheres to the PCMM/COPS/PDP functionality defined in the CableLabs specification.  PacketCable solution is an MD-SAL compliant component.
  11
  12 .System Overview
  13 image::pcmm-architecture.png["System Overview",width=500]
  14
  15 === Dependency Map
  16 .Dependency Map
  17 image::pcmm-depends-map.png["Dependency Map",width=500]
  18
  19 === Packetcable Components
  20
  21 packetcable is comprised of three OpenDaylight bundles
  22
  23 .Table of Bundle and Components
  24 [options="header"]
  25 |=======================
  26 | Bundle|Description
  27 | packetcable-model | Contains the YANG information model for flows and nodes
  28 | packetcable-provider | Provider hosts the model processing, RESTCONF, API implementation, and brokers requests to consumer
  29 | packetcable-driver | Driver manages PCMM Gate message over COPS for flows and CMTS connections
  30 | packetcable-consumer | Consumer is the codec for for transforming the model of nodes and flows to COPS Gate messages
  31 |=======================
  32
  33
  34 See link:https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-model/src/main/yang[YANG Model]
  35
  36 === Download and Install
  37
  38 Current instructions
  39
  40 ==== Download
  41
  42 link:http://nexus.opendaylight.org/content/groups/staging/org/opendaylight/integration/distribution-karaf/0.2.0-Helium/distribution-karaf-0.2.0-Helium.zip[Download]
  43
  44
  45 http://nexus.opendaylight.org/content/groups/staging/org/opendaylight/integration/distribution-karaf/
  46
  47 ==== Unzip
  48 [source, text]
  49 ----
  50 unzip distribution-karaf-0.2.0-Helium.zip
  51 ----
  52
  53
  54 ==== Run Karaf
  55 [source, text]
  56 ----
  57 cd distribution-karaf-0.2.0-Helium/bin/
  58 ./karaf
  59 ----
  60
  61 === Preparing to Work with the Packetcable PCMM Service
  62
  63 ==== Minimum install procedure
  64
  65 [source, text]
  66 ----
  67 opendaylight-user@root>feature:install odl-packetcable-all
  68 ----
  69
  70 ==== Useful Features to Start with PCMM
  71
  72 [source, text]
  73 ----
  74 opendaylight-user@root>feature:install odl-restconf odl-l2switch-switch  odl-dlux-core  odl-mdsal-apidocs odl-packetcable-all
  75 ----
  76
  77 ==== Auto Starting a Series of Bundles using Karaf
  78
  79 Edit etc/org.apache.karaf.features.cfg ‘featuresBoot'
  80 [source, text]
  81 ----
  82 #
  83 # Comma separated list of features to install at startup
  84 #
  85 featuresBoot=config,standard,region,package,kar,ssh,management,odl-restconf,odl-l2switch-switch,odl-dlux-core,odl-mdsal-apidocs,odl-packetcable-all
  86
  87 ----
  88
  89 ==== Starting Karaf as System Service
  90 ----
  91 cd distribution-karaf-0.2.0-Helium/
  92 sudo bin/start
  93 ----
  94
  95 ===== Accessing the Karaf Console
  96 [source, text]
  97 ----
  98    ssh -p 8101 karaf@localhost
  99
 100 ----
 101
 102 ===== Add These Directives to Your Operating System Profile to Change the Karaf Startup Parameters for Troubleshooting
 103 [source, text]
 104 ----
 105    export KARAF_DEBUG=true
 106    export JAVA_DEBUG_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005"
 107 ----
 108
 109 ===== Tell a Bundle to Log Debug
 110 [source, text]
 111 ----
 112     log:set  org.opendaylight.packetcable
 113 ----
 114
 115
 116 ==== Management UI
 117
 118 http://localhost:8181/dlux/index.html
 119
 120 |=======================
 121 | user | admin
 122 | password | admin
 123 |=======================
 124
 125
 126 Sign in
 127
 128 .Sign in to Dlux UI
 129 image::pcmm-dlux-login.png["Dlux Login",width=500]
 130
 131 Manage Flows
 132
 133 .View and Manage Flows in Dlux
 134 image::pcmm-dlux-flows.png["Dlux Flows",width=500]
 135
 136 Manage Nodes
 137
 138 .View and Manage Nodes in Dlux
 139 image::pcmm-dlux-nodes.png["Dlux Nodes",width=500]
 140
 141
 142 === Explore and exercise the PacketCable REST API
 143 http://localhost:8181/apidoc/explorer/index.html
 144
 145
 146
 147 === RESTCONF API Explorer
 148
 149 http://localhost:8181/apidoc/explorer/index.html
 150
 151 Add a CMTS to Opendaylight Inventory
 152
 153 .Add CMTS using RESTCONF Explorer
 154 image::pcmm-apidoc-explorer.png["Add CMTS using RESTCONF Explorer",width=500]
 155
 156
 157 === Postman
 158
 159 link:https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Configure the Chrome browser]
 160
 161 Download and import sample
 162 link:https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-client[packetcable collection] for Postman.
 163
 164 .Postman Collection for Packetcable PCMM
 165 image::pcmm-postman.png["Postman",width=500]
 166
 167 === Custom Testsuite
 168
 169 Most of the tests for RESTCONF can be adapted for PCMM and service flow testing. The following list of
 170 Packetcable client testing.  Browse this folder for tests and examples used for  testing.
 171
 172 ==== restconfapi.py
 173
 174 Scripted series of packetcable actions testing compliance.  Other flows can be formulated and added to create a regression test of what kind of flows are interesting for use cases.
 175
 176
 177 ==== flow_config_perf_pcmm.py
 178 For load testing there is this nice tool that could be repurpose to load test a CMTS.
 179
 180 === Using Wireshark to Trace PCMM
 181 To start wireshark with privileges issue the following command:
 182 [source, text]
 183 ----
 184 sudo wireshark &
 185 ----
 186
 187 Select the interface to monitor.
 188
 189 Use the Filter to only display COPS messages by applying “cops” in the filter field.
 190 .Using Wireshark to View COPS
 191 image::pcmm-wireshark.png["Wireshark",width=500]
 192
 193 === Debugging and Verifying DQoS Gate (Flows) on the CMTS
 194
 195 Below are some of the most useful CMTS commands to verify flows have been enabled on the CMTS.
 196
 197 ==== Cisco
 198
 199 link:http://www.cisco.com/c/en/us/td/docs/cable/cmts/cmd_ref/b_cmts_cable_cmd_ref.pdf[Cisco CMTS Cable Command Reference]
 200
 201
 202 === Find the Cable Modem
 203
 204 [source,text]
 205 ----
 206 10k2-DSG#show cable modem
 207                                                                                   D
 208 MAC Address    IP Address      I/F           MAC           Prim RxPwr  Timing Num I
 209                                              State         Sid  (dBmv) Offset CPE P
 210 0010.188a.faf6 0.0.0.0         C8/0/0/U0     offline       1    0.00   1482   0   N
 211 74ae.7600.01f3 10.32.115.150   C8/0/10/U0    online        1    -0.50  1431   0   Y
 212 0010.188a.fad8 10.32.115.142   C8/0/10/UB    w-online      2    -0.50  1507   1   Y
 213 000e.0900.00dd 10.32.115.143   C8/0/10/UB    w-online      3    1.00   1677   0   Y
 214 e86d.5271.304f 10.32.115.168   C8/0/10/UB    w-online      6    -0.50  1419   1   Y
 215 ----
 216
 217 ==== Show PCMM Plugin Connection
 218
 219 [source,text]
 220 ----
 221 10k2-DSG#show packetcabl ?
 222   cms     Gate Controllers connected to this PacketCable client
 223   event   Event message server information
 224   gate    PacketCable gate information
 225   global  PacketCable global information
 226
 227 10k2-DSG#show packetcable cms
 228 GC-Addr        GC-Port  Client-Addr    COPS-handle  Version PSID Key PDD-Cfg
 229
 230
 231 10k2-DSG#show packetcable cms
 232 GC-Addr        GC-Port  Client-Addr    COPS-handle  Version PSID Key PDD-Cfg
 233 10.32.0.240    54238    10.32.15.3     0x4B9C8150/1    4.0   0    0   0
 234 ----
 235
 236 ==== Show COPS Messages
 237
 238 [source,text]
 239 ----
 240 debug cops details
 241 ----
 242
 243 ==== Use CM Mac Address to List Service Flows
 244
 245 [source,text]
 246 ----
 247 10k2-DSG#show cable modem
 248                                                                                   D
 249 MAC Address    IP Address      I/F           MAC           Prim RxPwr  Timing Num I
 250                                              State         Sid  (dBmv) Offset CPE P
 251 0010.188a.faf6 ---             C8/0/0/UB     w-online      1    0.50   1480   1   N
 252 74ae.7600.01f3 10.32.115.150   C8/0/10/U0    online        1    -0.50  1431   0   Y
 253 0010.188a.fad8 10.32.115.142   C8/0/10/UB    w-online      2    -0.50  1507   1   Y
 254 000e.0900.00dd 10.32.115.143   C8/0/10/UB    w-online      3    0.00   1677   0   Y
 255 e86d.5271.304f 10.32.115.168   C8/0/10/UB    w-online      6    -0.50  1419   1   Y
 256
 257
 258 10k2-DSG#show cable modem 000e.0900.00dd service-flow
 259
 260
 261 SUMMARY:
 262 MAC Address    IP Address      Host          MAC           Prim  Num Primary    DS
 263                                Interface     State         Sid   CPE Downstream RfId
 264 000e.0900.00dd 10.32.115.143   C8/0/10/UB    w-online      3     0   Mo8/0/2:1  2353
 265
 266
 267 Sfid  Dir Curr  Sid   Sched  Prio MaxSusRate  MaxBrst     MinRsvRate  Throughput
 268           State       Type
 269 23    US  act   3     BE     0    0           3044        0           39
 270 30    US  act   16    BE     0    500000      3044        0           0
 271 24    DS  act   N/A   N/A    0    0           3044        0           17
 272
 273
 274
 275 UPSTREAM SERVICE FLOW DETAIL:
 276
 277 SFID  SID   Requests   Polls      Grants     Delayed    Dropped    Packets
 278                                              Grants     Grants
 279 23    3     784        0          784        0          0          784
 280 30    16    0          0          0          0          0          0
 281
 282
 283 DOWNSTREAM SERVICE FLOW DETAIL:
 284
 285 SFID  RP_SFID QID    Flg Policer               Scheduler             FrwdIF
 286                          Xmits      Drops      Xmits      Drops
 287 24    33019   131550     0          0          777        0          Wi8/0/2:2
 288
 289 Flags Legend:
 290 $: Low Latency Queue (aggregated)
 291 ~: CIR Queue
 292 ----
 293
 294 ==== Deleting a PCMM Gate Message from the CMTS
 295
 296 [source,text]
 297 ----
 298 10k2-DSG#test cable dsd  000e.0900.00dd 30
 299 ----
 300
 301 ==== Find service flows
 302
 303 All gate controllers currently connected to the PacketCable client are displayed
 304
 305 [source,text]
 306 ----
 307 show cable modem 00:11:22:33:44:55 service flow   ????
 308 show cable modem
 309 ----
 310
 311
 312 ==== Debug and display PCMM Gate messages
 313 [source,text]
 314 ----
 315 debug packetcable gate control
 316 debug packetcable gate events
 317 show packetcable gate summary
 318 show packetcable global
 319 show packetcable cms
 320 ----
 321
 322 ==== Debug COPS messages
 323 [source,text]
 324 ----
 325 debug cops detail
 326 debug packetcable cops
 327 debug cable dynamic_qos trace
 328 ----
 329
 330 === Arris
 331
 332 Pending
 333
 334
 335 === RESTCONF API for Packetcable PCMM
 336
 337 ==== CMTS
 338
 339 CMTS can be read, created, updated and deleted by a user having the
 340 correct role. An ID is used to identify where to read
 341 or save the CMTS node.
 342
 343 ===== Read
 344
 345 [cols="h,5a"]
 346 |===
 347 | URL
 348 | /restconf/config/opendaylight-inventory:nodes/node/[id]/packetcable-cmts:cmts-node/
 349
 350 | Method
 351 | GET
 352
 353 | Request Body
 354 |
 355 // include::cmts-get-request.json.adoc[]
 356 [source,json]
 357 ----
 358 {}
 359 ----
 360 | Response Body
 361 |
 362 // include::cmts-get-response.json.adoc[]
 363 [source,json]
 364 ----
 365 {}
 366 ----
 367 | Return Codes
 368 | 201
 369 |===
 370
 371 ===== Create
 372
 373 [cols="h,5a"]
 374 |===
 375 | URL
 376 | /restconf/config/opendaylight-inventory:nodes/node/[id]/packetcable-cmts:cmts-node/
 377
 378 | Method
 379 | PUT
 380
 381 | Request Body
 382 |
 383 //  include::cmts-put-response.json.adoc[]
 384 [source,json]
 385 ----
 386 {
 387     "packetcable-cmts:cmts-node": {
 388        "port": "3918",
 389        "address": "10.200.90.3"
 390     }
 391 }
 392 ----
 393 | Response Body
 394 |
 395 [source,json]
 396 ----
 397 {}
 398 ----
 399 | Return Codes
 400 | 201
 401 |===
 402
 403
 404 ===== Delete
 405
 406 [cols="h,5a"]
 407 |===
 408 | URL
 409 | /restconf/config/opendaylight-inventory:nodes/node/[id]/packetcable-cmts:cmts-node/
 410
 411 | Method
 412 | DELETE
 413
 414 | Request Body
 415 |
 416 // include::cmts-delete-request.json.adoc[]
 417 [source,json]
 418 ----
 419 {}
 420 ----
 421 | Response Body
 422 |
 423 [source,json]
 424 ----
 425 {}
 426 ----
 427 | Return Codes
 428 | 201
 429 |===
 430
 431 ==== Flows
 432
 433 Flows can be read, created, updated and deleted by a user having the
 434 correct role. A CMTS ID is used to identify which CMTS node to read
 435 or save the flow. Note: The Table ID is not used.
 436
 437 ===== Read
 438
 439 [cols="h,5a"]
 440 |===
 441 | URL
 442 | /restconf/config/opendaylight-inventory:nodes/node/[cmts id]/table/0/flow/[flow id]
 443
 444 | Method
 445 | GET
 446
 447 | Request Body
 448 |
 449 // include::flow-get-request.json.adoc[]
 450 [source,json]
 451 ----
 452 {}
 453 ----
 454 | Response Body
 455 |
 456 // include::flow-get-response.json.adoc[]
 457 [source,json]
 458 ----
 459 {
 460     "flow": {
 461         "cookie": "101",
 462         "cookie_mask": "255",
 463         "flow-name": "FooXf7",
 464         "hard-timeout": "1200",
 465         "id": "256",
 466         "idle-timeout": "3400",
 467         "installHw": "false",
 468         "instructions": {
 469             "instruction": {
 470                 "apply-actions": {
 471                     "action": {
 472                         "order": "0",
 473                         "traffic-profile": "best-effort"
 474                     }
 475                 },
 476                 "order": "0"
 477             }
 478         },
 479         "match": {
 480             "ethernet-match": {
 481                 "ethernet-type": {
 482                     "type": "34525"
 483                 }
 484             },
 485             "ip-match": {
 486                 "ip-dscp": "60",
 487                 "ip-ecn": "3",
 488                 "ip-protocol": "6"
 489             },
 490             "ipv6-destination": "fe80:2acf:e9ff:fe21::6431/94",
 491             "ipv6-source": "1234:5678:9ABC:DEF0:FDCD:A987:6543:210F/76",
 492             "tcp-destination-port": "8080",
 493             "tcp-source-port": "183"
 494         },
 495         "priority": "2",
 496         "strict": "false",
 497         "table_id": "2"
 498     }
 499 }
 500 ----
 501 |===
 502
 503 ===== Create
 504
 505 [cols="h,5a"]
 506 |===
 507 | URL
 508 | /restconf/config/opendaylight-inventory:nodes/node/[cmts id]/table/0/flow/[flow id]
 509
 510 | Method
 511 | PUT
 512
 513 | Request Body
 514 |
 515 //  include::flow-put-response.json.adoc[]
 516 [source,json]
 517 ----
 518 {
 519     "flow": {
 520         "barrier": "false",
 521         "flow-name": "FooXCableFlowCrazyTrafficProfileFBesteffort1",
 522         "id": "115",
 523         "installHw": "false",
 524         "instructions": {
 525             "instruction": {
 526                 "apply-actions": {
 527                     "action": {
 528                         "traffic-profile": "best-effort",
 529                         "be-authorized-envelope": {
 530                                 "traffic-priority":"0",
 531                                 "reserved0":"0",
 532                                 "reserved1":"0",
 533                                 "request-transmission-policy":"0",
 534                                 "maximum-sustained-traffic-rate":"0",
 535                                 "maximum-traffic-burst":"3044",
 536                                 "maximum-reserved-traffic-rate":"0",
 537                                   "traffic-rate-packet-size-maximum-concatenated-burst":"0",
 538                                 "assumed-minimum-reserved":"1522",
 539                                 "required-attribute-mask":"0",
 540                                 "forbidden-attribute-mask":"0",
 541                                 "attribute-aggregation-rule-mask":"0",
 542                         },
 543                         "be-reserved-envelope": {
 544                                 "traffic-priority":"0",
 545                                 "reserved0":"0",
 546                                 "reserved1":"0",
 547                                 "request-transmission-policy":"0",
 548                                 "maximum-sustained-traffic-rate":"0",
 549                                 "maximum-traffic-burst":"3044",
 550                                 "maximum-reserved-traffic-rate":"0",
 551                                 "traffic-rate-packet-size-maximum-concatenated-burst":"0",
 552                                 "assumed-minimum-reserved":"1522",
 553                                 "required-attribute-mask":"0",
 554                                 "forbidden-attribute-mask":"0",
 555                                 "attribute-aggregation-rule-mask":"0",
 556                         },
 557                         "be-committed-envelope": {
 558                                 "traffic-priority":"0",
 559                                 "reserved0":"0",
 560                                 "reserved1":"0",
 561                                 "request-transmission-policy":"0",
 562                                 "maximum-sustained-traffic-rate":"0",
 563                                 "maximum-traffic-burst":"3044",
 564                                 "maximum-reserved-traffic-rate":"0",
 565                                 "traffic-rate-packet-size-maximum-concatenated-burst":"0",
 566                                 "assumed-minimum-reserved":"1522",
 567                                 "required-attribute-mask":"0",
 568                                 "forbidden-attribute-mask":"0",
 569                                 "attribute-aggregation-rule-mask":"0",
 570                         }
 571
 572                         "order": "0"
 573                                 }
 574                 },
 575                 "order": "0"
 576             }
 577         },
 578         "match": {
 579             "ethernet-match": {
 580                 "ethernet-type": {
 581                     "type": "2048"
 582                 }
 583             },
 584             "ipv4-destination": "10.0.0.1/24"
 585         },
 586         "priority": "2",
 587     }
 588 }
 589 ----
 590 | Response Body
 591 |
 592 [source,json]
 593 ----
 594 {}
 595 ----
 596 | Return Codes
 597 | 201
 598 |===
 599
 600
 601 ===== Delete
 602
 603 [cols="h,5a"]
 604 |===
 605 | URL
 606 |  /restconf/config/opendaylight-inventory:nodes/node/[cmts id]/table/0/flow/[flow id]
 607
 608 | Method
 609 | DELETE
 610
 611 | Request Body
 612 |
 613 // include::flow-delete-request.json.adoc[]
 614 [source,json]
 615 ----
 616 {}
 617 ----
 618 | Response Body
 619 |
 620 // include::flow-delete-request.json.adoc[]
 621 [source,json]
 622 ----
 623 {}
 624 ----
 625 | Return Codes
 626 | 201
 627 |===
 628
 629
 630
 631 ==== Specifications and References
 632 The packetcable-driver was written to the
 633 link:http://www.cablelabs.com/wp-content/uploads/specdocs/PKT-SP-MM-I05-091029.pdf[PacketCable Specification Multimedia Specification PKT-SP-MM-I05-091029]