Search Results

CDRouter User Guide



Welcome to the Cable/DSL Router test suite CDRouter! CDRouter is a comprehensive test tool for Cable/DSL/SOHO/Edge and wireless routers and other similar IP devices. The test suite contains several types of tests including functional, conformance, negative, denial of service, and scaling.

The CDRouter test suite simulates a networking environment by creating LAN clients, providing an ISP connection to the device under test, and exercising different protocol and traffic flows. CDRouter can create IP hosts and services that appear to be operating out in the Internet. The test suite covers a wide range of protocols and applications that you would expect to find in a CPE router environment.

Test Organization

CDRouter is organized into several test modules of related functionality. Each test module contains several test cases. Tests can be executed using CDRouter’s web interface or through using the CDRouter Web API.

Before any tests are run, CDRouter attempts to set up a testing environment that is common to all tests. The initial setup phase includes starting a LAN client and establishing the WAN connection. Once the initial test setup is established, CDRouter moves on to executing specific test cases.

Test Coverage

This release of CDRouter tests the following areas of a Cable/DSL Router device:

  • Ethernet and IEEE 802.11a/b/g/n/ac/ax/be wireless interfaces
  • DHCP client (WAN side)
  • PPPoE client (WAN side)
  • PPPoA client (WAN side)
  • PPTP client (WAN side)
  • L2TP client (WAN side)
  • DHCP server (LAN side)
  • Bridge mode
  • 802.1q and 802.1p VLANs on the LAN interface
  • 802.1q, 802.1p, and 802.1ad VLANs on the WAN interface
  • ISP Renumbering Scenarios
  • NAT for TCP/UDP/ICMP/SCTP, Static NAT hosts
  • MSS Clamping for TCP sessions
  • WPA-PSK and WPA-RADIUS using supported EAP types
  • Firewall/Security
  • DMZ host configurations
  • IGMP proxy/multicast pass through
  • IPSEC, PPTP, and PPPoE pass through
  • DNS Proxy and Failover
  • mDNS
  • LLDP
  • LAN side MAC filtering
  • IP Forwarding
  • DHCP Client Scaling
  • Dynamic IP Routing (RIPv1/v2)
  • Virtual Services
  • URL Filtering
  • Port Triggers
  • Universal Plug and Play (UPnP)
  • Hotspot login via HTTP/HTTPS
  • DynDNS client verification
  • Xbox Live compatibility testing
  • Nmap integration (various Nmap scans are provided for information only)

Additional Expansions

Additional expansions that extend CDRouter’s testing capability into other specific protocol areas are also available. Expansions are currently available for:

Please refer to our website for more information.

Installing CDRouter

System Requirements

The CDRouter software must be run on the NTA1000 hardware platform.

Installation Procedure

Please see the complete installation instructions for CDRouter in our Knowledge Base.

Test Setup

CDRouter runs on a standard Linux PC using a combination of Ethernet and wireless network interfaces. Three network interfaces are typically required for a CDRouter test system:

  • One management interface
  • One WAN test interface (Ethernet or wireless)
  • One LAN test interface (Ethernet or wireless)

Finding Available Interfaces

You can find the available network interfaces on your Linux system using the /sbin/ifconfig command. From this list of interfaces, you can select two available network interfaces.

# -- example ifconfig output for eth1
eth1      Link encap:Ethernet  HWaddr 00:1b:21:01:20:1c
          UP BROADCAST  MTU:1500  Metric:1
          RX packets:1285 errors:0 dropped:0 overruns:0 frame:0
          TX packets:125 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:100 
          RX bytes:253489 (253.4 KB)  TX bytes:22574 (22.5 KB)

MAC Addresses

CDRouter generates MAC addresses for the LAN and WAN stacks as well as any additional on-link LAN or WAN hosts that are created during test cases. The addresses are created automatically, randomly, and uniquely, using the OUI specified by the cdrouterOui testvar, which defaults to QA Cafe’s IEEE OUI prefix of B0-75-C0.

There are configuration options to tune the creation of MAC addresses. These options differ depending on whether the interface represents the LAN or WAN.

LAN MAC Addresses

On the LAN, the NIC portion of the LAN MAC address may be specified using the lanMacId testvar to create a fixed, known MAC address on the respective LAN interface. The first client, or host, created on the interface will be assigned a MAC address created by concatenating the values of cdrouterOui and lanMacId . For example, the following values will yield a LAN client utilizing the MAC Address B0-75-C0-00-01-02.

testvar cdrouterOui b075c0
testvar lanMacId    000102

Additional clients after the primary LAN client always use a randomized MAC address. If the CDRouter Multiport expansion is available and additional ports are configured, the lanMacId may also be specified for the first client or host on these interfaces. Please see the CDRouter Multiport User Guide for more information.

Note that the resulting MAC addresses created by utilizing lanMacId must be unique. If MAC addresses are found to be duplicated in a configuration an error will be raised alerting the user of the duplicate prior to a package being run. Additionally, MAC addresses must be unique for all instances of CDRouter currently executing. If a MAC address is found to already be in use on a currently executing instance of CDRouter, an error will be raised during the startup procedure, alerting the user of a potential conflict with another CDRouter instance.

Additional testvars are available for configuring LAN MAC addresses for use in MAC Filtering test cases. These testvars are filteredMacId and unfilteredMacId , and are configured in the same way as lanMacId , however only apply for the mac-filter.tcl test module.

WAN MAC Addresses

On the WAN, depending on the connection type, it may be advantageous to avoid the constant creation of new random MAC addresses, in order to simulate a “stable” endpoint. The wanMacStable testvar may be configured to control the randomization of MAC addresses across package executions. When set to yes, CDRouter will generate WAN MAC addresses using an algorithm based on constant identifiers of the interface. Specifically, MAC addresses will be generated based on the System Hardware ID, the interface name, and the count of interfaces in use. This value will remain stable across test runs and reboots, and will be unique among CDRouter NTAs. This is especially useful in shared environments to uniquely and consistently identify multiple CDRouter NTAs. Note that the WAN MAC address cannot be modified or set in any way. Setting the value of the wanMacStable testvar to no will result in random MAC addresses using the QA Cafe OUI.

Note the testvars lanMac and wanMac are obsolete.

Connecting the Test Setup

