CDRouter USP User Guide

Introduction

User Services Platform

The User Services Platform (USP), as defined in Broadband Forum TR-369, is the next generation of the TR-069 protocol. It’s lighter weight, more flexible and adds some powerful new features.

In the TR-069 domain all messages are transported over HTTP or HTTPS. In some cases, XMPP is used for connection requests. In contrast, USP has far more combinations to test. Messages can be transported over WebSockets, MQTT (version 3.1.1 or 5) or STOMP each with optional encryption. Additionally, each exchange between endpoints can optionally use a session context, optionally encrypt the USP payload and optionally segment payloads at the USP layer.

The CDRouter USP expansion adds USP test capabilities to CDRouter, allowing you to test under all the conditions mentioned in a simple easy to configure way.

The full specification for USP can be found at usp.technology.

Terminology

Term Description
Agent An Agent is an Endpoint that exposes Service Elements to one or more Controllers.
Controller A Controller is an Endpoint that manipulates Service Elements through one or more Agents.
Endpoint An Endpoint is a termination point for a Message.
Record The Record is defined as the Message Transfer Protocol (MTP) payload, encapsulating a sequence of datagrams that comprise the Message as well as providing additional metadata needed for providing integrity protection, payload protection and delivery of fragmented Messages.
Endpoint ID A unique identifier assigned to a USP endpoint.
MTP Message Transport Protocol, the protocol used to transport USP records.
Message The payload within the USP record.
Session Context A set of additional fields that are exchanged between USP endpoints which allow either side to reassemble out of order records, request retransmission of missed records, authenticate messages as coming from allowed endpoints and encrypt messages to allow secure communication between endpoints.
Path A MTP specific string which is used in the transportation of USP messages between endpoints.
USP Encryption A method of encrypting the USP payload with TLS that is available when using session contexts.

Requirements and License

CDRouter USP is available for CDRouter 11.0 and newer releases only.

Licensing

CDRouter USP is a licensed expansion that must be purchased from QA Cafe. For information on upgrading a license to include CDRouter USP or any other expansions, please contact sales@qacafe.com.

CDRouter will report the status of all available expansions during the installation process and during start-up. To verify that CDRouter USP is enabled on a system, run the command cdrouter-cli -info as root and look for the line USP is enabled, as shown below. If this line is present, CDRouter USP is enabled and ready to use.

$ cdrouter-cli -info

Starting /usr/cdrouter/bin/cdrouter-cli Thu Mar 15 11:12:22 EDT 2018
Copyright (c) 2001-2018 by QA Cafe
Version 11.0 build 0 (b1081f6e0 master), built 2018-03-14 10:51:06 by nightly@cdr-forge6.lan (x86_64)
OS: CentOS Linux 7.4.1708 (4.4.87-1.el7.qacafe.x86_64)
CPU: Intel(R) Core(TM) i5-7600K CPU @ 3.80GHz
Loaded modules from: '/usr/cdrouter/tests'
Start command: /usr/cdrouter/bin/cdrouter-cli -info
System ID: b2d8619a16720c7c3fc0835500badc15
Registered to: qacafe
Maintenance, support and upgrades until: 2085-01-01
Test suite: cdrouter
    Multiport   is enabled
    IPv6        is enabled
    Storage     is enabled
    IKE         is enabled
    TR69        is enabled
    TR69-EDM    is enabled
    Nmap        is enabled
    BBF.069     is enabled
    SNMP        is enabled
    Performance is enabled
    ICS         is enabled
    DOCSIS      is enabled
    USP         is enabled

Test Methodology

Overview

The network topology of USP endpoints is highly flexible by design. In CWMP the only topology is one in which the TR-069 client is either a gateway or behind a gateway on the LAN side of a network and a single ACS sits somewhere on the internet. While this configuration is still valid in USP, it is by no means the only option. The USP standard was designed not only from the perspective of organizations controlling their products remotely but also from consumers controlling the products in their home. For this reason USP is designed to enable the configuration of an agent from one or more controllers that exist within the same network.

