CDRouter Support

CDRouter TR-069 User Guide

user-guide version 10.3

Introduction

CDRouter TR-069 Add-on for CDRouter

CDRouter TR-069 adds TR-069 testing and functionality to our industry leading CPE and router test platform, CDRouter. CDRouter TR-069 has been designed from the ground up to work with implementations based on the Broadband Forum’s CPE WAN Management Protocol described by Technical Report 69 (TR-069). CDRouter TR-069 currently supports TR-069 Amendments 1 and 2.

With the CDRouter TR-069 add-on module enabled, CDRouter is enhanced to provide a built-in ACS during all testing sessions. The CDRouter TR-069 add-on module also contains several new test modules focusing on three major areas of TR-069 testing:

  1. Fully automated Broadband Forum OD-128 testing:

    Test Module Description
    od128.tcl Interoperability Test Plan for TR-069 Plugfests
  2. Real-world testing that addresses functionality not currently covered in OD-128:

    Test Module Description
    tr69.tcl Additional TR-069 testing of the CPE device (beyond OD-128)
    tr111_part1.tcl TR-111 Part 1 tests for device-gateway association
    tr111_part2.tcl TR-111 Part 2 tests for connection request via NAT gateway
  3. CWMP data model profile verification testing for all Broadband Forum defined root data models and user-defined data models. For a complete list of all Broadband Forum data model specifications supported by CDRouter, please see this Knowledge Base article.

    Test Module Description
    InternetGatewayDevice1_profiles.tcl TR-098 CWMP Profile testing for IGD devices
    Device1_profiles.tcl TR-106 CWMP Profile testing for Device data model
    Device2_profiles.tcl TR-181i2 TR-181 issue 2 CWMP Profile testing for Device:2
    cwmp_scenarios.tcl General CWMP configuration testing for user defined CWMP scenarios
    cwmp_profiles.tcl General CWMP Profile testing for user defined CWMP Profiles

By offering automated versions of the OD-128 test cases in addition to the growing battery of real-world and data model profile tests, CDRouter TR-069 can help you test your TR-069 device quickly and thoroughly.

CDRouter TR-069 Extended Data Model Add-on (TR69-EDM)

The Extended Data Model add-on for CDRouter TR-069 (TR69-EDM) provides support for testing the profiles defined in the Broadband Forum’s service data models. The TR69-EDM add-on is only available on systems that already have CDRouter and the CDRouter TR-069 add-on installed.

TR69-EDM provides support for the profiles defined in Broadband Forum TR-104, TR-135, TR-140, and TR-196. The following test modules are included with the TR69-EDM add-on:

Test Module Description
VoiceService1_profiles.tcl TR-104 CWMP Profile testing for VoIP devices
VoiceService2_profiles.tcl TR-104 Issue 2 CWMP Profile testing for VoIP devices
STBService1_profiles.tcl TR-135 CWMP Profile testing for STB devices
StorageService1_profiles.tcl TR-140 CWMP Profile testing for Storage Service Enabled Devices
FAPService1_profiles.tcl TR-196 CWMP Profile testing for Femto Access Point Service
FAPService2_profiles.tcl TR-196 Issue 2 CWMP Profile testing for Femto Access Point Service

Test Methodology

Initial Setup

CDRouter TR-069 provides a built-in ACS for CPEs to communicate with. Prior to running any TR-069 tests, the CPE must be told how to connect to the ACS.

Information on how to configure CDRouter TR-069’s ACS can be found in the Configuration section below.

See the Configuring the CPE for TR-069 section to ensure the CPE’s ACS URL and username/password settings match the ACS configuration.

Start-Up

During the start-up procedure, CDRouter TR-069 expects to receive an Inform RPC from the device being tested. This Inform should be triggered by rebooting the device, or by configuring the CPE Connection Request URL in the CDRouter configuration file. Once CDRouter has received the initial Inform, the testing procedure will begin.

Running

Once testing has begun, CDRouter TR-069 will use the built-in ACS to communicate with the CPE. No additional user interaction is needed!

To run only the TR-069 related test modules from the command-line:

$ cdrouter-cli –addon tr69 –trace –pt

For additional execution options, see the CDRouter User’s Guide.

Requirements and License

In order to run the CDRouter TR-069 or TR69-EDM add-ons, your license file must be updated to enable the CDRouter TR-069 functionality. Note that the TR69-EDM add-on requires the CDRouter TR-069. Please follow the instructions from support@qacafe.com on updating your license file to enable CDRouter TR-069 and TR69-EDM (if applicable).

CDRouter will report the status of all available add-ons during the installation process and during startup. To verify that the CDRouter TR-069 or TR69-EDM add- ons are enabled on your system, execute the command cdrouter-cli -info as root and look for the lines “TR69 is enabled” and “TR69-EDM is enabled”. If these lines are present, the CDRouter TR-069 and TR69-EDM add-ons are enabled and ready to use.

$ cdrouter-cli -info

Starting cdrouter-cli Fri Mar 25 13:28:42 EDT 2016
Copyright (c) 2001-2016 by QA Cafe
Version 10.0 build 1 (21410 trunk), built 2016-03-24 17:36:47 by nightly@cdr-forge6.lan (x86_64)
Loaded OS distro \S Kernel \r on an \m
Loaded OS version Linux-3.10.0-327.10.1.el7.x86_64 x86_64
Loaded Tcl version 8.6.4
Loaded buddy version 10.0.1
(builder@kbuilder.dev.centos.org) (gcc version 4.8.3 20140911 (Red Hat 4.8.3-9) (GCC) )
Trying to load modules from '.'
Trying to load modules from '/usr/share/doc/cdrouter'
Start command: /usr/cdrouter/bin/cdrouter-cli -info
Test Suite cdrouter 10.0.1
The system ID is 2df9e2a1f8c359183cf0191a20f2cc5a
Using license installed at: /etc/cdrouter.lic
Registered to: qacafe
Maintenance, Support and Upgrades until: 2016-05-11
Licensed to run: 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 disabled
CPU is Intel(R) Core(TM) i5-4308U CPU @ 2.80GHz, bogomips 5599.98
Loaded TclXML version 3.1 (libxml2), TclDOM 3.0, xmldefs 3.1
Trying to load modules from '/usr/cdrouter/vendor/IOL/BBF.069/Tests'
BBF.069 version 1.2.075-11 (19093)

Configuration

Enabling the ACS

In order to run CDRouter TR-069 tests, the ACS server must be enabled in your CDRouter configuration file. This is done by setting supportsCWMP to “yes”.

testvar supportsCWMP yes

The ACS address is specified by setting the acsIp testvar to either an IPv4 or IPv6 address.

testvar acsIp 6.0.0.1
    -or-
testvar acsIp 6000::1

The ACS may run with both IPv4 and IPv6 at the same time by setting the acsDualStackIp testvar to a secondary address. When both testvars are set, each address must be in a different address family.

testvar acsIp 6000::1
testvar acsDualStackIp 6.0.0.1

The CPE configuration must be updated to reach the ACS at one of these addresses or a fully-qualified domain name that resolves to one of these addresses.

CDRouter’s DNS server will automatically resolve the special domain name acs.qacafe.com to one of the ACS addresses. Other domain names may be added to CDRouter using the dnsHostname/dnsIp testvar pairs

By default, when CDRouter’s ACS is enabled it runs over HTTP on TCP Port 80 with the following settings:

testvar acsTransport            http
testvar acsPort                 80
testvar acsAuth                 digest
testvar acsDigestQopAuth        yes
testvar acsInterface            wan
testvar acsWaitForInform        120
testvar acsSkipInitialInform    no
testvar cwmpProtocolVersion     1.0
testvar acsDeviceDiscovery      no
testvar acsDefaultUser          qacafe
testvar acsDefaultPassword      qacafe123
testvar acsCpeDefaultUser       qacafe
testvar acsCpeDefaultPassword   qacafe123