CDRouter’s LAN and WAN test interfaces should be connected directly to the test setup. In addition, the test setup should be isolated and include only the DUT and in certain cases additional required network components such as a DSLAM, CMTS, or OLT.

CDRouter can connect to the LAN side of the DUT using wired Ethernet or 802.11 a/b/g/n/ac/ac/ax wireless LAN interfaces. Likewise, CDRouter can connect to the WAN side of the DUT using Ethernet or 802.11 a/b/g/n/ac/ax wireless. Some common CDRouter test setups are detailed below.

Wired Test Setup

This is the most common setup for CDRouter testing. CDRouter’s LAN test interface is connected directly to one of the LAN ports on DUT via Ethernet. Likewise, CDRouter’s WAN test port is connected directly to the DUT’s WAN test interface via Ethernet.

wired lan.png

Wireless Test Setup

Another common test setup involves wireless on the LAN. In this setup CDRouter is configured to connect to the DUT’s LAN via an 802.11 a/b/g/n/ac/ax wireless interface. CDRouter’s WAN test interface is still directly connected to the DUT via Ethernet.

wireless lan.png

On certain systems running CDRouter 9.2 and later, support for testing multiple wireless clients on a single interface may be possible. Please see the Wireless LAN Configuration section for more information.

multi station wireless lan.png

LTE WAN Test Setups

LTE routers or hotspots can be tested with CDRouter provided the necessary infrastructure is available. To test LTE routers, CDRouter will connect via Ethernet or wireless to the LAN side of the DUT, and then via Ethernet to the LTE network simulator.

lte setup.png

Other WAN Test Setups

In some cases additional network components may be required and present on the WAN between CDRouter and the DUT. This is the true when testing DOCSIS cable gateways and GPON ONTs which require a CMTS or OLT, respectively, to properly terminate the WAN connections on the DUT. In these setups CDRouter’s WAN test interface will connect to the CMTS or OLT via Ethernet.

other wan.png

For more information on testing DOCSIS cable gateways, please see this article.

For information on testing GPON ONTs, please see this article.

To test a travel router that employs wireless on the WAN, please see this article.

Configuration Overview

Before running tests with CDRouter, a configuration file must be created. The configuration file describes the test setup, general test or protocol behavior, and the configuration of the device under test (DUT). A configuration file can be generated from CDRouter’s web interface or by using the appropriate Web API resource

The configuration file contains several test variables that are specified using the testvar keyword. The format of each testvar is as follows:

testvar keyword value

If a testvar value contains whitespace characters, it must be enclosed in double quotes. For example:

testvar myname “This is my name”

The configuration file is organized into sections which contain all of the testvars associated with a particular CDRouter expansion, protocol, or aspect of the test setup. The CDRouter configuration file may also contain Tcl style comments by beginning a line with the ‘#’ character.

Existing configuration files can be upgraded from an older format to the current format directly from CDRouter’s web interface or by using the appropriate Wen API resource Both methods preserves all testvar values from the source configuration value and carries them forward to a new configuration file. The resulting configuration file will be identical to the source configuration file but will include any new testvars that have been added since the source configuration file was originally created. Please see this Knowledge Base article for more information on upgrading configs.

LAN Configuration

CDRouter automatically creates a DHCP LAN client using the default settings in the config file. Most LAN testing can be done with minimal changes to these default values. This section highlights the essential testvars to configure for most situations.

  • lanInterface - This testvar specifies which physical interface on the system CDRouter will use for LAN testing. This interface must be connected to the LAN side of the DUT. CDRouter supports both wired (Ethernet) and wireless (802.11 a/b/g/n/ac/ax) interfaces on the LAN, and the type of interface (Ethernet or wireless) will be automatically determined by this testvar. If an interface is not explicitly defined, the eth1 interface will be used by default.

    In certain scenarios it may be helpful to disable CDRouter’s LAN interface. This can be accomplished by setting lanInterface to the keyword none. This is most often used when testing endpoints that do not have any forwarding capability. It can also be helpful for simplifying the test setup when the primary focus is on WAN specific functionality such as TR-069 or Nmap.

  • lanMode - By default, CDRouter’s LAN client will obtain its IP address from the DUT through DHCP. This testvar can be set to static to have CDRouter automatically assign an address to the LAN client from the configured DHCP pool.

  • lanIp - This testvar should be set to the LAN IP address of the DUT. The default value is Note that CDRouter’s LAN client will automatically obtain its own IP address from the DUT through DHCP.

  • dhcpClientStart / dhcpClientEnd - These testvars define the pool of available client addresses on the LAN. They should be set to match the range of addresses offered by the DUT’s DHCP server. Note that these addresses must fall within the IP subnet defined by lanIp and lanMask . They should be set to match the DUT’s DHCP address pool

  • lanSecurity - CDRouter supports many different security modes on the LAN for both wired and wireless interfaces. The security type used by CDRouter is specified by the testvar lanSecurity . Some security modes require 802.1X authentication. CDRouter includes a built-in RADIUS server for 802.1X authentication on the LAN. Please see the LAN RADIUS Setup section for more information.

    For wired (Ethernet) interfaces, CDRouter supports security modes of NONE (no security) and 802.1X. For wireless interfaces, CDRouter supports security modes of NONE, WEP (static WEP only), and WPA (for WPA, WPA2, or WPA3 Personal or Enterprise).

  • Other LAN Configuration Options

     **LAN Interface**

Multiple LAN interfaces and clients

The CDRouter Multiport expansion allows additional LAN interfaces and clients to be configured. Please see the CDRouter Multiport User Guide for details and configuration examples.

Wireless LAN Configuration

  • lanInterface - To configure a wireless LAN interface in CDRouter set this testvar to one of the wireless interfaces on the system. CDRouter will work with most wireless adapter cards that are recognized and natively supported by the Linux kernel.

  • lanSecurity - This testvar is set to NONE by default, which indicates that the DUT allows wireless clients to connect without any authentication or security protocols. If security is required, this testvar should be set accordingly. For 64 or 128-bit WEP, set this testvar to a value of WEP. For WPA, WPA2, or WPA3 Personal or Enterprise, set this testvar to a value of WPA. Advanced configuration options for both WEP and WPA can be found in separate sections within the config file. Note that the values WPA-PSK and WPA-802.1X are no longer supported. They have been replaced by the more flexible WPA security settings in the wpaMode testvar.

  • lanSSID - This testvar should be set to the SSID of the DUT.

  • lanBSSID - If the DUT advertises the same SSID on both 2.4 GHz and 5.0 GHz frequency bands, CDRouter will automatically determine the best connection available. To override this behavior, set this testvar to the BSSID of desired frequency band on the DUT.

  • lanChannel - This testvar determines which channel or which frequency band CDRouter will scan while it searches for the DUT’s SSID (as specified by the testvar lanSSID ). By default this testvar is set to a value of auto which means that CDRouter will scan both the 2.4GHz and 5.0GHz bands. If multiple access points with the same SSID are discovered, CDRouter will connect to the one with the strongest signal by default. The lanBSSID testvar can be optional configured to force CDRouter to connect to a specific access point.

