CDRouter Web CLI Guide

The CDRouter web CLI provides all of the tools necessary for controlling CDRouter’s web interface from a non-interactive environment such as an automation script or other custom utility.

There are several benefits to running tests from inside CDRouter’s web environment. Automatic queuing, results aggregation, package selection, tagging, etc. are all features unique to the web interface. To create an automated solution that still takes advantage of these additional features, the web CLI must be used.

CDRouter now comes with a complete set of web CLI commands that can list current Packages and Configurations available on the system, launch Packages and track their progress, and import and export files to and from CDRouter.

CDRouter’s web interface will reflect all changes made to the system from the web CLI. This makes it very easy for users to view and analyze results within CDRouter’s web interface that may have been automatically generated using the web CLI.

The CDRouter web CLI is controlled using the cdrouter command. It assumes by default that the CDRouter server you are interacting with is running locally. A different target can be selected via the -host option. More information is available in the Advanced section of this document.

All available options can be displayed by running cdrouter -help:

Usage of cdrouter:
  -debug
    	Enable CDRouter debug messages
  -edit-config NAME
    	Edit config NAME
  -export-config NAME
    	Export configuration NAME as a .gz file
  -export-package NAME
    	Export package NAME as a .gz file
  -export-result NAME
    	Export result NAME as a .gz file
  -export-result-csv NAME
    	Export result NAME as a .csv file
  -export-result-logdir NAME
    	Export result NAME's logdir as a .zip file
  -get-config NAME
    	Display config NAME
  -host HOST:PORT
    	Connect to CDRouter system HOST:PORT (default "localhost")
  -https
    	Connect to CDRouter system via HTTPS
  -import FILE
    	Upload and import .gz FILE
  -insecure
    	With -https, allow connections to CDRouter systems without valid certs
  -jobid
    	Return the job id after starting package
  -jobs
    	Display the jobs table
  -package NAME
    	Start the package NAME
  -password PASS
    	Use API password PASS to authenticate with CDRouter system.  If password is in the form @FILE, password will be read from FILE
  -replace
    	Replace any existing files when importing or exporting
  -running
    	Report what CDRouter is currently running
  -show-configs
    	List the configurations
  -show-packages
    	List the packages
  -show-result-id
    	Used with -status to return the Result-ID instead
  -skip
    	Skip any existing files when importing or exporting
  -status ID
    	Show the status of job ID
  -tags TAGS
    	Adds tags TAGS to the item being run or imported, separate tags with commas
  -token TOKEN
    	Use API token TOKEN to authenticate with CDRouter system
  -username NAME
    	Use API username NAME to authenticate with CDRouter system
  -version
    	print version information and exit
  -wait
    	Wait for package to complete before returning

Specifying an API Token

When CDRouter’s automatic login feature is disabled all users are required to authenticate before using the web interface or the web CLI. Authentication via the web interface is accomplished by providing a username and password. Authentication via the web CLI is accomplished by providing a valid API token to all commands.

An API token is an eight character hex string that is automatically created for all admin users. API tokens are available on the Account > Users page within the web interface for every user with admin privileges. Specifying a certain API token will associate all modifications made to the system through web CLI to that user.

If the automatic login feature is enabled, authentication is not required and any API tokens that are provided via the web CLI are ignored. All modifications made to the system in this mode will be associated with the system level admin user.

To specify an API token use the -token option:

cdrouter -token ffffffff

Launching a Package

Starting a test run is done by using the -package option, and specifying the name of the Package to launch. In the normal case, the command will return immediately after submitting the request to CDRouter.

cdrouter -package regression_1

Specifying the -wait option will prevent the command from returning until after the Package is finished. If the Package is queued, the CDRouter web CLI will continue waiting until it runs and completes.

cdrouter -package regression_1 -wait

Jobs

When a Package is launched, it is represented as a Job inside of CDRouter. Jobs simply keep track of what order Packages run in and their current state. By adding the -jobid option, CDRouter will return the Job’s ID after launching or queuing a package.