CDRouter is capable of testing common USP network topologies. CDRouter’s USP controller will always be configured on CDRouter’s simulated WAN, but a directly connected agent can be tested using any of the MTPs. Additionally with WebSockets and STOMP, an agent can be placed behind a gateway. For all USP testing CDRouter’s full suite of network address provisioning mechanisms are available for use.

The USP expansion supports all MTPs with or without TLS over both IPv4 and IPv6 and with or without USP layer encryption. All the defined message types are supported as well as segmentation of both USP records and TLS records at the USP layer.

The following MTP, MTP encryption, USP encryption, IP version options are testable using the USP CDRouter expansion:

MTP Supported MTP Encryption Supported USP Encryption Supported IP Versions Supports USP Segmentation
WebSocket TLS or None TLS v1.2 or None IPv4 or IPv6 Yes
STOMP TLS or None TLS v1.2 or None IPv4 or IPv6 Yes
MQTT (v5) TLS or None TLS v1.2 or None IPv4 or IPv6 Yes
MQTT (v3.1.1) TLS or None TLS v1.2 or None IPv4 or IPv6 Yes

What is not supported:

When using TLS at the USP layer CDRouter uses a certificate that does not include the controller’s endpoint ID in the subjectAltName field. This is because the certificate used by CDRouter’s controller is signed by a trusted CA and the controller’s endpoint ID is configurable. Additionally CDRouter will not validate that the subjectAltName of certificates sent by an agent contains the endpoint ID of the agent. If the agent being tested validates the subjectAltName in the certificate it receives from the controller this can be overcome by providing certs for the controller to use by setting uspControllerUSPCertPath and uspControllerUSPCaCertPath to the path to a certificate/CA certificate pair that the agent will accept (note that this may also require setting uspControllerID to match the endpoint ID in the subjectAltName in the provided certificate).

Initial Setup

CDRouter’s USP controller runs on the WAN interface. This presents three possible setups for testing USP Agents.

Test Setup #1

If the USP Agent is accessible via the WAN connection on a gateway, the setup is the same as the basic CDRouter test setup for CWMP:

USP test setup for gateway device

Test Setup #2

If the USP Agent is on an end-device, you can use an additional gateway as part of your test setup.

USP test setup for end device through a gateway

Test Setup #3

Alternatively, you can connect a USP Agent directly to CDRouter’s WAN port and run your testing without the LAN port configured.

USP test setup for end device directly connected

Configuration

This section covers the most commonly used testvar settings needed to allow the USP agent (DUT) to connect to CDRouter’s USP Controller. Some of these testvars may not be needed for certain types of environments and may be ignored.

testvar supportsUSP yes

testvar uspControllerID myControllerID
testvar uspControllerIpMode ipv4-only
testvar uspControllerIpv4 6.0.0.2
testvar uspControllerIpv6 6000::2
testvar uspControllerDomain controller.cdroutertest.com

testvar uspControllerMTP stomp
testvar uspControllerMTPEncryption yes
testvar uspControllerMTPCertPath /usr/cdrouter-data/custom/mycert.pem
testvar uspControllerMTPCaCertPath /usr/cdrouter-data/custom/mycert-ca.pem
testvar uspControllerPort auto 
testvar uspControllerPath /controllerendpoint

testvar uspControllerUseSessionContext   yes
testvar uspControllerUSPEncryption       yes
testvar uspControllerUSPCertPath /usr/cdrouter-data/custom/mycert.pem
testvar uspControllerUSPCaCertPath /usr/cdrouter-data/custom/mycert.pem

testvar uspAgentIpv4 auto
testvar uspAgentIpv6 auto
testvar uspAgentID proto::agent-id
testvar uspAgentPort auto
testvar uspAgentPath /agent-path

Each of these testvars are explained in more detail below.

Enabling the Controller

In order to run any of the USP test cases the USP controller must be enabled. This is done by setting supportsUSP to “yes”.

testvar supportsUSP yes

Configuring the Controller

Setting the Controller ID

If the USP agent expects the controller to have a specific endpoint ID this can be configured by setting uspControllerID to the desired ID.

testvar uspControllerID  myControllerID

Setting the Controller’s Address

The USP controller can be configured to run over IPv4 or IPv6. This is done by setting uspControllerIpMode to either “ipv4-only” or “ipv6-only”.

Once a IP version has been selected the controller’s IP address can be configured by setting uspControllerIpv4 for an IPv4 address

testvar uspControllerIpMode ipv4-only
testvar uspControllerIpv4   6.0.0.2

or uspControllerIpv6 for an IPv6 address.

testvar uspControllerIpMode ipv6-only
testvar uspControllerIpv6 6000::2

CDRouter will also add a DNS entry mapping the configured IP address of the controller to a domain name. To specify the domain named used set uspControllerDomain to the desired domain name.

Setting the MTP

CDRouter has support for all four MTPs:

To configure the specific MTP set uspControllerMTP to “stomp”, “websocket”, “mqtt” (for MQTTv5) or “mqttv3” (for MQTTv3.1.1). If using WebSockets the path component of the controller’s endpoint URI can be configured using uspControllerPath. The testvar uspControllerPath is also used to configure the destination controller subscribes to on the STOMP or MQTT server.

To enable MTP level TLS set uspControllerMTPEncryption to “yes”.

testvar uspControllerMTP           stomp
testvar uspControllerMTPEncryption yes
testvar uspControllerPath          /controllerendpoint

By default the USP controller will use wildcard certificates signed by Comodo for MTP layer encryption. If a different set of certificates should be used, it can be configured by setting uspControllerMTPCertPath and uspControllerMTPCaCertPath to the appropriate paths.

testvar uspControllerMTPCertPath     /usr/cdrouter-data/custom/mycert.pem
testvar uspControllerMTPCaCertPath   /usr/cdrouter-data/custom/mycert-ca.pem

To specify the port the controller should listen on for incoming connections set uspControllerPort to the desired port number. Setting this testvar to “auto” will cause CDRouter to use the default port for the MTP based off the values of uspControllerMTP and uspControllerMTPEncryption.

Additional Configuration for STOMP and MQTT

When using STOMP or MQTT as the MTP, CDRouter will configure the login credentials on the STOMP/MQTT server using uspControllerUsername and uspControllerPassword. Additionally CDRouter’s STOMP server can be configured to only accept specific values in the “host” header of the STOMP frame by setting uspControllerHost to the value the agent will provide.

Setting the Controller’s Default USP Behavior

CDRouter’s default behavior when it starts a new USP session can be configured.

By default the USP controller will wait 30 seconds for an agent to reply to a message. This can be configured by setting uspMessageTimeout.

testvar uspMessageTimeout 90

By default the USP controller will not use session contexts, nor will it use USP level security. To enable the use of session contexts set uspControllerUseSessionContext to “yes”. If uspControllerUseSessionContext is set to “yes”, it is also possible to configure the controller to use USP level security by setting uspControllerUSPEncryption to “yes”.

testvar uspControllerUseSessionContext   yes
testvar uspControllerUSPEncryption       yes

CDRouter’s USP controller will also use the Comodo signed certs by default for USP layer encryption. If a different set of certificates should be used, it can be configured by setting uspControllerUSPCertPath and uspControllerUSPCaCertPath to the appropriate paths.

testvar uspControllerUSPCertPath      /usr/cdrouter-data/custom/mycert.pem
testvar uspControllerUSPCaCertPath    /usr/cdrouter-data/custom/mycert.pem

Configuring the Agent

Agent IP Address

The IP address of the agent is needed to allow the controller to connect to the agent. If the agent will be getting an address from CDRouter both uspAgentIp testvars can be set to “auto”.