Please see the wireless LAN configuration article in our Knowledge Base for more details and configuration examples.

WPA Encryption Configuration Options

CDRouter supports the concept of ‘auto mode’ for certain WPA related testvars. When auto mode is enabled CDRouter will automatically select and use the strongest WPA security encryption settings advertised by the DUT.

The following testvars can be used to override this behavior and force CDRouter to connect with specific WPA security settings.

  • wpaMode - The WPA mode (WPA, WPA2, WPA3 Personal or Enterprise, etc.).
  • wpaKeyMgmt - The key management suite (PSK, SAE, SUITE-B, etc.).
  • wpaCipher - The pairwise cipher (CCMP, GCMP, TKIP, etc.).
  • wpaGroupCipher - The group cipher (CCMP, GCMP, TKIP, etc.).
  • wpaKey - The pre-shared key (required for WPA and WPA2-Personal modes only).
  • wpaPMF - Enables protected management frames (required for WPA3; optional for WPA2).
  • wpaSaePassword The SAE secret (required for WPA3-Personal modes only).

See this Knowledge Base article for a more detailed description of WPA auto mode.

WEP Encryption Configuration Options

CDRouter supports 64 or 128 bit static WEP keys and key indexes of 0 through 3. The following testvars can be used to configure the WEP key and key index. For 64 bit WEP keys a 10 character hex value must be specified; for 128 bit WEP keys a 26 character hex value must be specified.

Advanced Wireless Settings

The following testvars can be used to enable advanced optional wireless settings which are not typically required in most test setups.

Expected Beacon Information

The wifi test module contains tests that can be used to verify that is advertising the expected information in the 802.11 beacons it is broadcasting. The following testvars must be configured with the expected beacon contents.

Global Wireless Options

The following testvars can be used to enable global wireless settings and options on the system, including the country code and regulatory domain, the maximum number of wireless clients to create during testing, and whether or not 802.11 wireless capture functionality is enabled.

802.1X/RADIUS Configuration

CDRouter supports 802.1X with RADIUS authentication for both wired and wireless LAN connections. CDRouter’s RADIUS server will automatically respond to all Access-Request messages from the DUT and process the embedded EAP messages or PAP login requests. CDRouter’s RADIUS server supports all of the EAP types allowed by the testvar eapType .

RADIUS Server Setup

The RADIUS server user database is automatically configured based on the EAP identities defined in the LAN 802.1X Setup section of the configuration file. In order to use CDRouter’s RADIUS server, the DUT must be configured with the remoteHostIp address as the RADIUS server address on port 1812. In addition the DUT must be configured with the RADIUS secret specified by the radiusSecret testvar.

Additional RADIUS server attributes may also be defined. Each RADIUS attribute will be returned in any Access-Accept message sent to the DUT by CDRouter’s RADIUS server.

Note that CDRouter Multiport users can optionally move the RADIUS server from the WAN to an unused LAN interface. Please see this Knowledge Base article for more information on how to set up the RADIUS server on the LAN.

LAN 802.1X Setup

CDRouter supports 802.1X Port-Based Network Access Control for wired and wireless LAN interfaces. When running CDRouter with 802.1X enabled on the LAN, CDRouter will use its built-in supplicant to authenticate the wired or wireless port before running any test cases. CDRouter also contains several test modules with specific tests cases for EAPOL, RADIUS, and various EAP types.

To test with 802.1X authentication on the LAN, the DUT must be configured with CDRouter’s RADIUS server IP, port, and pre-shared key. Please see LAN RADIUS Setup section of the configuration file for information on configuring CDRouter’s built-in RADIUS server for 802.1X testing.

CDRouter supports a number of common EAP types for 802.1X testing on the LAN. The LAN EAP type is specified using the testvar eapType . For security modes that require 802.1X, certain EAP types may or may not be supported. Please see this Knowledge Base article for more information.

LAN EAP Credentials

For EAP-TLS, EAP-TTLS, and EAP-PEAP testing, you must configure CDRouter with valid X.509 certificates in PEM format. CDRouter includes 20 example PEM certificates in the /usr/cdrouter/tests directory that can be used as EAP credentials for 802.1X testing. Up to 16 sets of credentials can be configured per LAN interface.

Depending on the EAP type that is selected, only some of the EAP identity and certificate information needs to be configured. If a testvar entry is not required for the specific EAP Type, it will be ignored.

  • EAP-MD5 - For EAP-MD5, the eapIdentity and eapPassword entries must be configured for each EAP Identity in use.

  • EAP-TLS - For EAP-TLS, the eapIdentity entry must be configured. The eapPassword entry is not required. Additionally, the eapUserCertPath , eapUserCertPassword , and eapUserPrivateKey entries must be configured.

  • EAP-TTLS - For EAP-TTLS, the eapIdentity and eapPassword entries must be configured for each EAP Identity in use. The EAP-TTLS supplicant does not use a user certificate.

  • EAP-PEAP - For EAP-PEAP, the eapIdentity and eapPassword entries must be configured for each EAP Identity in use. The EAP-PEAP supplicant does not use a user certificate. By default, the PEAP supplicant will use EAPMSCHAPv2 as the inner EAP authentication method.

  • EAP-SIM - For EAP-SIM, the eapIdentity and eapPassword entries must be configured for each EAP Identity in use.

  • EAP-AKA - For EAP-AKA, the eapIdentity and eapPassword entries must be configured for each EAP Identity in use.

LAN 802.1X Configuration Options

WAN Configuration

