docs/developer-guide/packetcable-developer-guide.rst

   1 PacketCable Developer Guide
   2 ===========================
   3
   4 PCMM Specification
   5 ------------------
   6
   7 `PacketCable™ Multimedia
   8 Specification <http://www.cablelabs.com/specification/packetcable-multimedia-specification>`__
   9
  10 System Overview
  11 ---------------
  12
  13 These components introduce a DOCSIS QoS Service Flow management using
  14 the PCMM protocol. The driver component is responsible for the
  15 PCMM/COPS/PDP functionality required to service requests from
  16 PacketCable Provider and FlowManager. Requests are transposed into PCMM
  17 Gate Control messages and transmitted via COPS to the CCAP/CMTS. This
  18 plugin adheres to the PCMM/COPS/PDP functionality defined in the
  19 CableLabs specification. PacketCable solution is an MDSAL compliant
  20 component.
  21
  22 PacketCable Components
  23 ----------------------
  24
  25 The packetcable maven project is comprised of several modules.
  26
  27 +--------------------------------------+--------------------------------------+
  28 | Bundle                               | Description                          |
  29 +======================================+======================================+
  30 | packetcable-driver                   | A common module that containts the   |
  31 |                                      | COPS stack and manages all           |
  32 |                                      | connections to CCAPS/CMTSes.         |
  33 +--------------------------------------+--------------------------------------+
  34 | packetcable-emulator                 | A basic CCAP emulator to facilitate  |
  35 |                                      | testing the the plugin when no       |
  36 |                                      | physical CCAP is avaible.            |
  37 +--------------------------------------+--------------------------------------+
  38 | packetcable-policy-karaf             | Generates a Karaf distribution with  |
  39 |                                      | a config that loads all the          |
  40 |                                      | packetcable features at runtime.     |
  41 +--------------------------------------+--------------------------------------+
  42 | packetcable-policy-model             | Contains the YANG information model. |
  43 +--------------------------------------+--------------------------------------+
  44 | packetcable-policy-server            | Provider hosts the model processing, |
  45 |                                      | RESTCONF, and API implementation.    |
  46 +--------------------------------------+--------------------------------------+
  47
  48 Setting Logging Levels
  49 ~~~~~~~~~~~~~~~~~~~~~~
  50
  51 From the Karaf console
  52
  53 ::
  54
  55     log:set <LEVEL> (<PACKAGE>|<BUNDLE>)
  56     Example
  57     log:set DEBUG org.opendaylight.packetcable.packetcable-policy-server
  58
  59 Tools for Testing
  60 -----------------
  61
  62 Postman REST client for Chrome
  63 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  64
  65 `Install the Chrome
  66 extension <https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en>`__
  67
  68 `Download and import sample packetcable
  69 collection <https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-policy-server/doc/restconf-samples>`__
  70
  71 View Rest API
  72 ~~~~~~~~~~~~~
  73
  74 1. Install the ``odl-mdsal-apidocs`` feature from the karaf console.
  75
  76 2. Open http://localhost:8181/apidoc/explorer/index.html default dev
  77    build user/pass is admin/admin
  78
  79 3. Navigate to the PacketCable section.
  80
  81 Yang-IDE
  82 ~~~~~~~~
  83
  84 Editing yang can be done in any text editor but Yang-IDE will help
  85 prevent mistakes.
  86
  87 `Setup and Build Yang-IDE for
  88 Eclipse <https://github.com/xored/yang-ide/wiki/Setup-and-build>`__
  89
  90 Using Wireshark to Trace PCMM
  91 -----------------------------
  92
  93 1. To start wireshark with privileges issue the following command:
  94
  95    ::
  96
  97        sudo wireshark &
  98
  99 2. Select the interface to monitor.
 100
 101 3. Use the Filter to only display COPS messages by applying “cops” in
 102    the filter field.
 103
 104    .. figure:: ./images/packetcable-developer-wireshark.png
 105
 106       Wireshark looking for COPS messages.
 107
 108 Debugging and Verifying DQoS Gate (Flows) on the CCAP/CMTS
 109 ----------------------------------------------------------
 110
 111 Below are some of the most useful CCAP/CMTS commands to verify flows
 112 have been enabled on the CMTS.
 113
 114 Cisco
 115 ~~~~~
 116
 117 `Cisco CMTS Cable Command
 118 Reference <http://www.cisco.com/c/en/us/td/docs/cable/cmts/cmd_ref/b_cmts_cable_cmd_ref.pdf>`__
 119
 120 Find the Cable Modem
 121 ~~~~~~~~~~~~~~~~~~~~
 122
 123 ::
 124
 125     10k2-DSG#show cable modem
 126                                                                                       D
 127     MAC Address    IP Address      I/F           MAC           Prim RxPwr  Timing Num I
 128                                                  State         Sid  (dBmv) Offset CPE P
 129     0010.188a.faf6 0.0.0.0         C8/0/0/U0     offline       1    0.00   1482   0   N
 130     74ae.7600.01f3 10.32.115.150   C8/0/10/U0    online        1    -0.50  1431   0   Y
 131     0010.188a.fad8 10.32.115.142   C8/0/10/UB    w-online      2    -0.50  1507   1   Y
 132     000e.0900.00dd 10.32.115.143   C8/0/10/UB    w-online      3    1.00   1677   0   Y
 133     e86d.5271.304f 10.32.115.168   C8/0/10/UB    w-online      6    -0.50  1419   1   Y
 134
 135 Show PCMM Plugin Connection
 136 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 137
 138 ::
 139
 140     10k2-DSG#show packetcabl ?
 141       cms     Gate Controllers connected to this PacketCable client
 142       event   Event message server information
 143       gate    PacketCable gate information
 144       global  PacketCable global information
 145
 146     10k2-DSG#show packetcable cms
 147     GC-Addr        GC-Port  Client-Addr    COPS-handle  Version PSID Key PDD-Cfg
 148
 149
 150     10k2-DSG#show packetcable cms
 151     GC-Addr        GC-Port  Client-Addr    COPS-handle  Version PSID Key PDD-Cfg
 152     10.32.0.240    54238    10.32.15.3     0x4B9C8150/1    4.0   0    0   0
 153
 154 Show COPS Messages
 155 ~~~~~~~~~~~~~~~~~~
 156
 157 ::
 158
 159     debug cops details
 160
 161 Use CM Mac Address to List Service Flows
 162 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 163
 164 ::
 165
 166     10k2-DSG#show cable modem
 167                                                                                       D
 168     MAC Address    IP Address      I/F           MAC           Prim RxPwr  Timing Num I
 169                                                  State         Sid  (dBmv) Offset CPE P
 170     0010.188a.faf6 ---             C8/0/0/UB     w-online      1    0.50   1480   1   N
 171     74ae.7600.01f3 10.32.115.150   C8/0/10/U0    online        1    -0.50  1431   0   Y
 172     0010.188a.fad8 10.32.115.142   C8/0/10/UB    w-online      2    -0.50  1507   1   Y
 173     000e.0900.00dd 10.32.115.143   C8/0/10/UB    w-online      3    0.00   1677   0   Y
 174     e86d.5271.304f 10.32.115.168   C8/0/10/UB    w-online      6    -0.50  1419   1   Y
 175
 176
 177     10k2-DSG#show cable modem 000e.0900.00dd service-flow
 178
 179
 180     SUMMARY:
 181     MAC Address    IP Address      Host          MAC           Prim  Num Primary    DS
 182                                    Interface     State         Sid   CPE Downstream RfId
 183     000e.0900.00dd 10.32.115.143   C8/0/10/UB    w-online      3     0   Mo8/0/2:1  2353
 184
 185
 186     Sfid  Dir Curr  Sid   Sched  Prio MaxSusRate  MaxBrst     MinRsvRate  Throughput
 187               State       Type
 188     23    US  act   3     BE     0    0           3044        0           39
 189     30    US  act   16    BE     0    500000      3044        0           0
 190     24    DS  act   N/A   N/A    0    0           3044        0           17
 191
 192
 193
 194     UPSTREAM SERVICE FLOW DETAIL:
 195
 196     SFID  SID   Requests   Polls      Grants     Delayed    Dropped    Packets
 197                                                  Grants     Grants
 198     23    3     784        0          784        0          0          784
 199     30    16    0          0          0          0          0          0
 200
 201
 202     DOWNSTREAM SERVICE FLOW DETAIL:
 203
 204     SFID  RP_SFID QID    Flg Policer               Scheduler             FrwdIF
 205                              Xmits      Drops      Xmits      Drops
 206     24    33019   131550     0          0          777        0          Wi8/0/2:2
 207
 208     Flags Legend:
 209     $: Low Latency Queue (aggregated)
 210     ~: CIR Queue
 211
 212 Deleting a PCMM Gate Message from the CMTS
 213 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 214
 215 ::
 216
 217     10k2-DSG#test cable dsd  000e.0900.00dd 30
 218
 219 Find service flows
 220 ~~~~~~~~~~~~~~~~~~
 221
 222 All gate controllers currently connected to the PacketCable client are
 223 displayed
 224
 225 ::
 226
 227     show cable modem 00:11:22:33:44:55 service flow   ????
 228     show cable modem
 229
 230 Debug and display PCMM Gate messages
 231 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 232
 233 ::
 234
 235     debug packetcable gate control
 236     debug packetcable gate events
 237     show packetcable gate summary
 238     show packetcable global
 239     show packetcable cms
 240
 241 Debug COPS messages
 242 ~~~~~~~~~~~~~~~~~~~
 243
 244 ::
 245
 246     debug cops detail
 247     debug packetcable cops
 248     debug cable dynamic_qos trace
 249
 250 Integration Verification
 251 ------------------------
 252
 253 Checkout the integration project and perform regression tests.
 254
 255 ::
 256
 257     git clone ssh://${ODL_USERNAME}@git.opendaylight.org:29418/integration.git
 258     git clone https:/git.opendaylight.org/gerrit/integration.git
 259
 260 1. Check and edit the
 261    integration/features/src/main/resources/features.xml and follow the
 262    directions there.
 263
 264 2. Check and edit the integration/features/pom.xml and add a dependency
 265    for your feature file
 266
 267 3. Build integration/features and debug
 268
 269 ``  mvn clean install``
 270
 271 Test your feature in the integration/distributions/extra/karaf/
 272 distribution
 273
 274 ::
 275
 276     cd integration/distributions/extra/karaf/
 277     mvn clean install
 278     cd target/assembly/bin
 279     ./karaf
 280
 281 service-wrapper
 282 ~~~~~~~~~~~~~~~
 283
 284 Install http://karaf.apache.org/manual/latest/users-guide/wrapper.html
 285
 286 ::
 287
 288     opendaylight-user@root>feature:install service-wrapper
 289     opendaylight-user@root>wrapper:install --help
 290     DESCRIPTION
 291             wrapper:install
 292
 293     Install the container as a system service in the OS.
 294
 295     SYNTAX
 296             wrapper:install [options]
 297
 298     OPTIONS
 299             -d, --display
 300                     The display name of the service.
 301                     (defaults to karaf)
 302             --help
 303                     Display this help message
 304             -s, --start-type
 305                     Mode in which the service is installed. AUTO_START or DEMAND_START (Default: AUTO_START)
 306                     (defaults to AUTO_START)
 307             -n, --name
 308                     The service name that will be used when installing the service. (Default: karaf)
 309                     (defaults to karaf)
 310             -D, --description
 311                     The description of the service.
 312                     (defaults to )
 313
 314     opendaylight-user@root> wrapper:install
 315     Creating file: /home/user/odl/distribution-karaf-0.5.0-Boron/bin/karaf-wrapper
 316     Creating file: /home/user/odl/distribution-karaf-0.5.0-Boron/bin/karaf-service
 317     Creating file: /home/user/odl/distribution-karaf-0.5.0-Boron/etc/karaf-wrapper.conf
 318     Creating file: /home/user/odl/distribution-karaf-0.5.0-Boron/lib/libwrapper.so
 319     Creating file: /home/user/odl/distribution-karaf-0.5.0-Boron/lib/karaf-wrapper.jar
 320     Creating file: /home/user/odl/distribution-karaf-0.5.0-Boron/lib/karaf-wrapper-main.jar
 321
 322     Setup complete.  You may wish to tweak the JVM properties in the wrapper configuration file:
 323     /home/user/odl/distribution-karaf-0.5.0-Boron/etc/karaf-wrapper.conf
 324     before installing and starting the service.
 325
 326
 327     Ubuntu/Debian Linux system detected:
 328       To install the service:
 329         $ ln -s /home/user/odl/distribution-karaf-0.5.0-Boron/bin/karaf-service /etc/init.d/
 330
 331       To start the service when the machine is rebooted:
 332         $ update-rc.d karaf-service defaults
 333
 334       To disable starting the service when the machine is rebooted:
 335         $ update-rc.d -f karaf-service remove
 336
 337       To start the service:
 338         $ /etc/init.d/karaf-service start
 339
 340       To stop the service:
 341         $ /etc/init.d/karaf-service stop
 342
 343       To uninstall the service :
 344         $ rm /etc/init.d/karaf-service
 345