cdrouter -package regression_1 -jobid

This Job ID can then be used as the argument to -status in order to provide a simple text message about the current Job.

cdrouter -status 13

The text that is returned will be one of the following:

connection-failed
no-such-job
internal-error
starting
running
scheduled
finished
failed

Important: The status of a Job should not be queried more than once every 30 seconds.

To retrieve a list of the available Jobs, either finished, running, or queued; call cdrouter with the -jobs option. A list of Job ID’s will be returned.

cdrouter -jobs

Each ID can then be queried with the -status option to discover more detailed information about the Job’s current status.

Results

When a Job is finished running, the Results that were generated are available to view and export. These are accessed by knowing their Result-ID, which can be retrieved from CDRouter given the Job-ID that created them. Include the -show-result-id option along with the -status option.

cdrouter -status 13 -show-result-id

If the Job is still running, or hasn’t started yet, the command will return not-available. If the Result is available however, its 14-digit ID will be returned. This ID can be used with the -export-result, -export-result-csv and -export-result-logdir options described below.

Listing Resources

Knowing what is available from CDRouter can be very useful within a script. The CDRouter web CLI provides two methods to return lists of Resources. Similar to the -jobs option from before, it will list the names of Packages or Configurations.

cdrouter -show-packages
cdrouter -show-configs

Exporting from CDRouter

Individual resources can be exported from CDRouter into a single, zipped archive with a .gz extension. These files can be imported into another CDRouter system along with any tags, descriptions, and other meta data saved with them. This makes it very easy to duplicate setups from one CDRouter system to another.

Note: Exported files should not be edited or otherwise modified.

Packages

A CDRouter Package consists of a Configuration file, a list of test cases, a variety of additional run- time options, and any tags or meta data that have been applied. Packages must be exported by name, which can be found using the -show-packages option.

cdrouter -export-package regression_1

This example will export and save regression_1.gz to the current directory. This archive will contain the Package “regression_1”, the associated Configuration file, and all tags, test cases, and options.

Configurations

Configurations are exported the same way, and produce a similar .gz archive. Configurations must be exported by name, which can be found using the -show-configs option.

cdrouter -export-config local.conf

In this example the Configuration file local.gz will be exported and saved to the current directory.

Results

Results can be exported just like Packages and Configurations. They are referenced by their unique 14-digit Result-ID. This can be retrieved from recently completed Jobs using the -show-result-id option in conjunction with -status as describe above, or through other means.

cdrouter -export-result 20091118160622

Results exported with -export-result are exported as .gz archives which can be imported into other CDRouter systems. Results can also be exported as a .csv file with -export-result-csv:

cdrouter -export-result-csv 20091118160622

Finally, the contents of a result’s logdir can be exported as .zip archive with -export-result-logdir:

cdrouter -export-result-logdir 20091118160622

Replacing What’s on Disk

If there is already a file in the current directory with the same name as the export, CDRouter will ask the user if the file on disk should be replaced with the new one. This poses a problem if the export is being performed without user interaction. In this case, the -replace option can be added to always replace the existing file with the downloaded one. Replace works with any of the -export options.

cdrouter -export-result 20091118160622 -replace

Importing into CDRouter

Any resource that is exported from CDRouter can be imported back into it. The preferred format is a .gz exported archive generated by CDRouter. Additionally, .bw2 files and .zip or .tgz archives from older pre CDRouter 10.0 systems are also importable.

CDRouter’s importer is smart enough to figure out what has been uploaded based on the file’s content. The import option takes a local file name to import as its only argument.

cdrouter -import regression_1.gz

Because Package exports contain Configurations, this example will import the “regression_1” Package, as well its corresponding “local.conf” as well. This makes it extremely simple to copy Resources from one system to another without the fear of losing meta data, or the association between Configuration and Package.

Similarly, results can be imported into CDRouter this way. A Result exported from CDRouter as a .gz archive will retain all the information associated with it: tags, Packages, Configuration, comments, flags, etc. Each of these included Resources will be imported.

cdrouter -import 20091118160622.gz

Replacing What’s Already There

In cases where the Resource being imported already exists in CDRouter, the -import option will prompt to either replace the file in CDRouter with the new one, or skip importing that Resource. This can be useful in situations where a Result from another machine is being imported, but you don’t want to overwrite a Package or Configuration with the same name on this machine.

Just like the -export commands, -import also can take the -replace option to automatically replace the files in CDRouter with the newly imported versions without prompting the user.

cdrouter -import 20091118161622.gz -replace

Specifying a Different Target

For users with more than one CDRouter license, it is possible to control separate instances of CDRouter from a single networked machine. The web CLI provides the -host option, which specifies the hostname (or IP address) and port number where another CDRouter is running. By default, CDRouter runs on port 80 for new installations and port 8015 for older installations. The format of the -host argument must be hostname:port. To invoke any of the available commands on a remote machine, simply specify the -host option:

cdrouter -host 192.168.1.10:8015 -show-packages
cdrouter -host example.com:8015 -show-configs

The -https option can be used to connect to a CDRouter system via HTTPS. Including the -insecure option along with the -https option skips certificate validation which may be useful when connecting to systems with certain configurations.

Modifying testvars at Run-Time

It is also possible to modify the value of a configuration testvar at run-time using the -- operator. The -- operator allows users to use additional buddy specific CLI commands from the CDRouter web CLI. For example, the following command sets the value of the testvar wanMode to L2TP for the current test run, regardless of the value in the configuration file:

cdrouter -package regression_1 -- -testvar wanMode=L2TP

Here’s another example using a two testvars:

cdrouter -package regression_1 -- -testvar wanIspIp=12.12.12.1 -testvar wanIspAssignIp=12.12.12.2

If the testvar is part of a testvar_group, the -testvar_group option should be used instead. The format for the -testvar_group option is group:testvarName=value:

 cdrouter -package regression_1 -- -testvar_group lan2:lanSSID=testnet

If the value contains any whitespace it must be enclosed in quotes:

 cdrouter -package regression_1 -- -testvar firewallTcpOpenPorts="22 443"

Debug Information

If for some reason a web CLI command is not working and reporting errors, first make sure that CDRouter is running on the target machine. For detailed information that can be passed along to QA Cafe’s Support Team, enable the -debug option.

cdrouter -debug -import regression_1.gz -tags help

Please note that using -debug will expose PRIVATE URLs that the CDRouter CLI uses to communicate with CDRouter. These URLs are subject to change at anytime, and misuse of them may lead to loss or corruption of your entire CDRouter database.

Working with Configuration Files

Configuration files can also be viewed and edited directly via the web CLI using the -get-config and -edit-config options, respectively.

To display the contents of an existing configuration file use the -get-config option:

cdrouter -get-config "My config"

The output of the -get-config option can be redirected to create a local text copy of the configuration file:

cdrouter -get-config "My config" > "MyConfig.conf"

The -edit-config option opens the specified configuration file in an external text editor. This allows the configuration file to be edited directly from the CLI:

cdrouter -edit-config "My config"

The -edit-config option checks in several places to determine which editor to use. It first checks the value of the VISUAL environment variable, falling back to the value of the EDITOR environment variable if VISUAL is not set. If neither the VISUAL or EDITOR environment variables are set, -edit-config uses the vi editor.

Changes are committed when the configuration file is saved and the editor is closed.

Product

Search Results

CDRouter Web CLI Guide

Specifying an API Token

Launching a Package

Jobs

Results

Listing Resources

Exporting from CDRouter

Packages

Configurations

Results

Replacing What’s on Disk

Importing into CDRouter

Replacing What’s Already There

Tags

Launching a Package

Importing

Specifying a Different Target

Modifying testvars at Run-Time

Debug Information

Working with Configuration Files