CDRouter supports several main modes of operation depending on the WAN side configuration of the router. The testvar wanMode must be set to one of the following:

  • static - The router is configured with a static IP address on the WAN.
  • DHCP - The router is configured to run on a DHCP client on the WAN.
  • PPPoE - The router is configured to run a PPPoE client on the WAN.
  • PPPoA - The router is configured to run a PPPoA client on the WAN.
  • PPTP - The router is configured to run a PPTP client on the WAN.
  • L2TP - The router is configured to run a L2TP client on the WAN.
  • dslite - The router is configured to DS-Lite on the WAN.
  • none - The router does not support IPv4 on the WAN.

CDRouter 7.0 and newer releases support a new mode of operation for testing bridging devices. This mode is useful for verifying the basic forwarding functionality of wireless access points, smart switches, and bridged DSL CPE. Bridge mode is enabled by setting the testvar forwardingMode to bridge. By default bridge mode is disabled within CDRouter.

Note that CDRouter TR-069 can also be used in bridge mode to test the DUT’s TR-069 client, if present. Please see this Application Note for more information on bridge mode testing with CDRouter.

WAN Interface Configuration

DHCP Configuration

PPPoE Configuration

The PPPoE configuration on your Cable/DSL router must match CDRouter’s expected PPPoE configuration. There are several PPPoE and PPP related configuration parameters you can control. If your router uses a Connect-On-Demand type connection, you must configure the pppoeConnectOnDemand testvar to yes. When the Connect-On-Demand mode is in use, CDRouter will automatically send traffic from the LAN to the WAN when trying to establish a PPPoE session.

PPTP Configuration

If your router is running a PPTP client connection on the WAN interface, you can configure the wanMode to PPTP. The following PPTP testvars must be enabled in your configuration file.

When configuring your router for PPTP, the PPTP server address should be the same address as the wanIspIp address. The local WAN side address of the router should be the same as the wanIspAssignIp address.

L2TP Configuration

If your router is running a L2TP client connection on the WAN interface, you can configure the wanMode to PPTP. The following PPTP testvars must be enabled in your configuration file.

When configuring your router for L2TP, the L2TP server address should be the same address as the wanIspIp address. The local WAN side address of the router should be the same as the wanIspAssignIp address.

DS-Lite Configuration

Global PPP Configuration

WAN 802.1q VLAN

WAN 802.1ad VLAN

The testvars below enable 802.1ad VLAN stacking support. By default, CDRouter will use standard 802.1ad TPID tag values for the outer S-tag (0x88a8) and inner C-tag (0x8100) VLANs. Setting the wanOuterVlanQinQ testvar to “yes” will enable “QinQ” style tagging, causing CDRouter to use 0x8100 for both the outer and inner tag. Please see this Knowledge Base article for more details.

When enableVlanStacking is set to “yes”, CDRouter will ignore the wanVlanId and wanVlanPriority WAN 802.1q VLAN testvar settings and use the settings below instead.


CDRouter supports 802.1X authentication on the WAN starting with Release 6.2. For more information on testing with 802.1X port based authentication on the WAN, please see this article.

WAN 802.1X Setup

CDRouter supports 802.1X authentication on the WAN starting with Release 6.2. For more information on testing with 802.1X port based authentication on the WAN, please see this article.

WAN EAP Credentials

WAN 802.1X Configuration Options

DNS Setup

User Configurable DNS Entries

NTP Setup

The following testvars describe the configuration of CDRouter’s integrated NTP servers on the WAN.

Dynamic DNS Setup

CDRouter supports the Dynamic DNS protocol created by Dynamic Network Services, Inc.. The dyndns.tcl test module verifies that a client complies with the update syntax and specifications.

There are several configuration settings that control the DynDNS test setup.

WINS Server Configuration

WAN DHCP Relay Setup

IPSec Tunnel Configuration

CDRouter can terminate IPSEC ESP tunnel mode connections from the device under test. In order to test IPSEC tunnels on your device, you must configure the IPSEC tunnels on your device and create a corresponding IPSEC tunnel configuration in the CDRouter configuration file.

There are several testvar entries that must be created for each tunnel to define the remote gateway, destination network, inbound and outbound SPI numbers, security policy, and associated keys. NOTE: The base version of CDRouter only supports manual IPSEC keys. The CDRouter IKE expansion supports IKEv1 dynamic keys.

The picture below shows the logical topology that CDRouter uses for testing IPSEC tunnels. CDRouter emulates one end of each IPSEC tunnel. CDRouter is also able to emulate a remote network that is reachable through the tunnel and hosts on the remote network.


The following IPSEC tunnel configuration parameters must be configured in your CDRouter config file for each tunnel that will be tested. Each tunnel parameter ends with a number that identifies the tunnel. Each testvar shown in the IPSEC ESP Tunnel Configuration table should be appended with the actual number of the tunnel such as 1, 2, 3, etc. CDRouter’s default config template contains an example in the “IPsec Tunnel Configuration” section.

IPSEC Testing and NAT

The ipsec-esp.tcl test module does not require that the device apply NAT to outgoing packets before they enter the IPSEC tunnel. This test module can be used with devices that do apply NAT and devices that do not. Many of the test cases in the ipsec-esp.tcl test module will attempt to establish connections to the hosts specified in the ipsecTunnelHost entry. The device does not need to apply NAT to these packets in order for these tests to run.

If your device does support NAT over IPSEC tunnels, you can configure the remoteHostIp address inside of a configured IPSEC tunnel. When configured this way, many of the existing test modules for NAT, forwarding, applications, etc can be used to verify NAT over IPSEC. NOTE: If you configure the remoteHostIp address inside of an IPSEC tunnel, your device must apply NAT before packets from the LAN are forwarded in the IPSEC tunnel.

The following is an example configuration where the remoteHostIp is placed within an IPSEC tunnel. This allows many of the test cases that use the remoteHostIp address to verify NAT over IPSEC.

# IPSEC tunnel to
testvar ipsecTunnelEndpoint1
testvar ipsecTunnelRemoteNetwork1
testvar ipsecTunnelRemoteMask1
# (continued tunnel config for SPI, keys, etc...)

# emulated host on network 
testvar ipsecTunnelHost1 

# emulated remoteHost on network 
testvar remoteHostIp 

GRE Tunnel Configuration

The generic routing encapsulation protocol (GRE) is formally defined in RFC 2784. GRE provides a simple, general purpose mechanism for encapsulating one protocol within another protocol.