The acsTransport testvar specifies the type of connection (HTTP or HTTPS) the ACS will use for CWMP sessions with the CPE. The acsPort is the TCP port the ACS will listen on.

All connections from the CPE must be authenticated using the acsDefaultUser and acsDefaultPassword testvars below. The CPE must be configured with the same username and password in order to successfully authenticate with the ACS.

testvar acsDefaultUser          qacafe
testvar acsDefaultPassword      qacafe123

The acsCpeDefaultUser and acsCpeDefaultPassword testvars are used by the ACS when initiating Connection Requests with the DUT. Some CPE devices do not allow these credentials to be set by the user, and instead rely on the ACS itself to configure them. See the acsDeviceDiscovery testvar for more details.

testvar acsCpeDefaultUser       qacafe
testvar acsCpeDefaultPassword   qacafe123

See the Configuring the CPE for TR-069 section to ensure the CPE configuration matches CDRouter’s ACS settings.

Configuring ACS to use HTTPS with SSL/TLS certificates

The ACS can be configured to run over HTTPS using SSL or TLS certificates by setting acsTransport to https. The following settings provide a typical setup using well-known TCP port 443, but any port may be specified.

testvar acsTransport            https
testvar acsPort                 443
testvar acsSslVersion           sslv23
testvar acsCertPath             /usr/share/doc/cdrouter/acs.qacafe.com.pem
testvar acsCaCertPath           /usr/share/doc/cdrouter/acs.qacafe.com-ca.pem

By default acsSslVersion is set to sslv23 which is recommended to allow the ACS to automatically adjust to the version supported by the CPE. Other values are supported in order to force the ACS to operate at a specific version. See the acsSslVersion testvar definition below for more details.

The acsCertPath testvar specifies the location of the certificate that the ACS will send to the CPE when establishing a TLS/SSL connection. The file must contain both of the following:

  • The ACS certificate in PEM format (plain text)
  • The private key, which must be unencrypted

The acsCaCertPath testvar is used if the ACS certificate requires one or more additional certificates from an Intermediate Certificate Authority (CA) in order for the CPE to valid it. This testvar specifies a file containing all intermediate CA certificates, which the ACS will send to the CPE along with the ACS certificate.

Using CDRouter’s Default ACS Certificate

CDRouter provides several different certificate/key pairs for various types of TLS/SSL connections in the /usr/share/doc/cdrouter directory.

In CDRouter’s default configuration, the acs.qacafe.com.pem and acs.qacafe .com-ca.pem files are used.

  • The acs.qacafe.com.pem file contains the default ACS certificate, which has been signed by Verisign and should be accepted by most CPE devices.

  • The acs.qacafe.com-ca.pem file contains the intermediate certificate from Verisign that is needed to validate the ACS server certificate.

When validating the ACS certificate, the CPE must have the Verisign Root CA certificate pre-installed in its local store of trusted certificates. Otherwise, it will reject the ACS certificate and the TLS/SSL connection will not be established.

If this happens, the Verisign Root CA certificate must somehow be imported into the CPE’s trusted certificate store. The procedure for doing this will depend on the type of CPE device and may or may not be supported. You can find more help on this in the following article in the QA Cafe Knowledge Base: What root certificate must be installed to verify acs.qacafe.com.pem?

Using QA Cafe Self-Signed Certificates

The ACS can be configured to use a custom certificate for TLS/SSL connections with the CPE.

The /usr/share/doc/cdrouter directory contains a set of “self-signed” certificate files created by QA Cafe, which can be used by the ACS as an alternative to the default Verisign certificates.

testvar acsCertPath            /usr/share/doc/cdrouter/acs.qacafe.com-self.pem
testvar acsCaCertPath          /usr/share/doc/cdrouter/acs.qacafe.com-ca-self.pem
  • The acs.qacafe.com-self.pem file contains the ACS certificate signed by a local “qacafe.com” Certificate Authority. This certificate is sent by the ACS during TLS/SSL connection setup.

  • The acs.qacafe.com-ca-self.pem file contains the CA certificate that is needed to validate the ACS certificate. This certificate must be imported into the CPE.

Using Custom/Proprietary Certificates

You may also have the ACS use your own custom certificate for SSL/TLS connections, simply by copying the certificate file to your CDRouter system, and update the acsCertPath testvar to reference it. If the CPE will require one or more certificates from Intermediate CA’s, these should be copied into a single file on the CDRouter system as well and update the acsCaCertPath.

testvar acsCertPath            /home/qacafe/MyPrivateACSCert.pem
testvar acsCaCertPath          /home/qacafe/MyPrivateCA-Certs.pem

Remember that the ACS certificate file must contain both the certificate data in PEM format and the unencrypted private key associated with it, as described in the previous sections.

ACS testvar settings

The ACS has several configuration options to control its behavior and various aspects of the test setup.

Basic ACS Configuration

The following list describes all basic ACS configuration testvars.

Advanced ACS Configuration

There are also several advanced configurations options for the ACS which are listed here.

ACS SSL Configuration

The following configuration options can be used to enable SSL on the ACS.

TR-069 Profile Configuration

The following configuration options are used when testing TR-069 profiles.

Custom CWMP Profiles

Custom TR-069 profiles can also be defined and tested with CDRouter TR-069. The following configuration options are used to define custom TR-069 profiles. Each custom profile must be defined as a separate testvar_group in the configuration file.

Additional/Optional TR-069 Configuration

The following list of configuration options can be used to fine tune the test setup and provide additional information that will be used in certain test cases.

TR-111 Part 2 Configuration

If the CPE supports TR-111 Part 2, the following configuration options will enable this capability within CDRouter.

Configuring the CPE for TR-069

The CPE’s TR-069 settings must match the ACS configuration, as described in the previous sections.

Prior to running any TR-069 tests, the CPE must be told how to connect to the ACS. This may be done by statically configuring the CPE with an “ACS URL” that specifies the ACS IP address or its fully-qualified domain name, acs.qacafe.com, as well as the port number and transport method (HTTP or HTTPS) used by the ACS. These are specified by the acsIp, acsPort and acsTransport testvars in your CDRouter config file.

The CPE must also provide the correct username and password in order to successfully authenticate with the ACS. These are specified by the acsDefaultUser and acsDefaultPassword testvars.

Example CPE settings for CDRouter’s default ACS configuration might look like this:

ACS URL: http://acs.qacafe.com:80
Username: qacafe
Password: qacafe123

ACS Device Discovery via DHCP

The CPE may also learn the ACS URL dynamically via DHCP or DHCPv6. CDRouter supports ACS discovery as outlined in TR-069 Amendment 5 Section 3.1.

This feature is enabled by default when TR-069 is enabled. When CDRouter’s DHCP server receives a client request containing the Vendor Class option 60 or the V-I Vendor Class option 124 with the value ‘dslforum.org’, the DHCP server will include DHCP Vendor Specific Information option 43 or 125, respectively, in the response indicating the location of the ACS server. This feature is also supported using DHCPv6 Vendor Class option 16 and DHCPv6 Vendor Specific Information option 17.

The DHCP server will automatically construct the ACS URL to send to the CPE based on the values of the acsTransport, acsIp and acsPort testvars.

Example:

testvar acsTransport  https
testvar acsIp         6.5.4.3
testvar acsPort       7547

URL of ACS => https://6.5.4.3:7547/

You may also set the ACS URL to a specific value. This may be required when using DNS names or HTTPS transport for your ACS connections.

Examples:

testvar acsDiscoveryUrl https://acs.qacafe.com:7547/
testvar acsDiscoveryUrl http://6.0.0.1:80

