-== PacketCablePCMM
+
+== OpenDaylight Packet Cable MultiMedia (PCMM) Developer Guide
-Chapter on PacketCable PCMM
+=== Checking out the Packetcable PCMM project
+ git clone https://git.opendaylight.org/gerrit/p/packetcable.git
+The above command will create a directory called "packetcable" with the project.
+
+=== System Overview
+
+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.
+
+.System Overview
+image::pcmm-architecture.png["System Overview"]
+
+=== Dependency Map
+.Dependency Map
+image::pcmm-depends-map.png["Dependency Map", width=700 height=900]
+
+=== Packetcable Components
+
+packetcable is comprised of three OpendayLight bundles
+
+.Table of Bundle and Components
+[options="header"]
+|=======================
+| Bundle|Description
+| packetcable-model | Contains the YANG information model for flows and nodes
+| packetcable-provider | Provider hosts the model processing, RESTCONF, API implementation, and brokers requests to consumer
+| packetcable-driver | The codec for transforming the model into the appropriate PCMM Gate message for flows and CMTS connections
+| packetcable-consumer | The consumer is the codec for nodes and flows to gate messages
+|=======================
+
+
+See link:https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-model/src/main/yang[YANG Model]
+
+=== Download and Install
+
+Current instructions pertain to RC1
+
+==== Download
+
+link:http://nexus.opendaylight.org/content/groups/staging/org/opendaylight/integration/distribution-karaf/0.2.0-Helium-RC1/distribution-karaf-0.2.0-Helium-RC1.zip[Download]
+
+
+http://nexus.opendaylight.org/content/groups/staging/org/opendaylight/integration/distribution-karaf/
+
+==== Unzip
+[source, text]
+----
+unzip distribution-karaf-0.2.0-Helium-RC1.zip
+----
+
+
+==== Run Karaf
+[source, text]
+----
+cd distribution-karaf-0.2.0-Helium-RC1/bin/
+./karaf
+----
+
+=== Preparing to Work with the Packetcable PCMM Service
+
+==== Minimum install procedure?
+
+[source, text]
+----
+opendaylight-user@root>feature:install odl-packetcable-all
+----
+
+==== What features should we install?
+
+[source, text]
+----
+opendaylight-user@root>feature:install odl-l2switch-switch odl-restconf odl-mdsal-broker odl-restconf odl-adsal-all odl-openflowplugin-flow-services odl-openflowjava-protocol odl-ovsdb-all odl-openflow-nxm-extensions odl-adsal-compatibility odl-dlux-core odl-packetcable-all odl-mdsal-apidocs odl-mdsal-xsql
+----
+
+==== How is ODL auto starting a series of bundles using Karaf?
+
+Edit etc/org.apache.karaf.features.cfg ‘featuresBoot'
+[source, text]
+----
+#
+# Comma separated list of features to install at startup
+#
+featuresBoot=config,standard,region,package,kar,ssh,management,odl-l2switch-switch,odl-restconf,odl-mdsal-broker,odl-restconf,odl-adsal-all,odl-openflowplugin-flow-services,odl-openflowjava-protocol,odl-ovsdb-all,odl-openflow-nxm-extensions,odl-adsal-compatibility,,odl-dlux-core,odl-packetcable-all,odl-mdsal-apidocs,odl-mdsal-xsql
+
+----
+
+==== How can I create a system service to start Karaf?
+
+Install link:http://karaf.apache.org/manual/latest/users-guide/wrapper.html[Karaf Service Wrapper]
+[source, text]
+----
+opendaylight-user@root>feature:install service-wrapper
+opendaylight-user@root> wrapper:install
+Creating file: /home/user/odl/distribution-karaf-0.2.0-Helium-RC0/bin/karaf-wrapper
+Creating file: /home/user/odl/distribution-karaf-0.2.0-Helium-RC0/bin/karaf-service
+Creating file: /home/user/odl/distribution-karaf-0.2.0-Helium-RC0/etc/karaf-wrapper.conf
+Creating file: /home/user/odl/distribution-karaf-0.2.0-Helium-RC0/lib/libwrapper.so
+Creating file: /home/user/odl/distribution-karaf-0.2.0-Helium-RC0/lib/karaf-wrapper.jar
+Creating file: /home/user/odl/distribution-karaf-0.2.0-Helium-RC0/lib/karaf-wrapper-main.jar
+
+Setup complete. You may wish to tweak the JVM properties in the wrapper configuration file:
+/home/user/odl/distribution-karaf-0.2.0-Helium-RC0/etc/karaf-wrapper.conf
+before installing and starting the service.
+
+
+Ubuntu/Debian Linux system detected:
+ To install the service:
+ $ ln -s /home/user/odl/distribution-karaf-0.2.0-Helium-RC0/bin/karaf-service /etc/init.d/
+
+ To start the service when the machine is rebooted:
+ $ update-rc.d karaf-service defaults
+
+ To disable starting the service when the machine is rebooted:
+ $ update-rc.d -f karaf-service remove
+
+ To start the service:
+ $ /etc/init.d/karaf-service start
+
+ To stop the service:
+ $ /etc/init.d/karaf-service stop
+
+ To uninstall the service :
+ $ rm /etc/init.d/karaf-service
+
+----
+
+===== Accessing the Karaf Console
+[source, text]
+----
+ ssh -p 8101 karaf@localhost
+
+----
+
+===== Add These Directives to Your Operating System Profile to Change the Karaf Startup Parameters for Troubleshooting
+[source, text]
+----
+ export KARAF_DEBUG=true
+ export JAVA_DEBUG_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005"
+----
+
+===== Tell a Bundle to Log Debug
+[source, text]
+----
+ log:set org.opendaylight.packetcable.packetcable-provider
+----
+
+
+==== Management UI
+
+http://localhost:8181/dlux/index.html
+
+|=======================
+| user | admin
+| password | admin
+|=======================
+
+
+Sign in
+
+.Sign in to Dlux UI
+image:pcmm-dlux-login.png[Dlux Login]
+
+Manage Flows
+
+.View and Manage Flows in Dlux
+image::pcmm-dlux-flows.png[Dlux Flows]
+
+Manage Nodes
+
+.View and Manage Nodes in Dlux
+image::pcmm-dlux-nodes.png[Dlux Nodes]
+
+
+=== Explore and exercise the PacketCable REST API
+http://localhost:8181/apidoc/explorer/index.html
+
+
+
+=== RESTCONF API Explorer
+
+http://localhost:8181/apidoc/explorer/index.html
+
+Add a CMTS to Opendaylight Inventory
+
+.Add CMTS using RESTCONF Explorer
+image:pcmm-apidoc-explorer.png[Add CMTS using RESTCONF Explorer]
+
+
+=== Postman
+
+link:https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Configure the Chrome browser]
+
+Download and import sample
+link:https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-client[packetcable collection] for Postman.
+
+.Postman Collection for Packetcable PCMM
+image:pcmm-postman.png[Postman]
+
+== Custom Testsuite
+
+Most of the tests for RESTCONF can be adapted for PCMM and service flow testing. The following list of
+Packetcable client testing. Browse this folder for tests and examples used for testing.
+
+==== restconfapi.py
+
+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.
+
+
+==== flow_config_perf_pcmm.py
+For load testing there is this nice tool that could be repurpose to load test a CMTS.
+
+=== Using Wireshark to Trace PCMM
+To start wireshark with privileges issue the following command:
+[source, text]
+----
+sudo wireshark &
+----
+
+Select the interface to monitor.
+
+Use the Filter to only display COPS messages by applying “cops” in the filter field.
+.Using Wireshark to View COPS
+image:pcmm-wireshark.png[Wireshark]
+
+=== Debugging and Verifying DQoS Gate (Flows) on the CMTS
+
+Below are some of the most useful CMTS commands to verify flows have been enabled on the CMTS.
+
+==== Cisco
+
+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]
+
+
+=== Find the Cable Modem
+
+[source,text]
+----
+10k2-DSG#show cable modem
+ D
+MAC Address IP Address I/F MAC Prim RxPwr Timing Num I
+ State Sid (dBmv) Offset CPE P
+0010.188a.faf6 0.0.0.0 C8/0/0/U0 offline 1 0.00 1482 0 N
+74ae.7600.01f3 10.32.115.150 C8/0/10/U0 online 1 -0.50 1431 0 Y
+0010.188a.fad8 10.32.115.142 C8/0/10/UB w-online 2 -0.50 1507 1 Y
+000e.0900.00dd 10.32.115.143 C8/0/10/UB w-online 3 1.00 1677 0 Y
+e86d.5271.304f 10.32.115.168 C8/0/10/UB w-online 6 -0.50 1419 1 Y
+----
+
+==== Show PCMM Plugin Connection
+
+[source,text]
+----
+10k2-DSG#show packetcabl ?
+ cms Gate Controllers connected to this PacketCable client
+ event Event message server information
+ gate PacketCable gate information
+ global PacketCable global information
+
+10k2-DSG#show packetcable cms
+GC-Addr GC-Port Client-Addr COPS-handle Version PSID Key PDD-Cfg
+
+
+10k2-DSG#show packetcable cms
+GC-Addr GC-Port Client-Addr COPS-handle Version PSID Key PDD-Cfg
+10.32.0.240 54238 10.32.15.3 0x4B9C8150/1 4.0 0 0 0
+----
+
+==== Show COPS Messages
+
+[source,text]
+----
+debug cops details
+----
+
+==== Use CM Mac Address to List Service Flows
+
+[source,text]
+----
+10k2-DSG#show cable modem
+ D
+MAC Address IP Address I/F MAC Prim RxPwr Timing Num I
+ State Sid (dBmv) Offset CPE P
+0010.188a.faf6 --- C8/0/0/UB w-online 1 0.50 1480 1 N
+74ae.7600.01f3 10.32.115.150 C8/0/10/U0 online 1 -0.50 1431 0 Y
+0010.188a.fad8 10.32.115.142 C8/0/10/UB w-online 2 -0.50 1507 1 Y
+000e.0900.00dd 10.32.115.143 C8/0/10/UB w-online 3 0.00 1677 0 Y
+e86d.5271.304f 10.32.115.168 C8/0/10/UB w-online 6 -0.50 1419 1 Y
+
+
+10k2-DSG#show cable modem 000e.0900.00dd service-flow
+
+
+SUMMARY:
+MAC Address IP Address Host MAC Prim Num Primary DS
+ Interface State Sid CPE Downstream RfId
+000e.0900.00dd 10.32.115.143 C8/0/10/UB w-online 3 0 Mo8/0/2:1 2353
+
+
+Sfid Dir Curr Sid Sched Prio MaxSusRate MaxBrst MinRsvRate Throughput
+ State Type
+23 US act 3 BE 0 0 3044 0 39
+30 US act 16 BE 0 500000 3044 0 0
+24 DS act N/A N/A 0 0 3044 0 17
+
+
+
+UPSTREAM SERVICE FLOW DETAIL:
+
+SFID SID Requests Polls Grants Delayed Dropped Packets
+ Grants Grants
+23 3 784 0 784 0 0 784
+30 16 0 0 0 0 0 0
+
+
+DOWNSTREAM SERVICE FLOW DETAIL:
+
+SFID RP_SFID QID Flg Policer Scheduler FrwdIF
+ Xmits Drops Xmits Drops
+24 33019 131550 0 0 777 0 Wi8/0/2:2
+
+Flags Legend:
+$: Low Latency Queue (aggregated)
+~: CIR Queue
+----
+
+==== Deleting a PCMM Gate Message from the CMTS
+
+[source,text]
+----
+10k2-DSG#test cable dsd 000e.0900.00dd 30
+----
+
+==== Find service flows
+
+All gate controllers currently connected to the PacketCable client are displayed
+
+[source,text]
+----
+show cable modem 00:11:22:33:44:55 service flow ????
+show cable modem
+----
+
+
+==== Debug and display PCMM Gate messages
+[source,text]
+----
+debug packetcable gate control
+debug packetcable gate events
+show packetcable gate summary
+show packetcable global
+show packetcable cms
+----
+
+==== Debug COPS messages
+[source,text]
+----
+debug cops detail
+debug packetcable cops
+debug cable dynamic_qos trace
+----
+
+=== Arris
+
+Pending
+
+
+== RESTCONF API for Packetcable PCMM
+
+=== CMTS
+
+CMTS can be read, created, updated and deleted by a user having the
+correct role. An ID is used to identify where to read
+or save the CMTS node.
+
+==== Read
+
+[cols="h,5a"]
+|===
+| URL
+| /restconf/config/opendaylight-inventory:nodes/node/[id]/packetcable-cmts:cmts-node/
+
+| Method
+| GET
+
+| Request Body
+|
+// include::cmts-get-request.json.adoc[]
+[source,json]
+----
+{}
+----
+| Response Body
+|
+// include::cmts-get-response.json.adoc[]
+[source,json]
+----
+{}
+----
+| Return Codes
+| 201
+|===
+
+==== Create
+
+[cols="h,5a"]
+|===
+| URL
+| /restconf/config/opendaylight-inventory:nodes/node/[id]/packetcable-cmts:cmts-node/
+
+| Method
+| PUT
+
+| Request Body
+|
+// include::cmts-put-response.json.adoc[]
+[source,json]
+----
+{
+ "packetcable-cmts:cmts-node": {
+ "port": "3918",
+ "address": "10.200.90.3"
+ }
+}
+----
+| Response Body
+|
+[source,json]
+----
+{}
+----
+| Return Codes
+| 201
+|===
+
+
+==== Delete
+
+[cols="h,5a"]
+|===
+| URL
+| /restconf/config/opendaylight-inventory:nodes/node/[id]/packetcable-cmts:cmts-node/
+
+| Method
+| DELETE
+
+| Request Body
+|
+// include::cmts-delete-request.json.adoc[]
+[source,json]
+----
+{}
+----
+| Response Body
+|
+[source,json]
+----
+{}
+----
+| Return Codes
+| 201
+|===
+
+=== Flows
+
+Flows can be read, created, updated and deleted by a user having the
+correct role. A CMTS ID is used to identify which CMTS node to read
+or save the flow. Note: The Table ID is not used.
+
+==== Read
+
+[cols="h,5a"]
+|===
+| URL
+| /restconf/config/opendaylight-inventory:nodes/node/[cmts id]/table/0/flow/[flow id]
+
+| Method
+| GET
+
+| Request Body
+|
+// include::flow-get-request.json.adoc[]
+[source,json]
+----
+{}
+----
+| Response Body
+|
+// include::flow-get-response.json.adoc[]
+[source,json]
+----
+{
+ "flow": {
+ "cookie": "101",
+ "cookie_mask": "255",
+ "flow-name": "FooXf7",
+ "hard-timeout": "1200",
+ "id": "256",
+ "idle-timeout": "3400",
+ "installHw": "false",
+ "instructions": {
+ "instruction": {
+ "apply-actions": {
+ "action": {
+ "order": "0",
+ "traffic-profile": "best-effort"
+ }
+ },
+ "order": "0"
+ }
+ },
+ "match": {
+ "ethernet-match": {
+ "ethernet-type": {
+ "type": "34525"
+ }
+ },
+ "ip-match": {
+ "ip-dscp": "60",
+ "ip-ecn": "3",
+ "ip-protocol": "6"
+ },
+ "ipv6-destination": "fe80:2acf:e9ff:fe21::6431/94",
+ "ipv6-source": "1234:5678:9ABC:DEF0:FDCD:A987:6543:210F/76",
+ "tcp-destination-port": "8080",
+ "tcp-source-port": "183"
+ },
+ "priority": "2",
+ "strict": "false",
+ "table_id": "2"
+ }
+}
+----
+|===
+
+==== Create
+
+[cols="h,5a"]
+|===
+| URL
+| /restconf/config/opendaylight-inventory:nodes/node/[cmts id]/table/0/flow/[flow id]
+
+| Method
+| PUT
+
+| Request Body
+|
+// include::flow-put-response.json.adoc[]
+[source,json]
+----
+{
+ "flow": {
+ "barrier": "false",
+ "flow-name": "FooXCableFlowCrazyTrafficProfileFBesteffort1",
+ "id": "115",
+ "installHw": "false",
+ "instructions": {
+ "instruction": {
+ "apply-actions": {
+ "action": {
+ "traffic-profile": "best-effort",
+ "be-authorized-envelope": {
+ "traffic-priority":"0",
+ "reserved0":"0",
+ "reserved1":"0",
+ "request-transmission-policy":"0",
+ "maximum-sustained-traffic-rate":"0",
+ "maximum-traffic-burst":"3044",
+ "maximum-reserved-traffic-rate":"0",
+ "traffic-rate-packet-size-maximum-concatenated-burst":"0",
+ "assumed-minimum-reserved":"1522",
+ "required-attribute-mask":"0",
+ "forbidden-attribute-mask":"0",
+ "attribute-aggregation-rule-mask":"0",
+ },
+ "be-reserved-envelope": {
+ "traffic-priority":"0",
+ "reserved0":"0",
+ "reserved1":"0",
+ "request-transmission-policy":"0",
+ "maximum-sustained-traffic-rate":"0",
+ "maximum-traffic-burst":"3044",
+ "maximum-reserved-traffic-rate":"0",
+ "traffic-rate-packet-size-maximum-concatenated-burst":"0",
+ "assumed-minimum-reserved":"1522",
+ "required-attribute-mask":"0",
+ "forbidden-attribute-mask":"0",
+ "attribute-aggregation-rule-mask":"0",
+ },
+ "be-committed-envelope": {
+ "traffic-priority":"0",
+ "reserved0":"0",
+ "reserved1":"0",
+ "request-transmission-policy":"0",
+ "maximum-sustained-traffic-rate":"0",
+ "maximum-traffic-burst":"3044",
+ "maximum-reserved-traffic-rate":"0",
+ "traffic-rate-packet-size-maximum-concatenated-burst":"0",
+ "assumed-minimum-reserved":"1522",
+ "required-attribute-mask":"0",
+ "forbidden-attribute-mask":"0",
+ "attribute-aggregation-rule-mask":"0",
+ }
+
+ "order": "0"
+ }
+ },
+ "order": "0"
+ }
+ },
+ "match": {
+ "ethernet-match": {
+ "ethernet-type": {
+ "type": "2048"
+ }
+ },
+ "ipv4-destination": "10.0.0.1/24"
+ },
+ "priority": "2",
+ }
+}
+----
+| Response Body
+|
+[source,json]
+----
+{}
+----
+| Return Codes
+| 201
+|===
+
+
+==== Delete
+
+[cols="h,5a"]
+|===
+| URL
+| /restconf/config/opendaylight-inventory:nodes/node/[cmts id]/table/0/flow/[flow id]
+
+| Method
+| DELETE
+
+| Request Body
+|
+// include::flow-delete-request.json.adoc[]
+[source,json]
+----
+{}
+----
+| Response Body
+|
+// include::flow-delete-request.json.adoc[]
+[source,json]
+----
+{}
+----
+| Return Codes
+| 201
+|===
+
+
+=== Running the Packetcable PCMM project
+If you need additional resources, you can use these command line arguments:
+
+ -Xms1024m -Xmx2048m -XX:PermSize=512m -XX:MaxPermSize=1024m
+
+
+=== Specifications and References
+The packetcable-driver was written to the
+link:http://www.cablelabs.com/wp-content/uploads/specdocs/PKT-SP-MM-I05-091029.pdf[PacketCable Specification Multimedia Specification PKT-SP-MM-I05-091029]
-== PacketCablePCMM
-Chapter on PacketCable PCMM
+== OpenDaylight Packet Cable MultiMedia (PCMM) Service User Guide
+Packet Cable MultiMedia (PCMM) provides an interface to control and management service flow for CMTS network elements. A service flows constitute a DOCSIS data path between a CMTS and a subscriber's cable modem (CM) guaranteed application specific quality of service (QoS), known as Dynamic Quality of Service (DQoS). PCMM offers (MSOs) the ability to deliver new services using existing cable infrastructure. MSOs have already begun to apply PCMM technology for expanding their multimedia service offerings.
+
+== Overview
+
+The PCMM architecture comprises the following components:
+
+* The Application Manager, which specifies QoS requirements to the Policy Server on a per-application basis.
+* The Policy Server, which allocates network resources per subscriber and per application, ensuring that consumption meets MSO priorities.
+* The Cable Modem Termination System (CMTS), which enforces policies according to bandwidth capacity.
+* The Cable Modem, which resides on the client side and connects the client's network to the cable system.
+
+PacketCable Multimedia defines a service delivery framework that provides general-purpose QoS, event-based accounting, and security functionality founded upon the mechanisms defined in PacketCable 1.x. However, due to the broader spectrum of applications and services addressed by this initiative, each of these functional areas has been revisited and generalized for the present purposes. Telephony-specific requirements and interfaces (e.g., call signaling, PSTN interconnection and electronic surveillance) are not part of PacketCable Multimedia, while core functionality such as QoS resource management mechanisms, has been enhanced. Throughout this process, one of the primary objectives of this work has been to leverage and reuse as much of the existing body of PacketCable 1.x investment, knowledge base, and technical functionality as possible. Key features of the described Multimedia service delivery framework include:
+
+* Simple, powerful access to DOCSIS QoS mechanisms supporting both time and volume-based network resource authorizations,
+* Abstract, event-based network resource auditing and management mechanisms,
+* A robust security infrastructure that provides integrity and appropriate levels of protection across all interfaces.
+
+The goal of this project is to utilizes the OpenDayLight controller platform as for the Application Manager and parts of the Policy Server and leverage the as many existing components offered by the platform.
+
+The initial southbound transport has been written to the following version of the specification: http://www.cablelabs.com/wp-content/uploads/specdocs/PKT-SP-MM-I05-091029.pdf
+
+== Architecture Overview
+.Architecture Overview
+image::pcmm-docsis.jpg["Architecture Overview", width=512]
+
+The OpenDaylight Packetcable PCMM includes:
+
+* Packetcable PCMM Provider
+* Packetcable PCMM Consumer
+* Packetcable PCMM Model
+* Southbound ODL plugin supporting PCMM/COPS protocol driver
+* Packetcable PCMM RESTCONF Service API
+
+=== Packetcable PCMM Architecture
+
+The following figure shows the various Packetcable PCMM modules.
+
+.Packetcable PCMM Service Internal Architecture
+
+image::pcmm-technical-arch-overview-helium.jpg["Packetcable PCMM Service Internal Architecture", width=460]
+
+A brief description of some of what this feature has to offer:
+
+* Provision a CMTS
+* Flow Programmer match-only for managing DOCSIS (service) flows
+* Northbound APIs for provisioning CMTS network elements
+* HTML Provisioning Interface or some Python RESTful examples
+* Northbound APIs for provisioning Service Flow values and types
+* Northbound APIs for provisioning QoS (or metering) parameters
+* SAL extensions for DOCSIS specific data model and configuration APIs
+* Southbound PCMM/COPS transport plugin
+
+
+The following figure depicts the described components.
+
+
+=== Packetcable PCMM Support
+
+For support please contact the packetcable project at:
+
+* PCMM PacketCable mailing list: dev@lists.opendaylight.org
Code Review / docs.git / commitdiff
