Tip

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

Updating 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 in the host OS shell.

Note

Updating TNSR also updates 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:

Read through the Netgate TNSR Releases release notes for the new version to identify relevant changes in behavior which may require special actions before or after the upgrade
Make sure the signed certificate is in place (Install the certificate)
Check the ownership and permissions of the update certificate. The files must by owned by the _apt user.

See Certificate File Permissions for details.
Make sure the TNSR instance has working Internet connectivity
Have installation media ready for the new version of TNSR software. Problems during an in-place update may require reinstallation of TNSR software.
Take a backup of the running and startup configurations, plus other important files such as the signed certificate and keys (Configuration Backups)

Save a configuration history version, if enabled:

tnsr# configure
tnsr(config)# configuration history version save before-upgrade-xx.yy

Replace xx.yy with the new TNSR version.

If TNSR is running as a virtual machine, take a snapshot

Tip

Though it is optional, best practices for updating include a pre-upgrade reboot. This reboot ensures that the hardware and installation are functional before attempting the upgrade. This can help identify potential hardware and other issues, such as storage failures, so they do not present themselves unexpectedly during the upgrade.

Updating TNSR In-place (Different base OS version)¶

During some upgrades, such as to TNSR 22.10, the base operating system version is updated to a newer version from upstream. Usually due to the base operating system moving to a new upstream LTS release. For example, from Ubuntu 20.04 LTS to Ubuntu 22.04 LTS.

These upgrades must be performed in a different way than typical upgrades where only TNSR is updated and the base OS version stays the same.

Update Current Base¶

The first step is to update the current base OS and packages and reboot to ensure the base is ready to upgrade further.

From a shell prompt, run the following commands to update and reboot:

$ sudo apt update
$ sudo apt upgrade -y
$ sudo reboot

Upgrade to new Base¶

The following shell script will adjust the TNSR distribution source files and adjust the operating system (Ubuntu) to pull in the new versions of each.

Tip

The safest place to run this upgrade is from the system console, not SSH.

Download: update-tnsr-newbase.sh¶

#!/bin/bash

set -e

. /etc/os-release

if [ "${VERSION_CODENAME}" != "focal" ]; then
	echo "ERROR: This script is designed to run on Ubuntu focal (20.04)" >&2
	exit 1
fi

if [ $(id -u) != 0 ]; then
	echo "ERROR: This script must run as root" >&2
	exit 1
fi

if ! which do-release-upgrade >/dev/null 2>&1; then
	echo "ERROR: do-release-upgrade not found.  Please install ubuntu-release-upgrader-core" >&2
	exit 1
fi

flavors="aws azure hw iso kvm next vmware"

unset tnsr_config_flavor
for flavor in ${flavors}; do
	if dpkg -s tnsr-config-${flavor} >/dev/null 2>&1; then
		tnsr_config_flavor=${flavor}
		break
	fi
done

if [ -z "${tnsr_config_flavor}" ]; then
	echo "ERROR: Unable to identify installed tnsr-config flavor" >&2
	exit 1
fi

apt_config="/etc/apt/sources.list.d/tnsr-${tnsr_config_flavor}.list"

if [ ! -f ${apt_config} ]; then
	echo "ERROR: tnsr-config source list (${apt_config}) not found" >&2
	exit 1
fi

if [ -f /var/run/reboot-required.pkgs ]; then
	if [ $(cat /var/run/reboot-required.pkgs | wc -l) -gt 0 ]; then
		echo "You have not rebooted after updating.  Do it now and try again." >&2
		exit 1
	fi
fi

apt-get update
upgradable=$(apt list --upgradable 2>/dev/null | tail -n +2 | wc -l)

if [ ${upgradable} -gt 0 ]; then
	echo "Please install all available updates on current system and try again after that" >&2
	exit 1
fi

for f in /etc/apt/sources.list.d/*.list; do
	if [ "${f}" = "${apt_config}" ]; then
		cp ${f} ${f}.bak
		sed -i -e 's/20\.04/22.04/g; s/focal/22.04/g' ${apt_config}
	else
		mv ${f} ${f}.disabled
	fi
done

dpkg -P --force-all netgate-libyang

if dpkg -l | grep -q netgate-libyang; then
	  echo "ERROR: netgate-libyang was not removed" >&2
	exit 1
fi

echo 'DPkg::options { "--force-confdef"; "--force-confold"; }' > /etc/apt/apt.conf.d/tnsr-upgrade

do-release-upgrade -f DistUpgradeViewNonInteractive --allow-third-party -m server

rm -f /etc/apt/apt.conf.d/tnsr-upgrade

Place that file in the shell of the user on TNSR who will run the upgrade, then from a shell prompt, run the following commands to perform the remainder of the upgrade:

Warning

The upgrade script disables third party APT list files by renaming them with .disabled during this process.

$ sudo apt install -y ubuntu-release-upgrader-core
$ sudo bash update-tnsr-newbase.sh

After the upgrade completes, reboot the router and it will start up using the new base OS and new version of TNSR.

Note

The upgrade process may prompt to replace existing configuration files for TNSR service daemons such as Kea, VPP, and others. These files are managed by TNSR itself, and TNSR will overwrite them as needed. If prompted, the best practice is to answer N to keep the existing configuration files. Either way, once TNSR is restarted it will replace them with its own configuration data.

Note

To re-enable third party APT sources after performing the upgrade, rename the files to remove .disabled from the filename, then edit the files and update the URLs inside with jammy sources instead of focal.

Updating TNSR In-place (Same base OS version)¶

These methods may be used to upgrade to later versions of TNSR as well as to obtain regular updates for the operating system.

Note

This only updates TNSR and the current operating system version, it cannot change to a different operating system base, including a different major base operating system version.

Updates 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:

Updating Ubuntu¶

$ sudo apt update
$ sudo apt full-upgrade -y

Note

The upgrade process may prompt to replace existing configuration files for TNSR service daemons such as Kea, VPP, and others. These files are managed by TNSR itself, and TNSR will overwrite them as needed. If prompted, the best practice is to answer N to keep the existing configuration files. Either way, once TNSR is restarted it will replace them with its own configuration data.

Update Script¶

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

Download: update-tnsr.sh¶

#!/bin/sh

# 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

# Check OS type to determine upgrade method
. /etc/os-release

case "${ID}" in
ubuntu)
	# Update via APT
	echo "Upgrading TNSR on Ubuntu"
	sudo apt update
	sudo apt full-upgrade -y
	;;
*)
	echo "Unrecognized Operating System"
	exit 1
	;;
esac

# Start services
sudo tnsrctl restart

Post-Upgrade Reboot¶

TNSR upgrades include kernel updates, driver updates, and other operating system component updates. As such, the best practice is to reboot after upgrading these to ensure the device is running the proper kernel and is using a consistent set of updated system components.

The reboot procedure is covered in Rebooting the Router.

Updating the Configuration Database¶

Automatic Configuration Update¶

TNSR has its own automatic configuration upgrade procedures which accommodate changes made to the configuration database structure between versions.

Warning

The TNSR configuration upgrade only alters the running configuration database and not the startup database. After starting TNSR the first time post-upgrade, validate the running configuration. If the running configuration is OK, copy it to the startup configuration:

tnsr# config
tnsr(config)# configuration copy running startup

Manual Configuration Update¶

Any errors which could not be corrected by the automatic configuration upgrade process 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, stop TNSR, 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.

Additional Reboot / Update Verification¶

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.

This practice ensurs that the router performs as expected at startup during an upgrade maintenance window.

Once the upgrade has been validated as working, create a new configuration history version, if enabled:

tnsr# configure
tnsr(config)# configuration history version save after-upgrade-xx.yy

Replace xx.yy with the new TNSR version.

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 and other important files (e.g. PKI data)
Deploy a new instance of TNSR using the installation instructions for the chosen platform
Restore the configuration and other files
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.