Note that when specifying URLs containing literal IPv6 addresses, you must enclose the IPv6 address in square brackets, as specified in RFC 3986. If such URLs are used within a testvar, the square brackets must be escaped appropriately using one of the methods below:

testvar acsDiscoveryUrl http://\[6000::1\]:80/
testvar acsDiscoveryUrl {http:/[6000::1]:80/}

ACS Discovery may be turned off by setting the testvar acsDiscoveryUrl to none. For example:

testvar acsDiscoveryUrl none

Example Configurations

CDRouter TR-069 Basic Configuration

In the example below, CDRouter is configured with the CPE Connection Request URL so that it can initiate new TR-069 sessions from the start. The CPE Connection Request username and password are statically configured on the CPE and the CPE is also configured with the username and password of the ACS.

testvar supportsCWMP                yes
testvar acsIp                       6.0.0.1
testvar acsPort                     80
testvar acsTransport                http
testvar acsAuth                     digest
testvar acsDigestQopAuth            yes
testvar acsCpeConnReqURL            http://192.168.200.2:80/XML/000FCC-23570008.xml
testvar acsDeviceDiscovery          no
testvar acsDefaultUser              000FCC-23570008
testvar acsDefaultPassword          acs123
testvar acsCpeDefaultUser           cpeurl
testvar acsCpeDefaultPassword       cpe123
testvar tr69InitiateConnection      yes
testvar tr69DownloadImage           /home/user/fw_image_ver2.bin

CDRouter TR-069 Configuration with Device Discovery

In the example below, CDRouter is configured to use device discovery by configuring testvar acsDeviceDiscovery to yes. When the first Inform is received from the device, CDRouter will attempt to configure the CPE Connection Request URL username and password, and will disable the sending of Periodic Informs to the ACS. The CPE is also configured with the username and password of the ACS.

testvar supportsCWMP                yes
testvar acsIp                       6.0.0.1
testvar acsPort                     80
testvar acsTransport                http
testvar acsAuth                     digest
testvar acsDigestQopAuth            yes
testvar acsWaitForInform            120
testvar acsDeviceDiscovery          yes
testvar acsDefaultUser              000FCC-23570008
testvar acsDefaultPassword          acs123
testvar acsCpeDefaultUser           cpeurl
testvar acsCpeDefaultPassword       cpe123
testvar tr69InitiateConnection      yes
testvar tr69DownloadImage           /home/user/fw_image_ver2.bin

Firmware Upgrade

CDRouter TR-069 contains support for downloading new images to the CPE as part of the OD-128 firmware download tests. To enable firmware download tests, the path to the desired firmware image must be configured with the testvar tr69DownloadImage. The full path to the file should be used. By default, CDRouter TR-069 will wait up to 5 minutes for a download to complete. This is generally sufficient for a 1 – 3 megabyte image file. For larger image files, the download timeout can be adjusted by configuring the testvar tr69DownloadTimeout.

Log Messages

CDRouter TR-069 protocol messages can be filtered out using the cdrouter-cli -show and cdrouter-cli -hide options from the command-line. The following protocols are specific to CDRouter TR-069:

  • ACS: All ACS protocol messages

Examples:

To show only ACS log messages

$ cdrouter-cli –show ACS

To exclude all ACS related messages

$ cdrouter –hide ACS

TR-111 Parts 1 and 2

CDRouter TR-069 supports TR-111 Parts 1 and 2. By default, support for TR-111 Part 1 and 2 is disabled.

NOTE: TR-111 Parts 1 and 2 have been incorporated into the TR-069 specification as Annexes F and G, respectively, starting with TR-069 Amendment 1. This functionality (as defined in Annexes F and G of TR-069 Amendment 1+) is referenced as TR-111 Part 1 and TR-111 Part 2 within CDRouter TR-069.

TR-111 Part 1 (TR-069 Annex F: Device-Gateway Association)

Support for TR-111 Part 1 in an IGD device under test can be enabled by configuring the testvar supportsTr111Part1 to yes. This testvar defaults to no. When TR-111 Part 1 is enabled, CDRouter can run the TR-111 Part 1 tests from the od128 module. There is also an additional tr111_part1.tcl module with additional coverage of TR-111 Part 1. During any TR-111 Part 1 testing, CDRouter will create LAN side devices to associate with the IGD device.

NOTE: TR-111 Part 1 testing requires at least 1 Ethernet LAN interface.

TR-111 Part 2 (TR-069 Annex G: Connection Request via NAT Gateway)

Support for TR-111 Part 2 in an IGD device or LAN side TR-069 device under test can be enabled by configuring the testvar supportsTr111Part2 to yes. This testvar defaults to no. When TR-111 Part 2 is enabled, CDRouter will attempt to read the NATDetected and UDPConnectionRequestAddress parameters when it first learns about a TR-069 device. CDRouter will also enable STUN on the device and set up active notification of these parameters. If NAT is detected and the UDPConnectionRequestAddress is provided, CDRouter will switch to UDP style connection request attempts instead of TCP based requests.

By default, the ACS STUN server does not require authentication on STUN Binding Requests. When the ACS configures the STUN settings on the CPE, it automatically generates a STUN username and STUN password for the CPE. The ACS server will only require authenticated STUN Binding Requests when the testvar STUNAuth is set to yes. The ACS will configure the maximum and minmum STUN keep alive intervals to 60 seconds by default. These can be changed using the testvars STUNMaximumKeepAlivePeriod and STUNMinimumKeepAlivePeriod.

LAN Side TR-069 Devices

Starting with CDRouter TR-069 release 3.8, LAN side TR-069 aware devices can be tested using the od128.tcl test module. When testing a LAN side TR-069 device, the device must be connected to an IGD device that provides a WAN connection and NAT. Since the LAN side device is now behind NAT, the device must either support TR-111 Part 2 or a port mapping must be created on the IGD. When working with port mappings on the IGD, CDRouter must either be configured with a URL that works with the port mapping on the IGD, or CDRouter can create a port mapping dynamically via TR-069, if the IGD supports TR-069.

CDRouter TR-069 currently supports testing TR-104 VoIP and TR-135 STB devices using the od128.tcl test module.

LAN side TR-069 devices can be configured using testvar groups. Each LAN side TR-069 device must be named tr069_device2 through tr069_device8. The testvar group contains configuration items unique to each TR-069 LAN side device. Only a small number of testvars are required for each LAN device.

When LAN side TR-069 devices are used, the Serial Number and OUI for all TR-069 devices involved in the test setup must be configured. To tell CDRouter to run all test cases against a LAN side TR-069 device instead of the normal IGD device, the global testvar acsTargetDevice must be set to the testvar group name of the desired LAN side device. Otherwise, CDRouter will default to running all TR-069 tests against the IGD defined in the main CDRouter configuration.

Configuration Options

The following table describes each entry available to LAN side TR-069 devices:

Example 1: LAN Side TR-104 Device with TR-111 Part 2

In the example below, CDRouter is assumed to already have a working configuration for an IGD device with TR-069 enabled. A new device with TR-104 and TR-111 support has been added to the LAN side of the IGD. The following configuration will allow CDRouter to run all TR-069 related tests against the LAN side TR-104 device.

testvar acsTargetDevice             tr069_device2
testvar supportsTr111Part2          yes

testvar_group tr069_device2 {
  testvar acsDefaultUser          myata
  testvar acsDefaultPassword      qacafe123
  testvar tr69DeviceOui           001122
  testvar tr69DeviceSn            123
  testvar tr69DownloadImage       /home/files/myata.bin
  testvar tr69DeviceType          VoIP
}

Example 2. LAN Side TR-135 Device with Static Port Mapping on IGD

In the example below, CDRouter is assumed to already have a working configuration for an IGD device with TR-069 enabled. A new device with TR-135 support has been added to the LAN side of the IGD. The device does not support TR-111 and a port mapping has been created on the IGD device with a public IP address of 192.168.200.2. The LAN side device must define a URL that can be used through the IGD for the normal TCP based connection request mechanism. The following configuration will allow CDRouter to run all TR-069 related tests against the LAN side TR-135 device.

testvar acsTargetDevice             tr069_device3
testvar supportsTr111Part2          no

testvar_group tr069_device3 {
  testvar acsDefaultUser          mySTB
  testvar acsDefaultPassword      qacafe123
  testvar acsCpeConnReqURLMapped  http://192.168.200.2:1234/mySTB_request.htm
  testvar tr69DeviceOui           001144
  testvar tr69DeviceSn            124
  testvar tr69DownloadImage       /home/files/mySTB.bin
  testvar tr69DeviceType          STB
}

Example 3. LAN Side TR-135 Device with Dynamic Port Mapping on IGD

In the example below, CDRouter is assumed to already have a working configuration for an IGD device with TR-069 enabled. A new device with TR-135 support has been added to the LAN side of the IGD. The device does not support TR-111. CDRouter will automatically configure a port mapping on the IGD device with a public IP address of 192.168.200.2. The following configuration will allow CDRouter to run all TR-069 related tests against the LAN side TR-135 device.

testvar acsTargetDevice             tr069_device4
testvar supportsTr111Part2          no

testvar_group tr069_device4 {
  testvar acsDefaultUser          mySTB
  testvar acsDefaultPassword      qacafe123
  testvar acsCreatePortMapOnIGD   yes
  testvar acsPortMapPublicPort    5000
  testvar tr69DeviceOui           001144
  testvar tr69DeviceSn            124
  testvar tr69DownloadImage       /home/files/mySTB.bin
  testvar tr69DeviceType          STB
}

Example 4. LAN Side TR-135 Device with Manual Port Mapping on non-TR-069 Enabled IGD

Starting with CDRouter 7.0, the acsCpeConnReqURLMapped testvar can be configured for the primary TR-069 device. In previous releases this testvar was only supported for secondary TR-069 devices. This is useful for testing TR-069 LAN side devices that are connected to non-TR-069 enabled gateways. In these scenarios the TR-069 LAN side device is the primary TR-069 device in CDRouter’s config file. As a result, there are no additional testvar_groups defined since the DUT is the only TR-069 enabled device in the setup.

The acsCpeConnReqURLMapped testvar defines the mapped location of the DUT’s TR-069 connection request URL. The DUT’s connection request URL must be reachable using a manually created port mapping on the gateway that forwards requests between the mapped connection request URL on the WAN to the DUT’s actual connection request on the LAN.

For example, if the DUT’s connection request URL is http://192.168.1.5:5678/cwmp, and the gateway’s public IP is 5.5.5.5, the mapped URL will look like this, assuming port 5678 on the gateway is mapped to port 5678 on LAN host 192.168.1.5:

testvar acsCpeConnReqURLMapped  http://5.5.5.5:5678/cwmp

Note that when the acsCpeConnReqURLMapped testvar is used for the primary TR-069 device, the DUT’s OUI and SN must also be configured:

testvar tr69DeviceOui           e09153
testvar tr69DeviceSn            2673964

XMPP Connection Requests

The Broadband Forum has defined an XMPP based connection request mechanism in Annex K of TR-069 Amendment 5. The motivation for defining this new connection request mechanism is provided in section K.1:

K.1 Introduction

The CPE WAN Management Protocol can be used to remotely manage CPE that are
connected via a LAN through a Gateway. When an ACS manages a Device connected
via a NAT Gateway or firewall-enabled Gateway (where the Device cannot be
contacted  directly by the ACS), the CPE WAN Management Protocol can still be
used for  management of the Device, but with the limitation that the Connection
Request  mechanism defined in Section 3.2.2 that allows the ACS to initiate a
Session might not be  usable.

The procedures defined in this Annex allow an ACS to initiate a Session with any
Device, including Devices that cannot be contacted directly by the ACS. This
provides the equivalent functionality of the Connection Request defined in
Section 3.2.2, but makes use of a different mechanism, based on Extensible
Messaging and Presence Protocol (XMPP), to accommodate this scenario.

As it relates to Devices that cannot be contacted directly by the ACS, the
mechanism defined in this Annex does not assume that the Gateway, through which
the Device is connected, supports the CPE WAN Management Protocol. This
mechanism requires support only in the Device and the associated ACS.

Support for XMPP connection requests can be enabled by setting the testvar acsSupportsXmppConnReq to yes. When enabled, CDRouter will create an XMPP server on the same stack as the ACS. As a result, the XMPP server shares the same domain name as the ACS, which is acs.qacafe.com by default.

If acsDeviceDiscovery is set to yes CDRouter will query the DUT’s XMPP.Connection table during start to determine if an instance exists. If an instance does exist CDRouter will update it to match the running XMPP server configuration. If an instance does not exist CDRouter will issue an AddObject RPC to create an instance which will then be configured with appropriate XMPP server information.

If acsDeviceDiscovery is set to no, the DUT must be pre- configured with the correct XMPP server information. The domain name must be acs.qacafe.com and the username, password, and resource must all match the values in CDRouter’s configuration file, as determined by the testvars provided below.

Configuration Options

The following testvars define CDRouter’s XMPP server configuration:

XMPP Connection Requests Using TLS

TLS can be enabled for all XMPP connection requests by setting the testvar acsXmppConnReqUseTls to a value of yes. When TLS is enabled CDRouter will use the ACS server certificate, as defined by the testvars acsCertPath an acsCaCertPath, for the XMPP server. The DUT must have the appropriate intermediate and root CAs installed to validate the XMPP server certificate. Please see the following knowledge base article for more information:

CWMP Profile Testing

TR-106 defines the structure and use of CWMP profiles to allow the ACS to quickly detect the data model parameters supported by a device. The DeviceSummary parameter is used to provide a list of all CWMP profiles supported by a device. If a device claims support for a profile, it MUST support all required parameters included in that profile. This allows the ACS to have some commonality among devices.

CDRouter TR-069 contains profile definitions for all CWMP profiles defined in the following data models:

  • InternetGatewayDevice:1 (version 1.14)
  • Device:1 (version 1.14)
  • Device:2 (version 2.11)

The TR69-EDM add-on adds support supplemental CWMP profiles defined in:

  • STBService:1 (version 1.4)
  • VoiceService:1 (version 1.1)
  • VoiceService:2 (version 2.0)
  • StorageService:1 (version 1.2)
  • FAPService:1 (version 1.1)
  • FAPService:2 (version 2.1)

It is also possible for users to define their own CWMP profiles. For each profile, CDRouter defines several generic tests that verify the consistency of the profile:

  1. Verify all required parameter names are returned using GetParameterNames
  2. Verify parameter name instances can be walked using GetParameterNames
  3. Verify all parameter names and values are returned using GetParameterValues
  4. Verify the read and write status of each parameter
  5. Verify all writable parameters can be set using SetParameterValues
  6. Verify the creation and deletion of all creatable objects using AddObject and DeleteObject
  7. Verify UserCWMPProfile using GetParameterValues for GetParameterNames full paths

CWMP Profile Test Modules

There are a number of test modules specifically for CWMP profile testing. All of the modules can be selected together or individual modules and test cases can be selected. The following test modules are included with the CDRouter TR-069 add- on:

  • InternetGatewayDevice1_profiles.tcl
  • Device1_profiles.tcl
  • Device2_profiles.tcl
  • cwmp_profiles.tcl
  • cwmp_scenarios.tcl

The following additional test modules are available with the TR69-EDM add-on:

  • STBService1_profiles.tcl
  • VoiceService1_profiles.tcl
  • VoiceService2_profiles.tcl
  • StorageService1_profiles.tcl
  • FAPService1_profiles.tcl
  • FAPService2_profiles.tcl

Getting Started with CWMP Profile Testing

If the device under test supports the DeviceSummary parameter, CDRouter will automatically select the list of CWMP profiles to test. When CDRouter receives the first TR-069 Inform from the device, CDRouter’s ACS will parse the DeviceSummary string and automatically deselect any CWMP profiles that are not supported. If the DeviceSummary parameter is not supported, CDRouter will not automatically exclude any test cases.

It is possible to configure a “fake” DeviceSummary string for devices that do not support the DeviceSummary parameter or to override the real DeviceSummary from the device. Two new testvars have been introduced to control this behavior. A fake DeviceSummary string can be configured using the tr69FakeDeviceSummary testvar. The contents of this testvar should be included within “{“ and “}”. The tr69FakeDeviceSummary testvar also accepts the special keyword “all” to designate all available CWMP profiles. This can be used to select all available CWMP profiles regardless of the DeviceSummary reported by the device under test.

Examples:

testvar tr69FakeDeviceSummary {InternetGatewayDevice:1.5[](Baseline:2)}
testvar tr69FakeDeviceSummary {InternetGatewayDevice:1.5[](Baseline:2,EthernetLAN:1), STBService:1.0[1](DiagPerfMon:1,BasicPerfMon:1,DigitalOutput:2)}
testvar tr69FakeDeviceSummary all

By default, CDRouter uses the real DeviceSummary from a device and will only use the fake DeviceSummary if the tr69FakeDeviceSummary testvar is configured. Note that the DeviceSummary parameter has been depreciated by the Broadband Forum. As a result, it may be necessary to manually configure CDRouter to test Device:2 data models using the tr69FakeDeviceSummary testvar.

Profile Version Numbers

Each CWMP profile reported in the DeviceSummary string contains a version number. When testing a CWMP profile, CDRouter will try to match the profile version number against the CDRouter library of CWMP profile definitions. By default, CDRouter uses “strict” matching and will skip a profile unless an exact match is made. For example, if the device is reporting Baseline:3 and CDRouter only knows about Baseline:2, CDRouter will not attempt to test the Baseline profile. CDRouter can also be configured for “best” case matching which allows CDRouter to use the closest version available. With “best” matching in the scenario above, CDRouter would proceed to verify the Baseline profile using Baseline:2. NOTE: While most CWMP profiles are backwards compatible, there are some unfortunate exceptions. Some care must be exercised when using the “best” option.

Examples:

Use strict CWMP profile matching (the default behavior)

testvar tr69ProfileMatch strict

Use best case CWMP profile matching

testvar tr69ProfileMatch best

Excluding CWMP Parameters

In some cases, you may wish to exclude a parameter from the CWMP 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 cwmpSkipParameters 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 cwmpSkipParameters {
  InternetGatewayDevice.DeviceInfo.ModelName
  InternetGatewayDevice.LANDevice.{i}.USBLANConfigurationNumberOfEntries
}

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 LANConfigSecurity object from the TR-098 Baseline profile, you could skip the object by configuring the following cwmpSkipParameters testvar:

testvar cwmpSkipParameters {
  InternetGatewayDevice.LANConfigSecurity.
}

Modifying CWMP Parameters

All CWMP profiles supported by CDRouter and their corresponding objects and parameters are defined in the /usr/share/doc/cdrouter/cwmp-profiles directory. The type, requirement, or syntax of any of these pre-defined objects and parameters can be modified using the cwmpModifyParameters testvar. Like the cwmpSkipParameters testvar cwmpModifyParameters supports a list.

When modifying parameters we recommend copying the original parameter definition from the /usr/share/doc/cdrouter/cwmp-profiles directory and then making the required modifications using cwmpModifyParameters. Here is an example that modifies the enumeration syntax of the InternetGatewayDevice.LANDevice.{i}.LANEthernetInterfaceConfig.{i}.MaxBitRate parameter to support the additional keywords of auto and foo:

testvar cwmpModifyParameters {
  string R InternetGatewayDevice.LANDevice.{i}.LANEthernetInterfaceConfig.{i}.MaxBitRate {enumeration {foo 10 100 1000 10000 Auto auto}}
}

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

