The CDRouter Backup and Restore Tools

Introduction

It is very important to back up your CDRouter systems on a regular basis to protect against possible risks such as hardware failures, data corruption errors or other accidents that could results in your test configuration data and results becoming permanently lost.

CDRouter provides a set of command-line tools that allow you to create a full backup of the entire CDRouter configuration database and test results, as well as restore your data in the event of a catastrophic failure.

These tools can also be used when upgrading your NTA1000 or NTA3000 hardware to transfer your CDRouter data and test results to the new platform.

Tools

The CLI tools below can be found in the /usr/cdrouter/bin directory of your NTA platform:

• cdrouter-backup - Creates a backup archive of your CDRouter data directory (/usr/cdrouter-data) and copies it to a remote destination via SFTP.

• cdrouter-restore - Restores a the state of your CDRouter data directory from a backup archive previously created by cdrouter-backup.

• cdrouter-migrate - After transferring your data from an NTA1000 platform to an NTA3000, this tool can be used to upgrade your config files all at once. This will update the names of any network interfaces to match the new names used by the NTA3000.

CDRouter Backup Tool

The CDRouter Backup tool will gather all the saved user data within the /usr/cdrouter-data directory tree. This includes all the generated results, configuration files, packages, devices and the CDRouter database. By default, it will archive/compress/transfer to the specified destination into a tar/zipped file with the name "cdrouter-backup-\<YYYYMMDDHHmmss\>". The archiving is done locally, but the compression will occur during the transfer to the destination.

Depending on the amount of data saved, this process could potentially take a long time. The actual time it will take is dependent on several factors. Some of these are (but not limited to) the amount of data that is being backed up and the speed of the network link between CDRouter and the remote destination.

The CDRouter web UI will automatically be stopped when this process is occurring, so no tests may be run while the backup tool is running.

(The CDRouter web UI must remain stopped. Restarting the web UI during this process will corrupt the backup file and result in lost data.)

The remote destination you choose should have enough space to store a single large data file. The theoretical max of the data that is being backed up is the size of the data disk in the NTA, which is 4TB for the NTA1000 and 8TB for the NTA3000. This does not mean that your destination needs this much space. The compression will reduce this to a significantly smaller size. (For example, a 227GB database was compressed into a 53GB file)

(Note: The CDRouter Backup tool uses SFTP to securely transfer files. If the destination is a remote system, it must support/enable SFTP.)

Example

The example below connects to the sysadmin user account on the remote system named backup-nas.lan, and then creates a backup of the CDRouter system with the default name ("cdrouter-backup-\<YYYYMMDDHHmmss\>") in the /vol1/backups/ directory.

/usr/cdrouter/bin/cdrouter-backup sysadmin@backup-nas.lan:/vol1/backups/

checking CDRouter system, this may take a while on large systems... done.
backing up 226.82 GiB to /vol1/backups/cdrouter-backup-2024031213336 on 172.16.1.211
stopping CDRouter... done.
creating backup... 123.50 GiB / 226.82 GiB [==========================>-----------------------] 54.45% 60.00 MiB/s 27m43s

Users may specify a custom file name for the backup file, as in the example below:

/usr/cdrouter/bin/cdrouter-backup sysadmin@backup-nas.lan:/vol1/backups/my_cdrouter_backup.bin

When the CDRouter Backup tool is launched, it will calculate and display the total size that will be backed up and then will automatically begin the transfer/compression/archive process.

The tool will display statistics as it makes progress. It will display the running total of how much data has been backed up, the percent complete, the speed of the network transfer, and the approximate time remaining to complete the backup.

(Note: as mentioned above, the Backup tool will only backup files in the /usr/cdrouter-data directory tree. If you have other files, such as your own Linux-executable scripts, SSL certificates or custom test cases, located in other directories, they would need to be backed up separately. Of course, we encourage that these additional files are stored under /usr/cdrouter-data so they may be included in backups done with this tool.)

CDRouter Restore Tool

The CDRouter Restore tool will access a remote backup file located at the destination specified. It will transfer and extract the CDRouter data contained within it (defined devices, configuration files, packages, and results) into CDRouter’s /usr/cdrouter-data directory.

Note: Any existing files in /usr/cdrouter-data will be permanently erased.

There is no option to copy or save the previous files when running the cdrouter-restore tool.

Depending on the size of the backup file, the restore process could take a long time. The actual time it will take is dependent on several factors. Some of these are (but not limited to) the size of the file being restored and the speed of the network link between CDRouter and the remote destination.

The CDRouter web UI will be stopped when this process is occurring, so no tests may be run while the restore tool is running.

(The CDRouter web UI must remain stopped. Restarting the web UI during this process will corrupt the database and result in lost data.)

Example:

/usr/cdrouter/bin/cdrouter-restore sysadmin@backup-nas.lan:/vol1/backups/cdrouter-backup-2024031213336

checking CDRouter system, this may take a while on large systems... done.
restoring from /vol1/backups/cdrouter-backup-2024031213336 on backup-nas.lan
WARNING:

* 226.82 GiB will be copied from /vol1/backups/cdrouter-backup-2024031213336 to this system.

* This program will erase the CDRouter data directory of the local
  system and replace it with the data from /vol1/backups/cdrouter-backup-2024031213336.

* All data that is currently in /usr/cdrouter-data/ will be PERMANENTLY DELETED.  THIS
  ACTION CANNOT BE UNDONE AND MUST NOT BE INTERRUPTED ONCE STARTED.

Are you sure you want to do this (yes/no)? yes

stopping CDRouter... done.

restoring backup... 123.50 GiB / 226.82 GiB [==========================>-----------------------] 54.45% 60.00 MiB/s 27m43s

When the above command is launched, the CDRouter Restore tool will calculate and display the total size that will be restored and it print a warning that all files in the /usr/cdrouter-data directory will be permanently deleted.

You must answer ‘yes’ in order to proceed with the restore process.

The tool will display statistics as it makes progress. It will display the running total of how much data has been restored, the percent complete, the speed of the network transfer, and the approximate time remaining to complete the restore.

When the CDRouter Restore tool has finished, it will automatically restart the CDRouter web UI.

CDRouter Migrate Tool

The CDRouter Migrate tool can be used when upgrading to an NTA3000 hardware platform from an NTA1000.

In addition to updating your config files with new testvars and removing obsolete ones, The CDRouter Migrate tool will update network interface names of the NTA1000 to match the corresponding interface on the new NTA3000 platform.

Before migration:  testvar lanInterface wifi2-ac2        (NTA1000 name)
After migration:   testvar lanInterface wifi6-ax56       (NTA3000 name)

When upgrading WiFi interface names, there may be more than one NTA3000 interface to choose from. The Migrate tool will use the lanChannel testvar to determine whether to map the NTA1000 name to a 2.4GHz or a 5GHz interface on the NTA3000.

When upgrading the wifi0-acn and wifi1-ax interface names from the NTA1000, the Migrate tool will use the lanChannel testvar to determine which NTA3000 interface to map it to.

• If lanChannel is set to "5GHz" or a specific 5GHz frequency, the name will be mapped to a 5GHz interface.
• If lanChannel is set to "2.4GHz" or a specific 2.4GHz frequency, the name will be mapped to a 2.4GHz interface.
• If lanChannel is set to "auto" or commented out, the Migrate tool will not change the interface name and a warning message will be printed prompting the user to manually update the interface name.

See the table below for a list of all NTA1000 interface names and their corresponding name on the NTA3000 platform.

Note that running the CDRouter Migrate tool will fully reformat the configuration files as it upgrades them. Any custom formatting or comments will be lost in the upgrade process. Please see “Upgrading configuration files” for additional details.

The CDRouter Web UI and API may be used while the CDRouter Migrate tool is running. However, you should avoid running any test packages until the migrate has finished in order to avoid unexpected changes to the config files as they are being upgraded.

/usr/cdrouter/bin/cdrouter-migrate 
WARNING:

cdrouter-migrate is about to migrate 2081 configs to the NTA3000 platform.
Once a config has been migrated, the migration cannot be undone.

To perform a dry run of the migration, use the -dry-run flag.
To skip this prompt in the future, use the -yes flag.

Are you sure you want to continue? (yes/no)? yes
Migrating configs to NTA3000... done.                              

2081 of 2081 configs were migrated successfully

Total time 45m12s

Migration of configs completed

NTA1000 - NTA3000 Interface Mapping Table

CDRouter Clone Tool (discontinued)

The CDRouter Clone tool was a CLI program used to transfer CDRouter configuration and results data when replacing one NTA1000 system with a newer one. This tool has been discontinued and is not compatible with the NTA3000.

When replacing any NTA system or upgrading from an NTA1000 to an NTA3000, we recommend using the CDRouter Backup tool to perform a full backup of the original NTA system, and then running the CDRouter Restore tool to copy data in the backup file onto the new NTA system.

Once the transfer has been completed, the CDRouter Migrate tool can be used to upgrade any config files when upgrading to an NTA3000 system for the first time.

Caveats

Data is automatically stored in /usr/cdrouter-data for all tests performed using CDRouter’s web UI. The backup and restore tools documented in this article operate primarily on the /usr/cdrouter-data directory.

Any tests results created with the cdrouter-cli CLI command must be backed up manually. In addition, any custom tests or other assets or files not stored in /usr/cdrouter-data must also be backed up manually. A list of installed custom testpaths may be found on the Preferences page in CDRouter’s web UI.

Getting Help

If you have any questions about either of these command line tools or run into any problems, please contact QA Cafe Customer Support, and we will be happy to help you.