GRE is often used to create tunnels between two endpoints for the purpose of bridging two remote networks - typically between the LAN subnet and a remote subnet on the WAN. This can occur at either layer 3 (known as L3GRE) or at layer 2 (known as L2oGRE or L2GRE). PPTP also relies on a slightly different flavor of GRE, as defined in RFCs 1701, 1702, and 2683.

L2 and L3GRE tunnels are lightweight and have no inherent security or authentication. IP packets that are forwarded over the GRE tunnel are encapsulated/decapsulated by the tunnel endpoints, ie the CPE and a remote endpoint on the WAN. Encapsulation consists of adding an RFC 2784 style GRE header to all forwarded IP packets. At the remote end the GRE header is stripped by the tunnel endpoint and the packets are forwarded to the remote subnet.

The Protocol Type within the GRE header is different for L2 and L3GRE packets. For L2GRE the Protocol Type value is 0x6558 (Transparent Ethernet Bridging) whereas for L3GRE the Protocol Type value is 0x0800 (IP).

There is typically no NAT or firewall on L2 or L3GRE tunnels. As a result, CDRouter assumes that there is no NAT or firewall on any defined GRE tunnels.

Note that CDRouter currently supports only IPv4 GRE tunnel endpoints. Future versions of CDRouter may add support for IPv6 GRE tunnel endpoints. L2GRE tunnels can be used to transport both IPv4 and IPv6 traffic. L3GRE tunnels can only be used to transport IPv4 traffic.

L2GRE Config Example

CDRouter currently supports a single L2GRE tunnel per configuration file. The L2GRE tunnel creates a bridge between the LAN subnet and a secondary WAN interface. As a result, L2GRE support within CDRouter requires the Multiport expansion, and the LAN configuration must be consistent with the WAN interface configuration that it is associated with.

To configure L2GRE, set the testvar wanInterface to a value of l2gre for the secondary WAN interface wan2 that will be attached to the LAN subnet. In addition, the tunnel type (greType ) must be set to a value of L2 and the local subnet (greLocalNet / greLocalMask ) and remote GRE tunnel endpoint (greEndpoint ) must also be defined.

A simple example configuration for the L2GRE WAN, GRE tunnel, and LAN subnet is included below:

testvar dhcpClientStart            
testvar dhcpClientEnd              

