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 upgrade
command in the TNSR CLI.
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.
See also
Most of this document covers in-place updates. For information on updating by redeploying/reinstalling, see Upgrading by Redeploying TNSR.
Warning
There is no method to upgrade in-place from a CentOS-based TNSR installation to an Ubuntu-based TNSR installation. The only way to migrate to Ubuntu is by backing up, reinstalling, and then restoring the old configuration.
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¶
Updating TNSR in place will upgrade both TNSR and the operating system to the latest available versions without reinstalling from scratch.
Warning
Check Version-Specific Upgrade Notes for specific notes on upgrading from past versions of TNSR software.
Users running TNSR software version 23.11 must read Upgrading from TNSR 23.11 and follow the steps in that section.
Users running TNSR software version 23.06 and prior versions must upgrade using a different procedure, covered in Upgrading from TNSR 23.06 and earlier.
Updates via the TNSR CLI¶
The easiest way to update TNSR is from within the TNSR CLI:
tnsr# package upgrade
That command will download and apply all available updates for TNSR and the operating system. The upgrade output will instruct the administrator to reboot when the TNSR upgrade process is complete.
Note
There will be no output from this command until the process completely finishes or times out, which may take a several minutes for larger upgrades.
Note
Running this command when there is no new version of TNSR software will upgrade base operating system components, including upstream security fixes. In this case, the upgrade script will only prompt to reboot when there is a kernel change.
Example output from a successful upgrade:
tnsr# package upgrade
TNSR is going to upgrade packages. It can take several minutes.
Looking for packages to be upgraded
Getting repository metadata for TNSR 24.02
Removing HWE kernel packages
Executing pre upgrade scripts
Upgrading TNSR to 24.02
Executing post upgrade scripts
TNSR was upgraded to 24.02. Please reboot the system.
Warning
The CLI command may time out before it fully completes all of the required upgrade tasks. When this happens, the command output printed to the CLI will only reflect the portions of the upgrade completed before it timed out.
If this happens, run the package upgrade
command again. If the process
completed, it will detect that and print the final result. If the upgrade
process is still working in the background it will reattach to the existing
session and show its output.
tnsr# package upgrade
TNSR is going to upgrade packages. It can take several minutes.
Previous TNSR upgrade attempt exited with the following result:
TNSR was upgraded to 24.02. Please reboot the system.
Please reboot the system to continue upgrading TNSR.
Do not reboot TNSR until instructed to do so by the upgrade output.
Kernel Changes Require a Mid-Upgrade Reboot¶
In some cases the upgrade process may also need to change the kernel. For example, previous versions of TNSR software have used “HWE” kernels which are no longer necessary.
If this is necessary, the upgrade process will print a message stating that it
changed the kernel and that a reboot is necessary before it can continue. When
this happens, reboot and then run package upgrade
again to complete the
upgrade.
Example output when the kernel changes:
tnsr# package upgrade
TNSR is going to upgrade packages. It can take several minutes.
Previous TNSR upgrade attempt exited with the following result:
System is running HWE kernel, which is not compatible with next TNSR version.
Proper kernel is now configured to be used on next boot. Please reboot the
system immediately and re-run upgrade to finish upgrade process.
Please reboot the system to continue upgrading TNSR.
Reboot the router as directed:
tnsr# configure
tnsr(config)# reboot now
Reboot initiated. Are you sure? [yes/no]
yes
Run package upgrade
again to complete the upgrade:
tnsr# package upgrade
TNSR is going to upgrade packages. It can take several minutes.
Looking for packages to be upgraded
Getting repository metadata for TNSR 24.02
Removing HWE kernel packages
Executing pre upgrade scripts
Upgrading TNSR to 24.02
Executing post upgrade scripts
TNSR was upgraded to 24.02. Please reboot the system.
Updating via the shell¶
TNSR can also be updated from the command line using the tnsr-upgrade
script:
$ sudo tnsr-upgrade
$ sudo reboot
The rest of the procedure is the same as described in Updates via the TNSR CLI with regard to following the directions in the output about when to reboot and if it needs run multiple times.
Version-Specific Upgrade Notes¶
Upgrading from TNSR 23.11¶
TNSR software version 23.11 had a minor issue in package upgrade
which could
cause the command to timeout when run from the TNSR CLI. This problem scenario
is already covered by Updates via the TNSR CLI but there is an alternative
workaround.
The upgrade script can be run from a shell prompt as described in Updating via the shell and when run from the shell, it is not subjected to the TNSR CLI command timeout issue.
Once the system is running TNSR software version 24.02 or later, future upgrades can be performed at the CLI as described in Updates via the TNSR CLI.
Upgrading from TNSR 23.06 and earlier¶
TNSR software versions 23.06 and earlier have a known issue with the package
upgrade
method which can make upgrading problematic.
On systems running these older versions, upgrades must be performed by using
apt
.
From a shell prompt, run the following commands to update and reboot:
$ sudo apt update
$ sudo apt full-upgrade -y
$ sudo reboot
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.
Once the system is running TNSR software version 24.02 or later, future upgrades can be performed at the CLI as described in Updates via the TNSR CLI.
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 ensures 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.