Tip

This is the documentation for the 20.02 version. Looking for the documentation of the latest version? Have a look here.

Updating TNSR¶

Warning

Trial versions of TNSR packages cannot be updated. Reinstall with a full version of TNSR or install a new trial version. The operating system may be updated, but not TNSR.

With a signed client certificate from Netgate in place, TNSR has access to the Netgate software repositories which contain important updates to TNSR. These updates can be retrieved using the package command in the TNSR CLI, or yum in the host OS shell.

Note

Updating TNSR will also update the operating system. Even when there are no TNSR updates available, it is a good practice to periodically perform an update to obtain important operating system updates such as security vulnerability mitigations.

Pre-Upgrade Tasks¶

Before updating TNSR, perform the following tasks:

Make sure the signed certificate is in place (Install the certificate)
Make sure the TNSR instance has working Internet connectivity through the host OS management interface
Take a backup of the running and startup configurations (Configuration Backups)

Updating via the TNSR CLI¶

The easiest way to update TNSR is from within the TNSR CLI itself.

tnsr# package upgrade

That command will download and apply all available updates. Afterward, exit the CLI and start it again.

Note

There will be no output from this command until the process completely finishes, which may take a few minutes for larger updates.

Updating via the shell¶

TNSR can also be updated from the command line using the host OS package management commands, in this case, yum:

$ sudo yum clean all
$ sudo yum clean expire-cache
$ sudo yum -y upgrade

Update Script¶

The following shell script may be used to keep TNSR and CentOS updated. In addition to the updates it also makes a local backup before performing the update.

Download: updatetnsr.sh¶

#!/bin/sh

# Stop existing services
sudo systemctl stop strongswan frr vpp clixon-restconf

# Time to make the backups
mkdir -p ~/tnsr-config-backup
sudo cp -p /var/tnsr/running_db ~/tnsr-config-backup/running_db-`date +%Y%m%d%H%M%S`.xml
sudo cp -p /var/tnsr/startup_db ~/tnsr-config-backup/startup_db-`date +%Y%m%d%H%M%S`.xml

# Update all RPMs
sudo yum clean all
sudo yum clean expire-cache
sudo yum -y upgrade

# Ensure services are stopped, in case some automatically started after update.
sudo systemctl stop strongswan frr vpp clixon-restconf

# Run config database upgrade script
sudo /usr/bin/tnsr-db-update
sudo cp -p /var/tnsr/running_db /var/tnsr/startup_db

# Start services
sudo systemctl start clixon-backend clixon-restconf

Updating the Configuration Database¶

Automatic Configuration Update¶

If TNSR fails to start due to a change in the configuration, use the included configuration database migration utility, /usr/bin/tnsr-db-update, to check for and correct potential problems.

Warning

TNSR must be stopped before attempting to run this script, which modifies the running database at /var/tnsr/running_db.

The /usr/bin/tnsr-db-update script must be run as root either directly or via sudo:

$ sudo /usr/bin/tnsr-db-update

The utility will make a backup of the configuration before making alterations. This backup is placed in /var/lib/tnsr/db-backups/tnsr-<version>/running_db-<timestamp>.

Warning

This utility currently only alters the running configuration database and not the startup database. After running the script and validating its output, copy the running database to the startup database:

$ sudo cp -p /var/tnsr/running_db /var/tnsr/startup_db

If TNSR still will not start after running this utility, then the configuration database may contain errors which were not able to be corrected by the script.

Manual Configuration Update¶

Any errors which could not be corrected by the automatic script must be corrected by hand. Alternately, the configuration databases may be erased and recreated from scratch.

To attempt manual corrections, check the system logs after attempting to start TNSR for information about which configuration entries are causing the failure. View the logs with sudo systemctl status clixon-backend.service, sudo journalctl -xelu clixon-backend.service and sudo journalctl -xe.

A log entry for a configuration problem could look like the following example:

clixon_backend: startup_failsafe: 297: Database error: Startup failed and no
  Failsafe database found, exiting
clixon_backend: <rpc-reply><rpc-error>
  <error-type>application</error-type>
  <error-tag>unknown-element</error-tag><error-info>
  <bad-element>someinvalidtag</bad-element></error-info>
  <error-severity>error</error-severity>
  <error-message>namespace is: urn:ietf:params:xml:ns:netconf:base:1.0</error-message>
  </rpc-error></rpc-reply>

To correct such problems, edit the configuration in /var/tnsr/running_db (e.g. sudo vi /var/tnsr/running_db), erase or adjust the offending tag or configuration section, copy the repaired configuration to /var/tnsr/startup_db, and attempt to start TNSR again. Repeat until no errors are reported and TNSR starts normally.

To erase the configuration database, remove its files from /var/tnsr:

$ sudo rm /var/tnsr/*_db

After removing the configuration and starting TNSR, the TNSR configuration will need to be created again manually from scratch using the CLI or RESTCONF. Open the contents of a configuration backup in a text editor to use as a guide.

Reboot / Update Verification¶

If a TNSR update installed a new kernel or drivers, a reboot of the router is necessary to activate those changes.

Additionally, after performing a TNSR update and updating the configuration, administrators may wish to perform a reboot of the router to ensure it starts up correctly with the expected configuration.

Though not every TNSR update will require a reboot, the best practice is to test that the router performs as expected at startup during an upgrade maintenance window.

Update Troubleshooting¶

If the TNSR CLI method does not work, use the shell method instead.

If either method prints an error referring to a broken package database, recover it as follows:

$ mkdir -p ~/tmp/
$ sudo mv /var/lib/rpm/__db* ~/tmp/
$ sudo rpm --rebuilddb
$ sudo yum clean all

Upgrading by Redeploying TNSR¶

Rather than performing an in-place update of a TNSR installation, administrators may instead choose to deploy a fresh instance of TNSR using the new version. This practice is typical of environments such as cloud providers or virtual machines, but may be performed for ISO installations and others as well.

In those cases, follow this general procedure:

Take a backup of the configuration
Deploy a new instance of TNSR using the installation instructions for the chosen platform
Restore the configuration
Update the configuration (Updating the Configuration Database)

See Configuration Backups for details on saving and restoring configuration backups, and review Updating the Configuration Database for important information about updating the configuration for a new version of TNSR.