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

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