CDRouter Quick Start Guide
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 tutorial, 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.
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 expansion 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 configurations 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.
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.
Complex Setups
For simplicity, this Quick Start Guide will focus primarily on setups involving a simple CPE device 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.
- DSL CPE Testing with CDRouter
- DOCSIS Cable Gateway Testing with CDRouter
- Connecting to CDRouter through multiple routers
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 following URL:
http://10.0.0.5/
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.
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.
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 Expansion test suite. The Base Configuration section contains testvars that apply to all test environments and do not rely on any additional Expansions 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 Expansion 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.
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 testvars 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
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 between 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 or
WEP), then configure the associated security parameters in the
802.11 Wireless section.
In this example, CDRouter will connect using WPA 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
# 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
# testvar lanGuestMode no
}
SECTION "802.11 Wireless" {
testvar lanSSID "DUT Wireless AP"
SECTION "WPA Encryption Configuration Options" {
testvar wpaMode WPA-Personal
# 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.
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 section
at the bottom of the page. You can select individual tests or add entire
modules or expansions all at once.
Tests will be executed in the order they appear in the Testlist section of the test package. Modules and expansions added as a group will be placed in the Testlist section as a bundle that can be moved around as a single item. It is also possible to unbundle modules and expansions and rearrange test cases individually.
For your first test package we recommend using one of the pre-defined testlists that come installed with CDRouter. Click the Show Testlists button in the package editor and select any of the Testlists you want to run. Testlists can be added and rearranged in the same manner as expansions, modules, and individual test cases.
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 repetition of tests in a variety of ways.
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.
To view the job queue, select Jobs from the user’s dropdown menu in the
upper-right corner.
For CDRouter 13.0 and above, when multiple test instances are available, CDRouter will run test packages in parallel. Each package must use separate physical interfaces, and at most one package with a wireless interface can run at a time. Parallel testing is limited by the number of test instances available on CDRouter. For example, if there are four test instances, up to four packages can be run simultaneously. For more information and pointers on running high volume testing using multiple interfaces and devices, see Running Multiple Packages at Once.
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.
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.
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
colleagues.
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.
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.
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!
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 configuration resources to another user. Otherwise, all additional user
accounts cannot be used while automatic login is enabled.
