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.
While the full power of CDRouter will always be available through the original
CDRouter CLI using the
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
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
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 -package regression_1
-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
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
Each ID can then be queried with the
-status option to discover more
detailed information about the Job’s current status.
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
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-logdir options described
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: Prior to CDRouter 10.0, all exports used the proprietary
extension. Exports in this format can be imported into CDRouter 10.0+ systems
along with the new
.gz export format.
Note: Exported files should not be edited or otherwise modified.
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
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 are exported the same way, and produce a similar
archive. Configurations must be exported by name, which can be found
cdrouter -export-config local.conf
In this example the Configuration file
local.gz will be exported and saved
to the current directory.
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
option in conjunction with
-status as describe above, or through
cdrouter -export-result 20091118160622
Results exported with
-export-result are exported as
which can be imported into other CDRouter systems. Results can also
be exported as a
.csv file with
cdrouter -export-result-csv 20091118160622
Finally, the contents of a result’s logdir can be exported as
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
option can be added to always replace the existing file with the
downloaded one. Replace works with any of the
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.
.bw2 files and
.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
cdrouter -import 20091118160622.gz
Replacing What’s Already There
In cases where the Resource being imported already exists in CDRouter,
-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
-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
Tags allow you to manage, sort, and maintain structure among Results, Packages, and Configurations. From the CLI, tags can be applied when Launching a Package or when Importing.
Launching a Package
-tags option from the web CLI will add the specified tags to
the Result. This can be useful in labeling the Result, such as the
fact it was launched via the web CLI.
cdrouter -package regression_1 -tags cli
Multiple tags can be specified by enclosing the argument in quotes and separating individual tags with commas. Spaces are allowed in tag names.
cdrouter -package regression_1 -tags "cli,firmware-1.0,beta 1"
-tags option is also available when importing a Resource into
CDRouter. The specified tags will be applied to every Resource that
is imported. For example, this command will tag both the Package and
the associated Configuration with the tag “beta”:
cdrouter -import regression_1.gz -tags beta
When importing a Result, remember that the tags will be applied to everything that Result contains: Result, Package, and Configuration.
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
cdrouter -host 192.168.1.10:8015 -show-packages cdrouter -host example.com:8015 -show-configs
-https option can be used to connect to a CDRouter system via
HTTPS. Including the
-insecure option along with the
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
cdrouter -package regression_1 -- -testvar wanMode=L2TP
Here’s another example using a two testvars:
cdrouter -package regression_1 -- -testvar wanIspIp=126.96.36.199 -testvar wanIspAssignIp=188.8.131.52
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
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"
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
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
-edit-config options, respectively.
To display the contents of an existing configuration file use the
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"
-edit-config option opens the specified configuration file in an external
text editor. This allows the configuration file to be edited directly from the
cdrouter -edit-config "My config"
-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
EDITOR environment variables are set,
-edit-config uses the
Changes are committed when the configuration file is saved and the editor is closed.