If the agent already has a IPv4 or IPv6 address, set uspAgentIpv4 and uspAgentIpv6 respectively.

testvar uspAgentIpv4 10.0.0.6
testvar uspAgentIpv6 auto

USP Settings on the Agent

The USP controller will send messages to the agent using the agent ID set in uspAgentID. If the value of this testvar does not match the agent’s endpoint ID the controller will ignore messages from the agent, and packages will not pass start.

The port on which the agent is listening for a connection is set by configuring uspAgentPort to the port number. If the value “auto” is used, the default port for the MTP will be selected the same way it is for uspControllerPort.

The agent resource path is set by configuring uspAgentPath to the URI.

OB-USP-Agent

The Broadband Forum’s OB-USP-Agent is a popular open-source User Services Platform (USP) agent reference implementation. It enables communication and control of connected devices by utilizing parameters from the Device:2 data model.

For a detailed overview and initial setup steps, refer to the OB-USP-Agent Quick Start Guide.

OB-USP-Agent Configuration Example (STOMP)

The following minimal OB-USP-Agent configuration uses unencrypted STOMP as an MTP and is compatible with CDRouter’s default controller configuration:

OB-USP-Agent Parameter Value
Device.LocalAgent.EndpointID “proto::agent-id”
Device.STOMP.Connection.1.Enable “true”
Device.STOMP.Connection.1.Port “61613”
Device.STOMP.Connection.1.X_ARRIS-COM_EnableEncryption “false”
Device.STOMP.Connection.1.Host “controller.cdroutertest.com”
Device.STOMP.Connection.1.Username “qacafe”
Device.STOMP.Connection.1.Password “qacafe123”
Device.LocalAgent.MTP.1.Enable “true”
Device.LocalAgent.MTP.1.Protocol “STOMP”
Device.LocalAgent.MTP.1.STOMP.Destination “/agent-path”
Device.LocalAgent.MTP.1.STOMP.Reference “Device.STOMP.Connection.1”
Device.LocalAgent.Controller.1.Enable “true”
Device.LocalAgent.Controller.1.EndpointID “proto::controller-id”
Device.LocalAgent.Controller.1.MTP.1.Enable “true”
Device.LocalAgent.Controller.1.MTP.1.Protocol “STOMP”
Device.LocalAgent.Controller.1.MTP.1.STOMP.Reference “Device.STOMP.Connection.1”
Device.LocalAgent.Controller.1.MTP.1.STOMP.Destination “/controller-path”

This maps to the following CDRouter agent and controller configuration testvars:

testvar uspAgentID                        proto::agent-id
testvar uspAgentPath                      /agent-path
testvar uspControllerID                   proto::controller-id
testvar uspControllerMTP                  stomp
testvar uspControllerPort                 auto
testvar uspControllerPath                 /controller-path
testvar uspControllerUsername             qacafe
testvar uspControllerPassword             qacafe123
testvar uspControllerDomain               controller.cdroutertest.com
testvar uspControllerMTPEncryption        no

OB-USP-Agent Configuration Example (MQTTv5)

The following minimal OB-USP-Agent configuration uses unencrypted MQTTv5 as an MTP and is compatible with CDRouter’s default controller configuration:

OB-USP-Agent Parameter Value
Device.LocalAgent.EndpointID “proto::agent-id”
Device.MQTT.Client.1.BrokerAddress “controller.cdroutertest.com”
Device.MQTT.Client.1.ProtocolVersion “5.0”
Device.MQTT.Client.1.BrokerPort “1883”
Device.MQTT.Client.1.TransportProtocol “TCP/IP”
Device.MQTT.Client.1.Username “qacafe”
Device.MQTT.Client.1.Password “qacafe123”
Device.MQTT.Client.1.Enable “true”
Device.LocalAgent.MTP.1.Enable “true”
Device.LocalAgent.MTP.1.Protocol “MQTT”
Device.LocalAgent.MTP.1.MQTT.ResponseTopicConfigured “/agent-path”
Device.LocalAgent.MTP.1.MQTT.Reference “Device.MQTT.Client.1”
Device.LocalAgent.Controller.1.Enable “true”
Device.LocalAgent.Controller.1.EndpointID “proto::controller-id”
Device.LocalAgent.Controller.1.MTP.1.Enable “true”
Device.LocalAgent.Controller.1.MTP.1.Protocol “MQTT”
Device.LocalAgent.Controller.1.MTP.1.MQTT.Reference “Device.MQTT.Client.1”
Device.LocalAgent.Controller.1.MTP.1.MQTT.Topic “/controller-path”