testvar_group wan2 {
    testvar wanInterface                     l2gre
    testvar wanIspIp               

SECTION "GRE Tunnels" {

    # testvar greDFflag                        on

    testvar_group greTunnel1 {

        SECTION "Generic IPv4 GRE Tunnel Endpoints" {

            testvar greType                          L2
            testvar greEndpoint            
            testvar greLocalNet            
            testvar greLocalMask           

            SECTION "L2GRE Options" {

                testvar greWanGroup                      wan2


The l2gre test module has a number of basic tests that verify traffic forwarding over the tunnel in the upstream and downstream directions, fragmentation, etc.

L3GRE Config Example

Within CDRouter one or more L3GRE tunnels can be defined in the “IPv4 GRE Tunnels” portion of the config file.

For each L3GRE tunnel the tunnel type (greType ), local subnet (greLocalNet / greLocalMask ), remote GRE tunnel endpoint (greEndpoint ), remote GRE host (greHost ), and expected fragmentation behavior (greDFflag ) must be defined. The remote GRE host is used as an endpoint for the various tests included in the gre test module.

SECTION "GRE Tunnels" {

    # testvar greDFflag                        on

    testvar_group greTunnel1 {

        SECTION "Generic IPv4 GRE Tunnel Endpoints" {

            testvar greType                          IPv4
            testvar greEndpoint            
            testvar greLocalNet            
            testvar greLocalMask           

            SECTION "L3GRE Remote IPv4 Network" {

                testvar greHost            
                testvar greRemoteNet       
                testvar greRemoteMask      


The gre test module has a number of basic tests that verify traffic forwarding over the tunnel in the upstream and downstream directions with and without valid (and invalid) checksums, fragmentation, etc.

Wireless WAN Configuration

CDRouter 9.1 added support for 2.4 GHz WiFi Access Point (AP) mode on the WAN. Support for 5 GHz AP mode was later added in CDRouter 10.6.

AP mode makes it possible to test travel routers, WiFi range extenders, mesh systems, and other devices that support what is commonly referred to as ‘wireless on the WAN’. These devices connect to the ISP via WiFi instead of Ethernet, DSL, DOCSIS, GPON, etc.

CDRouter’s WAN AP can be enabled and configured using the testvars described below.


As usual, the WAN interface can be set with the wanInterface testvar.

If a wireless interface is specified, CDRouter’s internal WiFi AP will be enabled. Further configuration of CDRouter’s AP can be done in the “Wireless Access Point (AP)” section of the configuration file.

If wireless authentication is desired on the WAN, this can be enabled by setting the wanAuthenticator testvar to yes. In this case, CDRouter will provide all authentication services on its AP.

If a wireless interface is specified and a WAN authenticator is used, further configuration of CDRouter’s AP can be done in the “WPA Authenticator” section of the configuration file.

When setting up the DUT to use CDRouter’s WAN interface as its wireless AP, it is often necessary to have CDRouter’s AP up and running so that the DUT can see it and be configured to use it. Starting the test package can accomplish this. During the start process, CDRouter’s wireless AP will be running, allowing the DUT to be configured. If the start process ends too quickly to allow time to configure the DUT, the startTimeout testvar can be increased.

Please note that if a wireless connection is desired on both the LAN and WAN, then two physical wireless cards are required by CDRouter.

NAT and Firewall Configuration

The following testvars define the expected NAT behavior of the DUT.

CDRouter 7.3+ allow NAT to be disabled for testing CPE devices with public IP LAN clients. Please see this article for more information and configuration examples.

NAT Setup

NAT Timer Configuration

Protocol Pass Through Setup

IPSEC Pass Through Configuration

PPTP Pass Through Configuration

L2TP Pass Through Configuration

PPPoE Pass Through Configuration

Special Application Port Triggers Setup

Application Layer Gateway Setup

H.323 (NetMeeting) ALG Configuration

MSN Messenger ALG Configuration

RTSP ALG Configuration

SIP ALG Configuration

If the DUT supports a SIP ALG the following testvars should be configured.

FTP ALG Configuration

Virtual Services Setup (TCP and UDP)

TCP Virtual Services Configuration

UDP Virtual Services Configuration

Denial of Service Configuration

Deprecated SSL Protocol and Cipher Configuration

DMZ Configuration

CDRouter can test routers with a DMZ configuration. In order to test with a DMZ configuration, an IP address for a DMZ host on the LAN must be configured. This address must be on the same subnet as the router’s LAN IP address.

As part of the DMZ testing, CDRouter will scan a range of TCP and UDP ports to verify that the router forwards these entries to the DMZ host. These port scans skip any virtual services that are configured on the router. There is also an option to specify other ports that should be skipped. These may be specific ports that have been configured to drop packets or reject connections regardless of the DMZ configuration. For example, port 113 (ident) is commonly configured to reject connections.

All of the existing test modules can be run when the router has a DMZ configuration except the firewall module. When a DMZ host is configured, the firewall module is automatically skipped since the DMZ setting defeats any general firewall setting.

The following DMZ configuration parameters are available:

URL Filtering Configuration

XBox Configuration

Advanced Protocols Configuration

RIP Setup

The following testvars describe the RIPv1 or RIPv2 configuration of the DUT.

Static Route Setup

The following testvars describe any LAN or WAN static routes that may be configured on the DUT.

UPnP Setup

The following testvars describe the UPnP configuration of the DUT.

LLDP Setup

CDRouter 8.0 added support for LLDP. Please see this Knowledge Base article for more information.

Multicast Setup

CDRouter can test routers with IGMP proxy or multicast pass through support. CDRouter will act as an IGMPv2 or IGMPv3 client on the LAN side of the router. CDRouter will also act an as a multicast router on the WAN side of the router and deliver multicast streams.

If the router supports IGMP proxy, it must be configured to run an IGMPv2 or IGMPv3 client on the WAN interface. Please see this article for more information on multicast testing with CDRouter.

The following multicast configuration options are available:

IGMP Timer Configuration

IPTV Configuration

Additional Features Configuration

General Purpose HTTP Server Configuration

Free Network Range Configuration

During a test run, CDRouter will simulate different hosts on both the LAN side of the network and the WAN side of the network. In some cases, CDRouter may need to find an unused IP network or IP address to use in a test. Some of the tests also use a host IP on the WAN interface that can be configured with remoteHostIp . This IP address should not conflict with any addresses in the free network range. Also, it should not be on the same IP network as the router’s WAN IP address. The following diagram shows logically how the remoteHostIp address is used.


TCP MSS Clamping Configuration

TCP/UDP Scaling Configuration

Test Execution Options and Auto-Reboot Configuration

The following testvars can be used to various aspects of how tests are executed, including auto-reboot.

CDRouter 12.13 and newer releases no longer prompt the user to manually restart the DUT at the beginning of every test run. To restore the original behavior from previous releases, the testvar RestartDut must be set to the value prompt.

In all releases prior to CDRouter 12.13, CDRouter will automatically pause and prompt the user to reboot the DUT at every test run.

IMPORTANT(setup): 13:53:56.857| Restarting DUT ...

>>> Please restart the device under test
>>> Then PRESS <enter> to continue: 

CDRouter is paused.

Rebooting the DUT is recommended to ensure that the device is in a “known state” and helps to avoid inconsistent behavior during testing.

To avoid having to manually reboot the DUT and un-pause CDRouter to proceed with the test run, you can define the RestartDut testvar to launch a custom script that is able to reboot the DUT automatically.

Similarly, the ShutdownDut testvar will call a custom script that can power off the DUT.

Your custom scripts may be written in any language you choose so long as it can be executed from the Linux command line shell.

The RestartDut testvar takes a single TCL string representing the script name and any optional arguments that you may want to be passed in with the script. If you are passing arguments to the script, you need to put the entire testvar value within quotes so that it is treated as a single string:

testvar RestartDut       "/usr/cdrouter-data/custom/myScript arg1 arg2"

You can execute multiple commands by separating them with a semicolon ( ; ):

testvar RestartDut       "/usr/cdrouter-data/custom/myScript arg1 arg2 ; /usr/cdrouter-data/custom/myScriptTwo a1 a2 a3"

Since CDRouter executes the script using the TCL “exec” command, you need to be careful to avoid any special characters (like ‘$’ and ‘[’ ) that might be interpreted by the TCL parser.

If you want to pass the value of a CDRouter testvar from your config file into the script, you need to use the following CDRouter TCL syntax:

testvar RestartDut       "/usr/cdrouter-data/custom/myScript [buddy::getvar wanIspIp] arg2"

It is important to note that when using this syntax, CDRouter resolves the expression immediately as it parses the RestartDut testvar value. CDRouter replaces this syntax with the resulting value, and then continues to parse the rest of the config file. So in the example above, the wanIspIp testvar must be defined earlier in the config file than the RestartDut testvar. Otherwise, the buddy::getvar syntax will return a default value for wanIspIp.

CDRouter provides default values for most testvars. If a default value is not available, an empty string ("") is returned. Please see the Testvars documentation page for more details on default values assigned by CDRouter.

To see a practical example of how the RestartDut and ShutdownDut testvars might be used to control a managed power supply to power the DUT on and off, please see this Knowledge Base article.

Nmap Configuration

CDRouter Nmap is new expansion that is automatically included in the base version of CDRouter beginning with CDRouter 7.0. The CDRouter Nmap expansion includes four test modules, nmap.tcl, nmap-wan.tcl, nmap-v6.tcl, and nmap- wan-v6.tcl, which are designed to provide additional information about the DUT and how it behaves and appears on the network using the popular Nmap network scanner. The Nmap test modules perform various Nmap port scans on the DUT’s LAN and WAN interfaces over both IPv4 and IPv6. Please see the Nmap test case summaries for details on the tests included.

Note that CDRouter’s Nmap test modules ire based on the 6.00 version of Nmap and require a 2.6.35 or newer Linux kernel. Also note that the IPv6 Nmap tests can only be run if the CDRouter IPv6 expansion is installed.

Minimal configuration is required to run the Nmap tests. By default Nmap support is disabled within CDRouter. To enable Nmap the testvar enableNmap must be set to yes. The testvar nmapScanTimeout is provided which defines the amount of time to wait for an Nmap scan to complete. If the timeout is reached, the scan will be stopped and the test will be marked as a FAIL. This testvar defaults to a value of 900 seconds. The testvar nmapTimingTemplate selects the timing profile that will be used for each scan. Nmap has 6 built in timing templates that adjust retries and timeouts. The values range from 0 to 5. CDRouter uses a default value of 5 which runs the scan as fast as possible. Lowering this value will produce slower scans. Please see Nmap’s manual for more information on the timing template option.

The following testvars enable Nmap support within CDRouter.

End to End Testing

Normally, CDRouter is used to test a single Cable/DSL router device. However, the test suite can be configured to test through a network that contains additional IP devices. Typically, this is used to test a Cable/DSL router connected to a DSLAM device through a cable/xDSL modem. This can also be used to test routers that have built in xDSL connections.


If multiple IP routers are connected between the Cable/DSL Router and the WAN interface on the test host, the WAN mode can be configured to ‘static’ or ‘DHCP’. In order to use DHCP on the WAN in this type of topology, a DHCP-relay agent is required.

Multiple Routers on the WAN: Static Mode

The wanIspIp and wanIspGateway addresses should be set based on the IP address of the first router connected to the WAN side of CDRouter. The wanNatIp variable should be set to the expected WAN side address of the Cable/DSL router.



The following example configuration could be used on the WAN side to enable CDRouter to run in the example topology above.

# -- set WAN interface to static mode
testvar wanMode static

# -- the ISP’s IP address
testvar wanIspIp
testvar wanIspMask
testvar wanIspGateway

# -- the expected NAT address of the router under test
testvar wanNatIp

# -- the expected number of IPv4 hops in the topology
testvar IPv4HopCount 3

Multiple Routers on the WAN: DHCP-Relay Mode

To run in DHCP-relay mode, two additional configuration parameters are needed. The wanIspIp and wanIspGateway addresses should be set based on the IP address of the first router connected to the WAN side of the test suite. The additional testvars wanIspAssignIp and wanIspAssignGateway should be included and configured to the IP address and IP gateway address that should be assigned to the Cable/DSL router. The wanNatIp variable should be set to the expected WAN side address of the Cable/DSL router.

Please see this Knowledge Base article for more information on DHCP relay testing.

IPv4 Hop Count

The IPv4HopCount testvar specifies the number of IPv4 hops between the LAN and WAN interfaces. In the default setup where CDRouter is directly connected to the DUT, this is set to 1. In the configurations above where there are multiple routers connecting CDRouter’s WAN interface to the DUT, this testvar should be increased to account for the additional router hops.

Hotspot Routers

CDRouter supports hotspot routers that require a user to log in to a captive portal before full access is granted to the WAN. Hotspot support in CDRouter allows a DHCP client to log in to a web service using HTTP or HTTPS. Each DHCP client may have an associated user name and password configured or automatically assigned.

If the hotspot router uses RADIUS authentication for hotspot clients, CDRouter may also act as a RADIUS server and handle authentication and accounting requests from the router. The RADIUS server currently only handles PAP style authentication.

A typical scenario involves a client on the LAN trying to reach a service on the WAN side of the hotspot router (e.g. a host on the Internet). The LAN client would typically try to reach this host with an HTTP or HTTPS GET. This initial GET is ‘captured’ and redirected by the hotspot router to a login page or challenge of some sort. The LAN client would have to satisfy this challenge before the hotspot router forwarded the initial GET to the host on the Internet.

Basic Hotspot Configuration

The HTTP or HTTPS login can be enabled by defining a list of URLs that should be accessed once the DHCP client on the LAN is active. Normally, more than one URL is required to login. The first URL triggers HTTP redirection and typically sets up an HTTP session cookie. The next URL may send an HTTPS GET that includes a username and password.

Example configuration:

testvar browserLoginUrl1
testvar browserLoginUrl2

The browserLoginUrl* testvar entries may contain 3 different keywords surrounded by the “%” character that are dynamically substituted for each clients specific values before the URL is accessed.

  • %USERNAME% is translated to the client’s user name.
  • %PASSWORD% is translated to the client’s password.
  • %IPADDRESS% is translated to the clients IPv4 address on the LAN.

Username and password come from what is defined by:

testvar clientLoginName1 qacafe
testvar clientLoginPassword1 password

IP address is the value the LAN client received when it asked for an address during the “start” test.

If a URL is required to logout, it may be specified with:

testvar browserLogoutUrl1

Advanced Hotspot Configuration

In scenarios where the login and logout process is more complex, custom login and logout Tcl procedures may be defined to handle the complexity.

The name of the login and logout Tcl procedures are defined with the testvars in the “Advanced Hotspot Settings” section of the CDRouter configuration file. The location of the file that contains the custom Tcl procedures may also be specified in this section.

testvar browserLoginProc example_login
testvar browserLogoutProc example_logout
testvar browserScriptsPath /usr/cdrouter/tests/helper-scripts/hotspot-login.tcl

Client User Names and Passwords

If not explicitly specified the client usernames and passwords default to client<N> and admin<N> for each client where <N> is the client number. For example, the first DHCP client will have a username of “client1” with a password of “admin1”.

Specific usernames and passwords for each client may be configured using the following testvars.

testvar clientLoginName1 qacafe
testvar clientLoginPassword1 qacafe123
testvar clientLoginName2 fish
testvar clientLoginPassword2 secret123

Hotspot Configuration Reference

Advanced Hotspot Script Example

CDRouter provides a few example hotspot login scripts in /usr/cdrouter/tests/helper-scripts.

The following Tcl script demonstrates an example login procedure. It uses calls made to the CDRouter pktsrc API to interact with the test environment.

# Login procedure
# The login procedure takes the client stack as its only argument.
# In this example, the client sends an initial HTTP GET to a
# web page in order to start the HTTP redirection process. During
# the redirection, a session cookie will be established. The client
# then sends a HTTP GET to load a login page using the username
# and password.

proc example_login { stack } {
    upvar $stack s

    set router [ testvar lanIp ]
    set username [ Stack_get_client_name s ]
    set password [ Stack_get_client_password s ]
    set remoteIp [ testvar remoteHostIp ]
    # -- load a dummy URL to trigger the redirection
    HTTP_get s http://$remoteIp/dummy.htm page1

    # -- load the login page ans send password
    set urlbase https://$router/loginpages/userlogin.shtml?myusername
    set status [ HTTP_get s $urlbase=$username&mypassword=$password page2 ]

    # -- check the result
    if { $status < 0 } {

        pktsrcWarn s "Client $name failed to login"

    } elseif { "$page2(response-code)" != "200" } {

        pktsrcWarn s "Received response $page2(response-code), expecting 200"


    # -- done with login

In the following example, we demonstrate using the CDRouter pktsrc API to call a separate external script (in this case Python) to handle the hotspot login process.

# Login procedure
# The login procedure takes the client stack as its only argument.
# In this example, the client is set up so that an external script can
# be executed to send what is needed to satisfy the captive portal 
# login process.

#checker -scope line exclude warnRedefine
proc example_login { stack } {
    upvar $stack s

    set router [ buddy::getvar lanIp ]
    set username [ Stack_get_client_name s ]
    set password [ Stack_get_client_password s ]
    set remoteIp [ buddy::getvar remoteHostIp ]

    # Bind to CDRouter's LAN networking stack. 
    # CDRouter's stacks will have IP addresses that your services can bind to.
    # Using offload interface to allow traffic gnerated by external script
    # to be sent. 
    if {![info exists s(offload-handle)]} {
        Offload open s IPv4

    pktsrcInfo s "Creating offload interface "

    # Ensure appropriate namespace is used
    set netns [ Offload netns s ]

    # Make call to execute custom external python script to handle hotspot login

    pktsrcInfo s "Calling python script to authenticate with hotspot"
    set handle [pktsrc::app::exec offload {python /usr/cdrouter/tests/helper-scripts/} {} {} $netns]

    pktsrcInfo s "Hotspot login complete"

    pktsrc::app::close $handle

    pktsrcInfo s "Closing offload interface"

    if {[info exists offload_created]} {
        Offload close s


Adding New Test Cases

NOTE: QA Cafe now has a separate Developer’s Guide. Please refer to the CDRouter Developers Guide for an overview of the test development process.


Upgrading CDRouter is an easy process – just follow the steps below.

Upgrading an Existing Installation

Upgrade to a New Release of CDRouter:

If you would like to upgrade to a newer release of CDRouter, there is no need to re-install the license file. To upgrade, simply download the new release from the Customer Lounge and follow the installation instructions provided in the installation section of this User Guide , omitting the steps related to installing a license file.

Install New Expansions or Update the License File for an Existing Installation:

If you have purchased additional CDRouter expansions or extended your Maintenance and Service Agreement, you must update your license file. Please the instructions in this guide to update your license.

Upgrading from the Demo Version

Before installing the full version of CDRouter on a system that was previously running the CDRouter Demo, you should delete the demo version and license file completely.

You can use the -e flag to automatically delete the demo version:

$ rpm -e cdrouterdemo pktsrc buddy

To remove the license file use the rm command:

$ rm –rf /etc/cdr-DEMO.lic

Test Notes

DHCP Client

The default DHCP lease time used by CDRouter is 300 seconds (5 minutes). If several of the dhcp-c.tcl module tests are failing, it could be that the router does not deal gracefully with a short DHCP lease time when setting up the T1 and T2 timers for DHCP. When a DHCP lease is starting to expire, some DHCP clients will drop directly into DHCP discovery mode without attempting to send any DHCP request packets. This can cause several test failures in the dhcp-c.tcl module. You can adjust the DHCP lease time by setting the dhcpLeaseTime variable in your configuration file.

NOTE: Some test cases will wait an entire DHCP lease interval. Setting the dhcpLeaseTime to a large value will slow down test execution dramatically. We recommend trying to find the smallest value that will work with your DHCP client.


All the CDRouter NAT tests verify that the router is using Network Address Port Translation (NATP).

Trigger Ports and Special Applications

CDRouter can test up to 4096 different trigger port configurations on a router. Each trigger port can be configured with a single outbound port number and one or more ports that should be open on the inbound side of the router.

Trigger Port Example

testvar triggerName1 My-Special-Application
testvar triggerPort1 10003
testvar triggerType1 tcp
testvar triggerPublic1 7501-7502
testvar triggerPublicType1 tcp

If the application has multiple outbound ports that will trigger the same inbound port range, you must configure multiple triggerPort entries for each outbound port number. In this case, QA Cafe recommends that you test each trigger port individually. Once the port mapping is created by the router, there is no conclusive way for CDRouter to verify that other outbound port connections will also open the same inbound port range.


CDRouter’s UPnP test module supports versions 1.0 and 1.1 of the Universal Plug and Play Device architecture defined by the UPnP Forum as well as both InternetGatewayDevice:1 (IGDv1) and InternetGatewayDevice:2 (IGDv2) device protocols.

Please see the UPnP testing guide for more information.


CDRouter uses its own version of TCP for verification of TCP traffic through the router and for TCP connections directed to the router for UPnP. When the TCP session is between two hosts across the router, any packet loss from the router will cause the TCP session to fail. The endpoints will not retransmit any lost TCP segments. This allows CDRouter to quickly determine packet loss by the router under test.

When the TCP connection is directed to the router (UPnP), CDRouter does use a retransmission timer on the TCP session. This allows the TCP session to recover from any packet loss from the router. Any packet loss detected by TCP will still be logged as a WARNING but will not cause a test to fail.

WARNING(lan) 12:40:00| TCP Retransmission timer fired for session *:10377 ->

IPSEC Pass Through

Some vendors have implemented an IPSEC pass through technique that attempts to associate inbound and outbound SPI values in the IPSEC ESP header to support multiple pass through connections to the same destination IP address. This allows a router to multiplex inbound IPSEC packets to the correct LAN host. Similar techniques also exist for ISAKMP packets using the initiator and responder cookies. The CDRouter test cases for IPSEC/ESP and IKE/ISAKMP use unique SPI and ISAKMP cookie values to allow these types of techniques to be verified.

H.323 ALG Testing

CDRouter uses H.225 Version 2 during the H.323 ALG tests. This is the same version used by Microsoft Netmeeting. The device under test must support H.225 Version 2 or higher.


CDRouter contains example X.509 certificates in PEM format that can be used for EAP-TLS. The password used to generate all certificates is qacafe123. If you are generating your own certificates, CDRouter should be configured to use PEM formats for the root and user certificates.

The example certificates are installed under:


Dynamic WEP

When using the built-in RADIUS server, the EAPOL test suite uses the MS-MPPE- Send-Key and MS-MPPS-Receive-Key attributes to relay dynamic key information to the authenticator device.