testvar cwmpModifyParameters {
  string R InternetGatewayDevice.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 cwmpModifyParameters {
  string R InternetGatewayDevice.Time.NTPServer1
}

When modifying parameters that are part of a service object such as VoiceService or STBService, the root object should be specified as ‘root’, since it can be either InternetGatewayDevice or Device. Here is an example:

testvar cwmpModifyParameters {
  string R root.Services.VoiceService.{i}.VoiceProfile.{i}.SignalingProtocol
  unsignedInt R root.Services.VoiceService.{i}.VoiceProfile.{i}.MaxSessions
}

The Creating Your Own Custom Profiles section contains additional information regarding the format of parameters and data validation.

CWMP Parameter Data Validation

By default, CDRouter will perform data validation on CWMP profile parameters. To disable data validation, set cwmpDataValidation 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. See the Data Validation section for more information on what properties of a parameter are checked when validation is enabled.

Creating Your Own Custom CWMP Profiles

New CWMP profiles may be added by creating a file that defines all of the included parameters. Each line of the file should contain one parameter.

The new file containing the CWMP profile can be included in the CDRouter setup by defining a testvar_group using the cwmp_profile naming convention. You can create up to 128 unique profiles using testvar_group names cwmp_proflile1 through cwmp_profile128. For example:

testvar_group cwmp_profile1 {
  testvar cwmpProfileName      myVendorParameters
  testvar cwmpProfileObject    InternetGatewayDevice
  testvar cwmpProfilePath      /home/dev/myVendorParameters.cwmp
}

The file /home/dev/myVendorParameters.cwmp should contain a CWMP parameter on each line. The format for each parameter is <type> <requirement> <path> [<syntax>], where <syntax> may be omitted. For example:

boolean W InternetGatewayDevice.X_Vendor.featureA.Enabled
string  W InternetGatewayDevice.X_Vendor.featureA.foo

The type field comes directly from the CWMP parameter definition. The following requirement options are available:

P   The parameter is a required object
PC  The parameter is a required object and creatable
PO  The parameter is an optional object
POC The parameter is an optional object and creatable
R   The parameter is read-only
W   The parameter is writable and readable
WO  The parameter is writable but can not be read (password, keys, etc)

Note: When defining custom profiles that include a creatable object (either PC or POC, as defined above) with multiple instances in its path, all parent instances for that object must also be included in the profile. For example, to properly define the following vendor defined creatable object:

object POC InternetGatewayDevice.X_Custom.{i}.Interface.{i}.Address.{i}.

The custom profile must include the following:

object P   InternetGatewayDevice.X_Custom.{i}.
object P   InternetGatewayDevice.X_Custom.{i}.Interface.{i}.
object POC InternetGatewayDevice.X_Custom.{i}.Interface.{i}.Address.{i}.

Data Validation

The <syntax> field must be a Tcl dictionary value containing syntax information used to validate the parameter’s value when cwmpDataValidation is yes. The following table describes the keys that may be present and how they are used during validation:

Key Value
enumeration A Tcl list of all possible values for the parameter to hold
pattern A Tcl list of patterns, the parameter must match at least one
size minLength The minimum length in characters for the parameter
size maxLength The maximum length in characters for the parameter
range minInclusive The minimum value the parameter may hold
range maxInclusive The maximum value the parameter may hold
list is Must be true or false indicating whether the parameter is a list
list size minLength The minimum number of elements in the list
list size maxLength The maximum number of elements in the list

Note that if list is is true, all other keys become specific to an element in the list as opposed to the full parameter value. The snippet below outlines the general structure of the syntax dictionary:

{
  enumeration { STR1 STR2 STR3... }
  pattern     { PAT1 PAT2 PAT3... }
  size        { minLength MIN maxLength MAX }
  range       { minInclusive MIN maxInclusive MAX }
  list { 
    is   BOOLEAN 
    size { minLength MIN maxLength MAX }
  }
}

For example, to define a parameter as being a list of strings with between two and four elements and with possible values A, B, or C which must each be exactly one character long:

string W InternetGatewayDevice.MyCustom.StringParam {
    list { is true size { minLength 2 maxLength 4 } }
    enumeration { A B C }
    size { minLength 1 maxLength 1 }
}

or to define an integer parameter that must have values within the range of ten to twenty-five:

int W InternetGatewayDevice.MyCustom.IntParam {
    range { minInclusive 10 maxInclusive 25 }
}

Using the Pktsrc/CWMP API

It is also possible to create new profiles using the PktSrc/CWMP API. Please see the API reference for an overview of the Tcl procedures available.

Profile Testing Issues

When starting CWMP profile testing, it is common to find unsupported or misspelled parameter names. The SetParameterValues testing can also detect issues with the data model that may need to be resolved. The following issues may occur:

  • The initial value of the parameter is not a valid value. CDRouter will attempt to read the initial value and write back this same value. If the initial value is not valid, the SetParameterValues test will fail.

  • The initial value of a parameter may be empty until some additional operation occurs. In some cases, it may be more useful to run the CWMP profile tests after running other TR-069 test cases. For example, some devices may not populate the IPPing parameters with valid values until the IPPing diagnostics have been run at least once.

Any parameters causing the testing to fail can either be skipped or modified.

CWMP Scenario Testing

Starting in CDRouter 8.0, users may create CWMP scenarios to easily set and verify CWMP parameters on their device. CWMP scenarios are small text based scripts that define interactions between the CDRouter ACS and the CPE device under test.

To get started with CWMP scenarios, create a CWMP scenario file on the local disk of your CDRouter system. Configure the testvar cwmpScenarioPath using the name of this file. For example:

testvar cwmpScenarioPath /home/cdrouter/files/configuration_test.cwmp

Multiple scenarios can be placed in this file, each with a unique name.

New Test Modules

CWMP scenario script files are executed by the following new test module included with the CDRouter TR-069 add-on for verifying CWMP scenarios:

  • cwmp_scenarios.tcl

Simple Example

Here is a simple CWMP scenario for reading a value with a GetParameterValues RPC. Note, each scenario must be given a unique name when it is defined.

CWMP my_name_goes_here {

  GetParameterValues {

    # get all the Time parameters
    parameter InternetGatewayDevice.Time.
  }

}

The CWMP scenario defined above consists of a command. Some commands correspond directly to a CWMP RPC method. In some cases, the command may contain additional information on how to verify the result. You can verify whether returned parameters match specific values by using the “verify” command. Here is another example:

CWMP my_name_goes_here {

  GetParameterValues {

    # get all the Time parameters
    parameter InternetGatewayDevice.Time.

    # verify the NTPServer1 matches the configure ntpServerName1 in the configuration file
    verify InternetGatewayDevice.Time.NTPServer1 5.6.7.8
  }
}

Scenario Commands

CWMP Scenarios contain commands that map directly to TR-069 RPCs. For example, to set specific parameters, use the SetParametervalues command. To read the values of parameters, use the GetParameterValues command. The AddObject and DeleteObject commands are used to create and delete instances.

GetParameterValues Command

The GetParameterValues command must specify a parameter using the parameter argument. This parameter may be a full or partial path.

 parameter <parameter path>

“verify” argument

The verify argument is used to verify any value returned by the GetParameterValues. The verify argument is optional.

verify <parameter path> <value>

By default, verify will check to ensure that the value of the specified parameter exactly matches <value>. Additional keywords are available to modify this behavior. These keywords and their arguments must be specified in square brackets (’[]‘).

  • [ any ]

    The any keyword ensures the parameter exists without regard for its value.
    This is useful for parameters such as packet counters which may be constantly changing. Empty (null) values are also acceptable.

    verify InternetGatewayDevice.Time.NTPServer1 [ any ]
    
  • [ accept … ]

    The verify argument can also be configured to accept a list of values using the syntax [ accept value1 value2 ... ] . The value returned by the GetParameterValues call will then be compared to the list of acceptable values.

    verify InternetGatewayDevice.Time.NTPServer1 [ accept 5.5.5.5 5.5.5.6 ]
    

    To verify a boolean value that may return either true or 1:

    verify InternetGatewayDevice.ManagementServer.PeriodicInformEnable [ accept true 1 ]
    
  • [ regexp … ]

    The verify argument can compare the value returned by the GetParameterValues call against a TCL regular expression if the exact value is not known. Any valid TCL regular expression string may be used and should be enclosed in curly braces (‘{}’).

    verify InternetGatewayDevice.Time.NTPServer1 [ regexp {[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+} ]
    

“block” argument

One or more block arguments can be specified to perform custom validation on any parameter returned by the GetParameterValues call. The block argument is followed by a section of TCL code which can be designed to iterate over each parameter returned by the DUT and validate them individually as needed.

The special params TCL array variable contains all of the parameters returned by the GetParameterValues call as key,value pairs. The params array also contains a “count” index whose value is the number of parameters returned.

Validation code within the block can call the buddy::PASS or buddy::FAIL methods to report results into the test log file.

block {

    #- Make sure we did not get 0 parameters
    puts "Starting my own validation"

    set count $params(count)
    buddy::logInfo "I found $count parameters"
    if { "$count" == 0 } {
      buddy::FAIL "I was expecting 0 parameters"
    } else {
      buddy::PASS "Okay I did not find 0 parameter values"
    }

    #- Verify Device.DNS.Client.Server.{i}. Table
    set count [ llength [ array names params "Device.DNS.Client.Server.{i}.Status" ] ]
    puts "Received $count entries in Device.DNS.Client.Server.{i}. table."
    if { $count == $params(Device.DNS.Client.ServerNumberOfEntries) } {
        buddy::PASS "ServerNumberOfEntries parameter matches actual number of parameters received."
    } else {
        buddy::FAIL "ServerNumberOfEntries parameter does not match actual number of parameters received."
    }

    foreach i [array names params "Device.DNS.Client.Server.*.Status"] {
        if { $params($i) != "Enabled" } {
            buddy::FAIL "$params($i) is not Enabled."
        } else {
            buddy::PASS "$params($i) is Enabled."
        }
    }
}

SetParameterValues Command

The SetParameterValues command must specify a parameter using the parameter argument along with its value and optionally its type.

parameter <path to parameter> <value> <type>

The faultcode is used to specify an expected failure. The faultcode argument is optional.

faultcode <value> 

When the type field is included in a SetParameterValues scenario, CDRouter will include the type attribute in the outgoing XML:

<cwmp:SetParameterValues>
    <ParameterList SOAP-ENC:arrayType="cwmp:ParameterValueStruct[1]">
        <ParameterValueStruct>
            <Name>InternetGatewayDevice.ManagementServer.PeriodicInformEnable</Name>
            <Value xsi:type="xsd:boolean">1</Value>
        </ParameterValueStruct>
    </ParameterList>
    <ParameterKey>cdrouter</ParameterKey>
</cwmp:SetParameterValues>

When the type field is not included CDRouter will omit the type attribute in the outgoing XML:

<cwmp:SetParameterValues>
    <ParameterList SOAP-ENC:arrayType="cwmp:ParameterValueStruct[1]">
        <ParameterValueStruct>
            <Name>InternetGatewayDevice.ManagementServer.PeriodicInformEnable</Name>
            <Value>1</Value>
        </ParameterValueStruct>
    </ParameterList>
    <ParameterKey>cdrouter</ParameterKey>
</cwmp:SetParameterValues>

Inclusion of the type attribute is optional according to section 3.5 of TR-069 Amendment 5 for elements of a type other “anySimpleType”.

AddObject Command

Objects can be created using the AddObject command. The path argument is used to specify the path for the object. The instance argument is used to create an instance variable that may be referenced in other commands.

path <path to object> instance <name>

DeleteObject Command

Objects can be deleted using the DeleteObject command. The path argument is used to specify the path to the deleted object. Paths can reference instance values created in previous AddObject commands using %NAME%.

path <path to object>

Add and Delete Objects Example

CWMP port_map_example {

    # -- Create a Port Map
    AddObject {
        path InternetGatewayDevice.WANDevice.1.WANConnectionDevice.2.WANIPConnection.1.PortMapping.
        instance INSTANCE1
    }

    # -- Read all the default values
    GetParameterValues {
        parameter InternetGatewayDevice.WANDevice.1.WANConnectionDevice.2.WANIPConnection.1.PortMapping.%INSTANCE1%.
    }


    # -- Read again, but verify some of them
    GetParameterValues {
        parameter InternetGatewayDevice.WANDevice.1.WANConnectionDevice.2.WANIPConnection.1.PortMapping.%INSTANCE1%.
        verify InternetGatewayDevice.WANDevice.1.WANConnectionDevice.2.WANIPConnection.1.PortMapping.%INSTANCE1%.RemoteHost {}
        verify InternetGatewayDevice.WANDevice.1.WANConnectionDevice.2.WANIPConnection.1.PortMapping.%INSTANCE1%.ExternalPort {0}
    }


    # -- Set a parameter
    SetParameterValues {
        parameter InternetGatewayDevice.WANDevice.1.WANConnectionDevice.2.WANIPConnection.1.PortMapping.%INSTANCE1%.ExternalPort {BadValue}
        faultcode 9003
    }

    # -- Verify the Set
    GetParameterValues {
        parameter InternetGatewayDevice.WANDevice.1.WANConnectionDevice.2.WANIPConnection.1.PortMapping.%INSTANCE1%.ExternalPort
        verify InternetGatewayDevice.WANDevice.1.WANConnectionDevice.2.WANIPConnection.1.PortMapping.%INSTANCE1%.ExternalPort {0}
    }

    # -- Delete the Port Map
    DeleteObject {
        path InternetGatewayDevice.WANDevice.1.WANConnectionDevice.2.WANIPConnection.1.PortMapping.%INSTANCE1%.
    }

}

GetParameterNames Command

The GetParameterNames command must specify a parameter using the parameter argument. This parameter may be a full or partial path.

parameter <parameter path>

The writable argument is used to verify the writable status of any parameter returned by the GetParameterNames. The writable argument is optional and multiple writable arguments may be specified.

writable <parameter path> <true|false>

The nextlevel argument controls the nextlevel flag passed to the GetParameterNames RPC. It accepts values of true, false, 1, or 0.

CWMP get_parameter_names_example {
    GetParameterNames {
        # get all the Time parameters
        parameter InternetGatewayDevice.Time.

        nextlevel false

        # verify the writeable status for a few names
        writable InternetGatewayDevice.Time.NTPServer1 true
        writable InternetGatewayDevice.Time.CurrentLocalTime false
        writable InternetGatewayDevice.Time.X_00247B_UpdateFrequency true
    }
}

The GetParameterNames command was added in CDRouter 8.1.

Reboot Command

The Reboot command sends the Reboot RPC to the CPE. Note: The CWMP session is not automatically closed after the Reboot RPC is sent. It is possible to perform other CWMP actions in the current session. If desired, the Close command may be sent after the Reboot RPC to end the current session and start the reboot process.

CWMP reboot_example {
   Reboot
   Close
}

The Reboot command was added in CDRouter 8.1.

Open Command

The Open command will initiate a new CWMP session if a current session does not exist. The Open command ends when an Inform is received from the device and the ACS returns an InformResponse. This command is used for CWMP scenarios that want more control over the CWMP session timing. Normally, a CWMP session is created automatically by any command that requires a CWMP session.

The Open command was added in CDRouter 8.1.

Close Command

The Close command will end any current CWMP session.

The Close command was added in CDRouter 8.1.

Delay Command

The Delay command can be used to insert an arbitrary delay, in milliseconds, anywhere within the scenario file. This can be useful for investigating timing issues between successive RPCs.

CWMP Delay_example {
   # Pause for 60 seconds
   Delay 60000
}

The Delay command was added in CDRouter 9.0.

Log command

The Log command can be used to insert a user defined message into the log file. This command can be used anywhere within a scenario file.

CWMP log_example {
   Log "Here is an SPV for parameter X"
}

The Log command was added in CDRouter 9.0.

Handling SOAP Faults

A CWMP scenario will create a FAIL result if a SetParameterValues command produces a SOAP fault. However, if a SOAP fault is expected, the expected faultcode may be configured. If a fault does not occur or the fault code does not match, the scenario will be set to a FAIL. This is very useful for negative testing.

SetParameterValues {
    parameter InternetGatewayDevice.WANDevice.1.does_not_exist
    faultcode 9003
}

Run a single scenario from the CWMP scenario file

Rather than running all CWMP scenarios defined in the scenario file all at once, it is possible to run the scenarios one at a time by setting the following testvar:

testvar cwmpScenarioSingleMode   yes

If set to yes, then only a single CWMP scenario will be run for each iteration of the cwmp_scenario_1 test. If the CDRouter test package is defined such that the cwmp_scenario_1 test is repeated or looped, then each iteration of the cwmp_scenario_1 test will run a subsequent scenario.

This feature was added in CDRouter 8.1.

Testing Exercises

Aside from running each test case in CDRouter TR-069, other testing scenarios can be created. The following test scenarios are recommended.

Vary the ACS Configuration

The ACS has several different configuration modes that impact its behavior. It is worthwhile to test the ACS using several different configurations. Besides the options for http or https and the different authentication schemes (basic, digest), chunked transfer mode can be enabled or disabled. See the listing of ACS testvars in the Configuration section.

Long Duration Testing

Besides running through the CDRouter TR-069 test cases one time, it is recommended to set up long duration runs of the od128.tcl and tr69.tcl modules using the cdrouter-cli -repeat command line option or a CDRouter web test package with the repeat option enabled. Frequent CWMP sessions will help verify that the TR-069 client will continue to operate over time.

XML Validation with Help from CDRouter

CDRouter TR-069 can help validate your device’s XML against the TR-069 CWMP Schema. This schema is provided by CDRouter in /usr/share/doc/cdrouter/cwmp.xsd. While CDRouter TR-069 is running, it can be configured to save all XML input and output for later validation.

The testvar tr69XMLCapturePath should point to an empty directory that will hold this XML. If this directory doesn’t exist, CDRouter will attempt to create it for you. While the test is running, every XML payload will be written to this directory in individual files prefixed by either ‘inbound’ or ‘outbound’. Inbound files will have been sent by the DUT where Outbound will be payloads sent by CDRouter TR-069.

Once the test run is complete, you can use a third-party tool to validate your XML against the provided schema.

QA Cafe recommends using xmllint for schema validation. xmllint is part of libxml2 and is installed by default on most Linux distributions. To run xmllint against the saved XML and compare it to the CWMP schema, use the following syntax:

$ xmllint --noout /path/to/xml/*.xml --schema /usr/share/doc/cdrouter/cwmp.xsd

For more information on using xmllint, please visit http://xmlsoft.org/xmllint.html

Check Folded HTTP Header Behavior

HTTP 1.1 allows long headers to be folded onto multiple lines using a continuation character. Most HTTP clients and servers do not use folded headers by default. However, QA Cafe has seen cases of clients using folded headers and it is possible that special applications could use them in CWMP headers.

The CDRouter ACS can be configured to use folded HTTP headers for digest authentication by configuring the testvar acsUseFoldedHeaders. You can quickly check that folded HTTP headers are supported for the CPE’s client and server side by enabling folded headers and then running through a set of TR-069 tests.

Please see the Configuration section for a description of how to set the testvar acsUseFoldedHeaders to enable folded HTTP headers. Folded HTTP headers are not used by default. However, they will be accepted if the CPE sends them.

Possible Problems

No Initial Inform Received from the CPE

If you configure the testvar acsWaitForInform, CDRouter will wait up to this interval in order to receive the first Inform from the CPE. If the Inform is not received, CDRouter will fail the startup phase and end the test session. There are a couple of things to check if the Inform is not being received during this interval.

  • NTP – Some devices will hold off sending the initial Inform while they try to synchronize the system clock using NTP. You can enable the built-in CDRouter NTP server to speed up this process.

  • Short wait interval – If you are using a small value for acsWaitForInform, you may need to increase this value.

  • CPE configuration – Verify that the CPE is configured with the correct IP or domain name of the ACS server. By default, CDRouter will populate the name acs.qacafe.com in all of the CDRouter DNS servers. This domain name maps to the testvar acsIp.

CPE Periodic Informs vs ACS Connection Requests

In CDRouter’s default configuration the acsDeviceDiscovery and tr69InitiateConnection testvars are both set to ‘yes’ which allows CDRouter to quickly progress through testing by disabling Periodic Informs on the CPE, and connecting to the CPE’s Connection Request URL to initiate a CWMP session whenever one is required. CDRouter TR-069 will enable Periodic Inform during specific test cases where this is required. This is the recommended configuration for most test environments.

However, CDRouter TR-069 is also compatible with CPE devices running with Periodic Informs enabled. To support this testing scenario, the following configuration changes must be made:

  • The acsDeviceDiscovery testvar must be set to ‘no’. This will prevent the ACS from disabling Periodic Informs on the CPE. (Note that this will also prevent the ACS from learning the CPE’s Connection Request URL from the initial Inform message, and the ACS will not configure the CPE’s Connection Username and Password password parameters.)

  • The tr69InitiateConnection testvar should also be set to ‘no’. This is not necessary but it will force the ACS to wait for the CPE’s next Periodic Inform message whenever a CWMP session is desired (rather than initiating a session using the Connection Request URL mechanism.)

  • In cases where acsDeviceDiscovery is disabled and tr69InitiateConnection is enabled, the connection request URL, username, and password must all be manually configured in your CDRouter configuration file since they will not be learned or configured automatically by CDRouter (these must match what is currently configured on the CPE).

Note that in this scenario, the periodic inform interval is important since it determines how often CDRouter will receive an inform from the CPE. In particular, if you are planning to run tests with tr69InitiateConnection disabled, a good value for the periodic inform interval on the CPE is around 60 seconds.

Also be aware that if acsDeviceDiscovery is set to ‘yes’, but tr69InitiateConnection is set to ‘no’, most tests will fail because CDRouter will not be able to initiate a CWMP session and the CPE will not automatically send an inform to CDRouter in a timely manner (ie. there will be no way for CWMP sessions to be reliably established in order to fulfill test case requirements).

Invalid Certificate Using HTTPS

When using HTTPS, the ACS configuration on the CPE may need to use the domain name of the ACS rather than the IP address in order to validate the ACS server certificate. The default server certificate for the ACS included with CDRouter is registered to the domain name acs.qacafe.com. CDRouter will automatically configure this DNS name in all DNS servers used in CDRouter.

The ACS URL configured on the CPE should use the domain name.

For example:

https://acs.qacafe.com

The CDRouter configuration file would be as follows.

testvar supportsCWMP yes
testvar acsIp        6.0.0.1
testvar acsPort      443
testvar acsTransport https

CDRouter will automatically map the testvar acsIp (6.0.0.1 in the example above) to the domain name acs.qacafe.com.

ACS is Unable to Request New CWMP Sessions

When the CDRouter ACS needs to communicate with the TR-069 CPE, it will attempt to initiate a new CWMP session using the CPE Connection Request URL. CDRouter will use the username and password from the acsDefaultCpeUser and acsDefaultCpePassword when trying to access this URL.

testvar acsCpeDefaultUser           cpeurl
testvar acsCpeDefaultPassword       cpe123

If the testvar acsDeviceDiscovery is set to yes, CDRouter can automatically set the CPE Connection Request URL username and password during the first CWMP session. This will ensure that the username and password match.

Tests Fail When the ACS is Not Configured to Initiate Connections

When setting up CDRouter TR-069 to run automatically, the testvar tr69InitiateConnection should be set to yes. When tr69InitiateConnection is set to yes, CDRouter will always initiate a connection using the CPE Connection Request URL. However, some PD-128 test cases specifically require the CPE to initiate a new connection by some local means. This may be a reboot or local action. By setting the testvar tr69InitiateConnection to no, you can execute these tests using the exact PD-128 test procedure. This may require some level of manual intervention to make sure the local action is executed when expected.

We recommend that you start out running with tr69InitiateConnection set to yes.

Working Around a Failing CWMP Client

In some cases, you may need to have the CDRouter ACS enabled and configured, but not wait for the initial Inform during the start phase. If the CWMP client does not respond consistently to the CPE Connection Request URL or experiences other failures, the start phase can be configured to skip the initial Inform by configuring the testvar acsSkipInitialInform to yes.

OD-128 Test Case Notes

The test cases in the OD-128 test module, od128.tcl, are based on the test case procedures outlined in the OD-128 Interoperability Test Plan for TR-069 Plugfests (Rev 04) from the Broadband Forum. In some cases, the test cases have been modified slightly to allow for a fully automated test run. In other cases, the parameter names have been changed to parameter names that should always be supported. For example, OD-128 does reference specific parameter names for wireless interfaces which may not always be available.

Rev 04 of OD-128 includes provisions for devices implementing the Device:2 data model defined in TR-181 Issue 2. The test parameters defined for Device:2 compliant IGD implementations in OD-128 Rev 04 are different than the parameters defined for InternetGatewayDevice:1.x compliant IGD implementations. As a result, CDRouter will automatically choose the correct parameters to use based on the setting of the testvar tr69DeviceType. If tr69DeviceType is set to “VoIP” or “STB”, CDRouter will test with the VoIP or STB specific parameters defined in OD-128 Rev 03 and earlier, respectively. If tr69DeviceType is set to “IGD”, CDRouter will attempt to autodetect which parameters to use based on the IGD’s advertised root object. If the IGD’s root object is InternetGatewayDevice CDRouter will use the older IGD parameters defined in OD-128 Rev 04. If the IGD’s root object is Device CDRouter will use the newer Device parameters in OD-128 Rev 04.

Note that a number of the parameters defined for InternetGatewayDevice:1.x implementations in OD-128 Rev 04 are invalid. As a result, CDRouter uses the parameters from earlier versions of OD-128 when testing InternetGatewayDevice:1.x implementations. In addition, specific notes about each implemented OD-128 test case are included below.

Contents

×

About CDRouter

CDRouter is made by QA Cafe, a technology company based in Portsmouth, NH.

Get in touch via our Contact page or by following us on your favorite service: