CDRouter Support

CDRouter Quick Start Guide

quick-start-guide version 10.4

Introduction

Welcome to the world of CDRouter! And congratulations on purchasing the leading test tool for CPE devices and broadband access gateways!

This guide will help you connect CDRouter to your device and set up a basic test configuration so that you can begin running tests. We also offer brief Quick Start video tutoial, that illustrates much of the same information you’ll find here.

Before you begin, please make sure your CDRouter system is running the latest software update. If you are not using the NTA1000 platform, be sure your system meets the system requirements and that you have at least two dedicated network interfaces to connect to your CPE device. Check out our Getting Started with CDRouter page if you need help installing CDRouter or choosing a new system to install CDRouter on.

When you are finished with this guide, the following links will help you learn more advanced CDRouter configurations:

  • User Guides - Full documentation for CDRouter and other add-on test suites, like IPv6 and TR-069.
  • CDRouter Training - video webinars and reference articles offering introductions to more advanced features of CDRouter.
  • Knowledge Base - Articles containing guides for unique test conifgurations and tips to help you get the most out of CDRouter.

If at any time you have any questions or would like assistance, please contact us at support@qacafe.com.

Physical Connections

Basic Setup

Before you can run tests you must connect the device under test (DUT) to CDRouter as shown in the diagrams below. The interfaces used for testing should be dedicated to CDRouter exclusively and should not be used for management of the system or by other applications running on the system.

Setup for wired LAN tests

Setup for wireless LAN tests

When selecting test interfaces, do not use CDRouter’s management interface or any interface that is configured for use on a live network. You should also ensure that the test interfaces are not managed by any “auto-configuration” service on the system such as NetworkManager, as this will interfere with CDRouter’s ability to configure and use the interface for testing.

On the NTA1000 platform, eth0 is used as the managment interface for remote access to the system, and all other interfaces are unconfigured and available for use as test interfaces. Please refer to the following Knowledge Base articles for information on how to properly configure interfaces for use with CDRouter and prevent NetworkManager from controlling them:

Note that the NTA1000 is preconfigured and ready to use out of the box. No additional configuration is required for the test interfaces.

Complex Setups

For simplicity, this Quick Start Guide will focus primarily on setups involving a simple CPE deivce with an Ethernet WAN interface. However, if the router under test is a DSL or DOCSIS based device, CDRouter can be still be used, provided a DSLAM or CMTS, respectively, is available. For more information, please refer to these articles in our Knowledge Base for details and examples.

Connecting to CDRouter

CDRouter provides a convenient web interface for configuring and running tests.

The web interface can be reached from any web browser that has access to your CDRouter system. For example, if your CDRouter host system has an IP address of 10.0.0.5, point your browser to the URL http://10.0.0.5.

image

HTTPS Connections

By default, the web interface is accessible over either either HTTP or HTTPS.

http://10.0.0.5
https://10.0.0.5

When connecting over HTTPS, CDRouter provides a locally-generated certificate to establish an encrypted connection. Your web browser may warn you that the certificate is not from a trusted source. If this happens, click the appropriate link on the warning message to proceed and/or create an execption in your web browser if you are sure that you are connected to your CDRouter server.

Connection Port Number

Note that in versions of CDRouter prior to 10.0, the web interface was available using HTTP by connecting to port 8015. If you upgraded your CDRouter system from a previous version to CDRouter 10.0 or higher, the HTTP interface to CDRouter will continue to use port 8015, and you will have to add this port number to your URL:

http://10.0.0.5:8015

The following lines in the /usr/cdrouter-data/etc/config.yml file can be configured specify which port CDRouter’s web interface will listen on for HTTP and HTTPS connections, respectively.

port: 80
https: 443

For added security, the following line in the /usr/cdrouter- data/etc/config.yml file can be set to yes to redirect all HTTP connections to HTTPS.

force_https: "yes"

Adding Users

Once connected to CDRouter, you will automatically be logged in as the admin user.

When CDRouter is first installed, the admin user is the only user present on the system.

To add other users, select Users from the Admin dropdown menu in the upper- right corner to get to the Users page.

image

Click the New button to create a new user and set their password. By default, each user is only allowed to view and edit testing resources that they own or that have been shared with them. Users with the Admin flag set are able to view and edit all resources on the system regardless of who owns them. The admin user is a permanent user. It cannot be deleted and its username cannot be changed. Otherwise, all users with the Admin flag set are equivalent to each other and have all of the administrative rights that the admin user has.

image

To allow other users to login to CDRouter, you will need to disable automatic logins on the Users page. This will cause CDRouter to prompt all for a username and password in order to access the system.

Important: Before disabling automatic logins, make sure the admin user’s password has been set!

image