This maps to the following CDRouter agent and controller configuration testvars:

testvar uspAgentID                        proto::agent-id
testvar uspAgentPath                      /agent-path
testvar uspControllerID                   proto::controller-id
testvar uspControllerMTP                  mqtt
testvar uspControllerPort                 auto
testvar uspControllerPath                 /controller-path
testvar uspControllerUsername             qacafe
testvar uspControllerPassword             qacafe123
testvar uspControllerDomain               controller.cdroutertest.com
testvar uspControllerMTPEncryption        no

OB-USP-Agent Configuration Example (MQTTv3.1.1)

The following minimal OB-USP-Agent configuration uses unencrypted MQTTv3.1.1 as an MTP and is compatible with CDRouter’s default controller configuration:

OB-USP-Agent Parameter Value
Device.LocalAgent.EndpointID “proto::agent-id”
Device.MQTT.Client.1.BrokerAddress “controller.cdroutertest.com”
Device.MQTT.Client.1.ProtocolVersion “3.1.1”
Device.MQTT.Client.1.BrokerPort “1883”
Device.MQTT.Client.1.TransportProtocol “TCP/IP”
Device.MQTT.Client.1.Username “qacafe”
Device.MQTT.Client.1.Password “qacafe123”
Device.MQTT.Client.1.Enable “true”
Device.LocalAgent.MTP.1.Enable “true”
Device.LocalAgent.MTP.1.Protocol “MQTT”
Device.LocalAgent.MTP.1.MQTT.ResponseTopicConfigured “/agent-path”
Device.LocalAgent.MTP.1.MQTT.Reference “Device.MQTT.Client.1”
Device.LocalAgent.Controller.1.Enable “true”
Device.LocalAgent.Controller.1.EndpointID “proto::controller-id”
Device.LocalAgent.Controller.1.MTP.1.Enable “true”
Device.LocalAgent.Controller.1.MTP.1.Protocol “MQTT”
Device.LocalAgent.Controller.1.MTP.1.MQTT.Reference “Device.MQTT.Client.1”
Device.LocalAgent.Controller.1.MTP.1.MQTT.Topic “/controller-path”

This maps to the following CDRouter agent and controller configuration testvars:

testvar uspAgentID                        proto::agent-id
testvar uspAgentPath                      /agent-path
testvar uspControllerID                   proto::controller-id
testvar uspControllerMTP                  mqttv3
testvar uspControllerPort                 auto
testvar uspControllerPath                 /controller-path
testvar uspControllerUsername             qacafe
testvar uspControllerPassword             qacafe123
testvar uspControllerDomain               controller.cdroutertest.com
testvar uspControllerMTPEncryption        no

OB-USP-Agent Configuration Example (WebSockets)

The following minimal OB-USP-Agent configuration uses unencrypted WebSockets as an MTP and is compatible with CDRouter’s default controller configuration:

OB-USP-Agent Parameter Value
Device.LocalAgent.EndpointID “proto::agent-id”
Device.LocalAgent.MTP.1.Enable “true”
Device.LocalAgent.MTP.1.Protocol “WebSocket”
Device.LocalAgent.Controller.1.Enable “true”
Device.LocalAgent.Controller.1.EndpointID “proto::controller-id”
Device.LocalAgent.Controller.1.MTP.1.Enable “true”
Device.LocalAgent.Controller.1.MTP.1.Protocol “WebSocket”
Device.LocalAgent.Controller.1.MTP.1.WebSocket.Host “controller.cdroutertest.com”
Device.LocalAgent.Controller.1.MTP.1.WebSocket.Port “80”
Device.LocalAgent.Controller.1.MTP.1.WebSocket.Path “/controller-path”
Device.LocalAgent.Controller.1.MTP.1.WebSocket.EnableEncryption “false”

This maps to the following CDRouter agent and controller configuration testvars:

testvar uspAgentID                        proto::agent-id
testvar uspAgentPath                      /agent-path
testvar uspControllerID                   proto::controller-id
testvar uspControllerMTP                  websocket
testvar uspControllerPort                 auto
testvar uspControllerPath                 /controller-path
testvar uspControllerUsername             qacafe
testvar uspControllerPassword             qacafe123
testvar uspControllerDomain               controller.cdroutertest.com
testvar uspControllerMTPEncryption        no

USP Scenario Testing

USP Scenarios are lightweight custom test scripts you can develop to execute commands from CDRouter’s USP Controller to validate parameters, reboot the DUT and perform other actions.

Details can be found in the USP Scenario Scripting Guide in our Knowledge Base.

USP Profile Testing

Much like CWMP Profile testing, CDRouter is able to perform USP profile tests to ensure a USP agent has correctly implemented all the required parameters of a data model’s profile.

The following profile test modules are available:

  • USP_Device2_profile.tcl
  • USP_FAPService2_profile.tcl
  • USP_StorageService1_profile.tcl
  • USP_STBService1_profile.tcl
  • USP_VoiceService1_profile.tcl

For each profile, CDRouter defines several generic tests that verify the consistency of the profile:

  1. Verify all required parameter names are returned using Get
  2. Verify all required parameters exist using GetSupportedDM
  3. Verify the read and write status of each parameter using GetSupportedDM
  4. Verify all writable parameters can be set using Set
  5. Verify the creation and deletion of all creatable objects using Add and Delete

Configuring Which Profiles are Tested

CDRouter has the ability to skip unsupported profiles automatically after specifying what the agent supports.

The agent’s supported data model can be configuring using the testvar uspSupportedDataModel, which supports several different options. Setting this testvar to the keyword all indicates that the agent supports every profile from all officially defined USP data models:

testvar uspSupportedDataModel "all"

A list of top level data models can be specified to indicate that all the profiles in only those data models are supported:

testvar uspSupportedDataModel {Device:2.13 VoiceService:2.0}

A DeviceSummary string as defined in Section 3.7 of TR-106 can also be specified:

testvar uspSupportedDataModel {Device:2.13[](Baseline:2),VoiceService:2.0[1](Baseline:1)}

Or:

testvar uspSupportedDataModel {Device:2.15[](IPInterface:1,WiFiRadio:1)}

When specifying a supported data model and its version, the profile version tested will be the most recent version which was included in the minor version specified. This means that values like this:

testvar uspSupportedDataModel {Device:2.1[](Baseline:3)}

will skip the baseline profile because the 3rd version of the Baseline profile did not exist in version 2.1 of the Device data model.

USP Parameter Data Validation

By default, CDRouter will perform data validation on USP profile parameters. To disable data validation, set uspDataValidation to no. When data validation is enabled, CDRouter will verify that the value of every parameter is syntactically correct according to syntax information contained within the Broadband Forum’s official XML data model definitions. If a parameter fails data validation, CDRouter will print a message detailing why the parameter’s value is incorrect and the test will fail.

Custom USP Profiles

CDRouter supports user defined profiles. To test a user defined profile, set the testvar uspProfileName to the name of the profile you would like to test and uspProfilePath to the unix file path to the XML file containing profile.

Note: in CWMP profile testing, there is support for specifying profiles in XML format as well as QA Cafe’s proprietary format. The proprietary format is not available as a file format for USP profile testing.

To then test this custom profile, after setting the testvars, run the usp_datamodels.tcl test module.

Example config:

testvar_group usp_profile_1 {
    testvar uspProfileName     STOMPHeartbeats:1
    testvar uspProfilePath     /usr/cdrouter-data/custom/my-usp-profile.xml
}

It is also possible to set the uspProfilePath testvar to “auto”. When set to this value, CDRouter’s controller will issue a GetSupportedDM message to the agent in start targeting the root object. The response from the agent will be treated as one large profile which will be used in the usp_datamodels.tcl test module. Additionally when uspProfilePath is set to “auto” CDRouter will save the extracted data model to the result’s log directory. The data model will be saved as “usp-extracted-data-model.xml” in the BBF data model XML format, which can then be used as a custom data model in subsequent test runs. It’s important to remember that the extracted data model is entirely based on the reported data model from the agent. The extracted data model should be used as a starting point and should not be interpreted as the complete data model the agent was expected to implement.

Excluding USP Parameters

In some cases, you may wish to exclude a parameter from the USP profile check because it is not supported by the device under test. CDRouter allows you do to this by configuring a list of parameters to skip in the uspSkipParameters testvar. A list of parameters can be specified by enclosing the list members between “{“ and “}”. The list of parameters can be either full instances or generic instances that use “{i}” for each instance index. Note that each individual parameter within the list must be specified using a full instance or partial path, or a fully generic instance using “{i}” for each index. Parameters cannot be specified using a mix of generic and full instances. Here is an example:

testvar uspSkipParameters {
  Device.DeviceInfo.ModelName
  Device.USP.InterfaceNumberOfEntries
}

If you are skipping an entire object path and all parameters contained below it, you only need to specify the top object path. All top object paths (partial paths) must end with a ‘.’ character. For example, if the device under test does not support the Stats object from a PTM link, you could skip the object by configuring the following uspSkipParameters testvar:

testvar uspSkipParameters {
  Device.PTM.Link.{i}.Stats.
}

Modifying USP Parameters

All USP profiles supported by CDRouter and their corresponding objects and parameters are defined in the /usr/cdrouter/tests/usp-profiles directory. The type, requirement, or syntax of any of these pre-defined objects and parameters can be modified using the uspModifyParameters testvar. Like the uspSkipParameters testvar uspModifyParameters supports a list.

When modifying parameters we recommend copying the original parameter definition from the /usr/cdrouter/tests/usp-profiles directory and then making the required modifications using uspModifyParameters. Here is an example that modifies the enumeration syntax of the Device.DSL.BondingGroup.{i}.Status parameter to support the additional keywords of auto and foo:

testvar uspModifyParameters {
  string R Device.DSL.BondingGroup.{i}.Status {enumeration {Up Down NotPresent LowerLayerDown}}
}

Likewise, here is an example that changes the requirement of the Device.Time.NTPServer1 parameter from write, W, to read- only, R:

testvar uspModifyParameters {
  string R Device.Time.NTPServer1 {size {maxLength 64}}
}

Note that the syntax argument is optional when modifying parameters. If omitted CDRouter will only overwrite the type and requirement for the specified parameter. As a result the above example can be reduced to this:

testvar uspModifyParameters {
  string R Device.Time.NTPServer1
}

USP Software Module Management (SMM) Testing

CDRouter’s USP expansion contains a module of test cases to help validate Software Module Management functionality for USP agent implementations.

Typically, in these test cases, CDRouter simulates a USP Controller that instructs the agent to download a software module from a location (URL) that exists on a server separate from the CDRouter system.

In shared test setups, where there is a shared termination device (CMTS, OLT, etc.) that is inbetween the DUT and CDRouter’s WAN connection, the DUT can directly connect to that URL on the separate server.

In closed-loop test setups, where the DUT’s WAN is directly connected to CDRouter’s WAN port, the DUT can only reach the URL on a separate server by routing traffic through CDRouter. These test setups require the use of CDRouter’s Internet Connection Service (ICS) feature.

Alternatively, if the test setup does not have a separate server to store software modules, CDRouter’s built-in HTTP server may be able to be used to serve the required software modules.

The following section provides an example of how to do this -

Setup General Purpose HTTP Server

Example configuration of HTTP Server -

SECTION "General Purpose HTTP Server" {
    testvar httpServerIp     3.3.3.16
    testvar httpServerPort   80
    testvar httpServerRoot   /usr/cdrouter-data/custom
}

Configure USP Software Module Management Section

After successfully configuring the general purpose HTTP server, configure the “USP Agent Software Module Management” section of the CDRouter configuration file to make use of the HTTP Server.

Note that the values for the URL testvars specify the IP of the general purpose HTTP server.

SECTION "USP Agent Software Module Management" {

    testvar uspSoftwareModuelURL            http://3.3.3.16/<module filename>
    testvar uspSoftwareModuleUpdateURL      http://3.3.3.16/<other module filename>
    testvar uspSoftwareModuleUsername       anonymous
    #testvar uspSoftwareModulePassword      qacafe123 
    testvar uspSoftwareModuleUUID           01234567-890a-bcde-f012-3456789abcde
    #testvar uspSoftwareModuleEEName	    default
    #testvar uspSoftwareModuleEEClassName   default
    testvar uspSoftwareModuleTimeout        120
}

The module files will need to be copied over to the CDRouter system and placed into the directory specified by the httpServerRoot.

Broadband Forum USP Agent Certification

CDRouter is the official test tool of the Broadband Forum’s USP Agent Certification program. CDRouter includes a full implementation of TP-469 Conformance Test Plan for USP Agents in the usp_conformance test module.

More information on how to use the CDRouter USP Expansion to perform self-testing certification can be found here.

Troubleshooting

Controller is not sending messages

Agent IP configuration

Before the controller will send any USP messages, it will ARP for the agent’s IP. If the agent doesn’t have the correct IP address it will never respond to the ARPs being sent. If the agent is configured to use a static IP ensure it matches what is in the config file. If the agent is configured to get an IP via DHCP, ensure the agent IP address in the config file is either set to “auto” or the DHCP pool is configured to allow for one address and that the appropriate agent IP testvar is set to that address.

If STOMP is being used as the MTP and the agent is getting an IP address but the controller is not sending any messages, ensure the agent is correctly connecting to the STOMP server and subscribing to the correct destination. The controller will not attempt to send any messages until the agent has correctly connected and subscribed to the right destination on the STOMP server. If the agent appears to be attempting to connect to the STOMP server ensure the uspControllerUsername and uspControllerPassword are correctly set to the credentials the agent provides.

Agent not responding to USP messages

If the controller is sending USP messages to the agent’s IP address and not getting a response ensure the following are correctly configured:

  • The MTP the controller is using matches what the agent is expected to use.
  • The port used to accept connections on the agent is correctly configured in the config file.
  • uspControllerID matches what the agent expects the controller ID to be
  • uspAgentID matched the endpoint ID configured on the agent
  • uspControllerUseSessionContext is set to “yes” if the agent is expected to use a session context

Agent’s responses are ignored by the controller

If the controller is ignoring the responses the agent is sending ensure:

  • uspControllerID matches the to_id in the agent’s responses
  • uspAgentID matches the from_id in the agent’s responses
  • The message_id of the message sent to the agent matches the message_id in the agent’s response

Other Issues

TLS

If USP payload security is configured it’s possible there is an issue with the certificate exchange or with the fact that there might be more than one TLS record in a single message.

Controller is dropping messages

If the controller cannot properly decode messages it receives from the agent it will issue a warning in the log and drop it. The most likely reason for a message to not decode properly is an issue with the protobuf encoding.