Automatic login can also be re-enabled to prevent CDRouter from prompting for a login username/password. When automatic login is enabled, all connections are automatically logged in as the admin user. All existing user accounts will still exist, and the admin user may change the ownership of any test results or configuraion resources to another user. Otherwise, all additional user accounts cannot be used while automatic login is enabled.

API Tokens

Every CDRouter user has an API token associated with their account. The API token can be used as an authentication mechanism with the the ‘cdrouter’ CLI command and CDRouter’s Web API interface to control CDRouter and automate tasks. Each user has a single, unique API token that is auto-generated when the account is created. New API tokens can be auto-generated from Users page, if necessary. Creating a new API token will replace the user’s existing token, and all web API operations for that user will then require the new token.

Note that CDRouter’s web API only requires an API token when automatic login is disabled. If automatic login is enabled, any API token included in a web API operation will be ignored, and the operation will be accepted and processed.

See the CDRouter web API and CLI documentation for more information:

Home Page

The home page provides a dashboard with system information and a summary of recent test results. Information on this page is continually updated, allowing you to monitor how well the latest tests are performing and quickly jump to results that interest you.

image

Setup and Test Execution

To begin testing with CDRouter, you will need to create a Test Package that contains all of the test cases you wish to run and run-time options which control the flow of the tests are executed.

Your test package will also need to specify a Configuration File which describes the DUT and the test environment using test variables called testvars.

CDRouter creates a set of Test Results for every test package that is launched. The test results contain detailed logs of each test case that is executed, packet capture files and a snapshot of the Configuration used during testing.

Use the navigation tabs at the top of the screen to reach the page for each component. By default, CDRouter only shows information that is owned by the user who is logged in. Admin users can use the filters on the left side of the screen to display resources owned by other users.

image

The sections below will guide you through the steps required to create a simple configuration file and test package, launch a test run against a connected device, and analyze the results.

Creating A Configuration File

Go to the Configurations page and click the New button to open CDRouter’s configuration editor. New config files are populated with a default configuration template.

The configuration file is grouped into sections of related functionality. At the top level, each section contains the testvars provided by each CDRouter Add-on test suite. The Base Configuration section contains testvars that apply to all test environments and do not rely on any additional Add-ons being present.

In this guide, all examples will focus on the “WAN” and “LAN” sections under Base Configuration section, which contain all the testvars used in setting up the interface addressing and initial services.

Please see the CDRouter User Guide for a more detailed description of the Base Configuration section of the config file. Documentation for each of the CDRouter Add-on test suites can be found in the User Guides section of the QA Cafe Customer Support website.

Within each section are individual settings, called testvars, that specify configuration details related to the DUT and the test environment. The testvars in your configuration also specify parameters CDRouter uses to emulate network services such as DNS, DHCP, CWMP, etc.

Collapsed sections can be expanded by clicking the arrow in the left margin (▶), or in between the curly braces at the end of the line ({↔}). In general, you should be able to locate the testvars you need by navigating to the appropriate section based on names. You can also search for testvars or any text string in your config file using the 🔍Find button.

image

CDRouter’s WAN interface simulates a WAN termination point, such as a next-hop router or PPPoE server, between CDRouter and the DUT. The “WAN Interface” section contains testvars that define the IPv4 subnet of this link, including CDRouter’s interface address, the address assigned to the DUT and the method used to assign that address.

SECTION "WAN Interface" {

    testvar wanInterface           eth2                *Interface connected to DUT*
    testvar wanIspIp               202.254.1.1         *CDRouter's WAN IPv4 Address*
    testvar wanIspAssignIp         202.254.1.2         *IPv4 Address assigned to DUT*
    testvar wanNatIp               202.254.1.2         *Expected IP address after NAT translation*
    testvar wanIspNextIp           202.254.1.3         *Alternate address assigned to DUT for renumbering tests*
    testvar wanIspMask             255.255.255.0       *Subnet mask of WAN Link"
    testvar wanMac                 b0:75:0c:01:00:01   *Expected MAC address of DUT WAN interface*
    testvar wanDutMac              00:0b:0b:0b:0b:0b   *MAC address of CDRouter WAN interface*
    testvar wanDomainName          qacafe.com          *DNS domain name assigned to DUT*
    testvar wanDnsServer           202.254.101.1       *Emulated DNS server*
    testvar wanBackupDnsServer     202.254.101.2       *Emulated DNS server (backup)*
    testvar wanBackupDnsServer2    0.0.0.0             *Additional backup DNS server*
    testvar wanBackupDnsServer3    0.0.0.0             *Additional backup DNS server*
    testvar forwardingMode         route               *Forwarding mode of DUT*
    testvar wanMode                DHCP                *Method to assign IPv4 address to DUT*
    testvar wanAuthenticator       no                  *Emulated 802.1x Authenticator*

}

The LAN Interface section describes the DUT’s configuration on the LAN interface.

SECTION "LAN Interface" {

    testvar lanInterface           eth1                *Interface connected to DUT*
    testvar lanMode                DHCP                *How CDRouter's LAN client obtains IPv4 address*
    testvar lanIp                  192.168.1.1         *LAN IPv4 address of DUT*
    testvar lanMask                255.255.255.0       *Subnet mask of LAN network*
    testvar lanMac                 b0:75:0c:00:00:01   *MAC address of CDRouter LAN interface*
    testvar lanMtu                 default             *MTU for LAN packets to prevent fragmentation by DUT*
    testvar lanHostname            mydut               *Hostname of DUT for use in DNS requests*
    testvar lanSecurity            NONE                *DUT's LAN security mechanism*
    testvar lanGuestMode           no                  *LAN Guest Mode enabled on DUT*

}

In the configuration template, all tesvars are commented out with a hash symbol (#), which is essentially equivalent to an empty file. CDRouter provides default values for most testvars, which means that you do not need to uncomment and explicitly define every testvar setting in order to accurately describe your test environment or device configuration.

When the cursor is on a line containing a testvar definition, CDRouter will display information about the testvar in the right-hand side of the screen. This includes a description of the testvar’s function and default value, if it has one.

Example: Default Template

In this first example, CDRouter’s default configuration template is used to test a network like the one pictured below:

image

The default configuration template assumes the DUT has the settings listed below. These are common factory defaults for many consumer CPE devices.

  • DUT is an IPv4 CPE device performing NAT translation betwen LAN and WAN interfaces
  • LAN interface is connected to CDRouter’s eth1 interface
  • WAN interface is connected to CDRouter’s eth2 interface
  • DUT uses DHCP on the WAN to obtain an IPv4 address, default router, and DNS server configuration. All servers (DHCP, DNS, etc.) are emulated by CDRouter.
  • DUT’s LAN IP address is 192.168.1.1
  • DUT is running DHCP on the LAN
  • DUT acts as a proxy DNS server on the LAN

With this setup, none of the testvars in the default config template need to be uncommented or changed.

CDRouter will run an emulated DHCP server on its WAN interface and wait for the DUT to request an address. CDRouter will also create an emulated LAN client that will request an address from the DUT’s DHCP server.

The remaining examples will build upon this default example in small incremental changes.

Example: PPPoE WAN Connection

If the DUT’s WAN interface is configured to connect via PPPoE, CDRouter can be configured to run a PPPoE server instead of DHCP on the WAN. The same WAN Interface testvars are used to specify parameters such as the IPv4 address of CDRouter and the DUT and DNS server address.

Uncomment and modify the appropriate testvars in the PPPoE Server and PPP Options section to match the DUT’s PPPoE connections settings for the PPPoE connection.

The following example configures the following parameters for the PPPoE link:

  • The username & password the DUT must use to authenticate with the PPPoE server
  • The value of the AC-Name tag to be returned by the PPPoE server
  • The value of the Service-Name tag to be returned by the PPPoE server
  • The PPP Authentication protocol used to validate the DUT’s connection is set to MSCHAPv2
SECTION "PPPoE Server" {

    # testvar pppoeConnectOnDemand             no
    # testvar pppoeIdleTimeout                 60
      testvar pppoeUser                        dut_client
      testvar pppoePassword                    dut_password
      testvar pppoeAcName                      CDRouter_AC
      testvar pppoeServiceName                 CDRouter_Service
    # testvar pppoeAcCookie                    auto
    # testvar pppoeMaxPayload                  none

}

SECTION "PPP Options" {

      testvar pppAuthType                      PAP
    # testvar pppForceLcpMRU                   1500
    # testvar pppMagicNumber                   yes
    # testvar pppConnectionDelay               10
    # testvar pppRestartTimeout                300000
    # testvar pppFailUsesICMP                  no

}

Example: Wireless LAN client

To have CDRouter’s LAN client connect to the DUT over an 802.11 wireless interface, make the following changes to your config file in the Base Configuration > LAN > LAN Interface and Base Configuration > LAN > 802.11 Wireless sections.

  • Uncomment the lanInterface testvar and set the value to wlan0 (ie. name of the wireless interface in your CDRouter system).
  • Set the lanSSID testvar to match SSID of the DUT. Enclose the SSID in quotes if the SSID contains spaces.
SECTION "LAN Interface" {
      testvar lanInterface                     wlan0
    # testvar lanMode                          DHCP
    # testvar lanIp                            192.168.1.1
    # testvar lanMask                          255.255.255.0
    # testvar lanMac                           b0:75:0c:00:00:01
    # testvar lanMtu                           default
    # testvar lanHostname                      mydut
    # testvar lanSecurity                      NONE
    # testvar lanGuestMode                     no
}

SECTION "802.11 Wireless" {
      testvar lanSSID                          "DUT Wireless AP"
}

If the DUT’s wireless network is “open”, leave the lanSecurity set to "NONE" (same as being commented out). Otherwise, set lanSecurity to match the security mechanism configured on the DUT (WPA- PSK, WPA-802.1X, WEP, etc.), then configure the associated security parameters in the 802.11 Wireless section.

In this example, CDRouter will connect using WPA-PSK (pre-shared key), and will automatically scan to select the best version and encryption parameters offered by the DUT:

SECTION "LAN Interface" {
      testvar lanInterface                     wlan0
    # testvar lanMode                          DHCP
    # testvar lanIp                            192.168.1.1
    # testvar lanMask                          255.255.255.0
    # testvar lanMac                           b0:75:0c:00:00:01
    # testvar lanMtu                           default
    # testvar lanHostname                      mydut
      testvar lanSecurity                      WPA-PSK
    # testvar lanGuestMode                     no
}

SECTION "802.11 Wireless" {
      testvar lanSSID                          "DUT Wireless AP"

    SECTION "WPA Encryption Configuration Options" {

        # testvar wpaMode                          auto
        # testvar wpaCipher                        auto
        # testvar wpaGroupCipher                   auto
          testvar wpaKey                           "DUT_secret_key"

    }
}

In the example below, CDRouter will force the LAN interface to connect via WPA even if the DUT supports WPA2. The DUT also supports both 2.4GHz and 5GHz connections on the same SSID, but the lanBSSID testvar is explicitly set to the BSSID of the DUT’s 5GHz receiver.

SECTION "LAN Interface" {
      testvar lanInterface                     wlan0
    # testvar lanMode                          DHCP
    # testvar lanIp                            192.168.1.1
    # testvar lanMask                          255.255.255.0
    # testvar lanMac                           b0:75:0c:00:00:01
    # testvar lanMtu                           default
    # testvar lanHostname                      mydut
      testvar lanSecurity                      WPA-PSK
    # testvar lanGuestMode                     no
}

SECTION "802.11 Wireless" {
      testvar lanSSID                          "DUT Wireless AP"

    SECTION "WPA Encryption Configuration Options" {

        # testvar wpaMode                          auto
        # testvar wpaCipher                        auto
        # testvar wpaGroupCipher                   auto
          testvar wpaKey                           "DUT_secret_key"

    }

    SECTION "Advanced Wireless Settings" {

          testvar lanBSSID                         b0:75:0c:65:43:21
        # testvar lanChannel                       auto
        # testvar lanWirelessMaxClients            32

    }
}

Creating A Test Package

The Packages page is where tests are selected to be executed against a device. Each package is paired with a configuration file and a set of options to control the flow of testing.

Click the New button to open the package editor and begin creating a new package.

image

Select the tests you want to run by selecting them from the test selection section at the bottom and clicking Add tests to add them to the Testlist at the bottom of the page. You can select individual tests or add entire modules or add-ons all at once.

image

Tests will be executed in the order they appear in the Testlist. Modules and add-ons added as a group will be placed in the Testlist as a bundle that can be moved around as a single item. It is also possible to unbundle modules and add-ons and rearrange test cases individually.

image

By default, CDRouter executes each test one time in the order they are listed. Click the Edit Options button to enable additional parameters that control the execution and repetion of tests in a variety of ways.

image

Click Create to save the test package and add it to the Packages page.

Launching Test Packages

Once your test package has been saved, click the Launch button to begin running your tests.

You can also launch several test packages by selecting them on the Packages page and clicking the Launch button.

Whenever any test package is launched, it is added to CDRouter’s Job Queue. CDRouter runs each package sequentially in the order it appears in the job queue. CDRouter does not support running multiple jobs simultaneously. To view the job queue, select Jobs from the Admin dropdown menu in the upper-right corner.

image

Analyzing Test Results

After launching your test package, you can monitor progress from the Results page. By default, the most recent test results are listed first. Test results named with a timestamp representing the date and time the test package was executed.

image

Note that if you launch a test package while other tests are running, it will be added to the job queue, and will not appear on the Results page until it actually begins starts.

Click the test result name of the test package you just executed to view the test execution in real-time. From the Results page you can view the detailed results, open the results folder, print a report, or export the results directory for a particular test package. The Results page also displays a summary of the number of tests that passed and failed, the test duration.

image

Click the Log link next to each test case to view the detailed log file and analyze the results. The log includes all of the test activity including inline packet decodes of all traffic sent and received during the test. The log file can be highlighted and annotated with with notes to save and share with colleages.

image

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: