2.2.9. Update an existing installation¶

This section covers the software update of a Turbo Router appliance.

Prerequisites¶

Note

In Turbo Router version X.Y.Z, digits are referred to as follows:

X = major
Y = minor
Z = maintenance

Update between maintenance versions within the same minor version is supported.
Update between consecutive minor versions is supported.
Update between major versions requires a fresh install.
Update between inconsecutive minor versions requires to update in several steps between consecutive minor versions.
Downgrade is not supported.

Examples:

Update from	To	Supported
3.0.1	3.0.5	Yes
3.0.5	3.1.0	Yes
2.2.6	3.0.0	No; backup your configurations, install from scratch and restore your configurations
3.0.5	3.2.0	No; update to the latest 3.1.x, then from 3.1.x to 3.2.0.
3.0.0	2.2.6	No; install from scratch. Configuration backup/restore is not supported when downgrading.

The rationale for these restrictions is to properly support API deprecation.

Backup existing files¶

If you are updating from Turbo Router 2.x, make sure that you update to the latest 2.x version first. Refer to Turbo Router 2.x documentation.

Before updating to a new revision, ensure that you are not using a deprecated API, at least in the startup configuration:
```
vrouter> validate startup
OK.
```
Note

Any use of deprecated or obsolete API should be fixed. It is advised to also check the saved configurations.
Backup your existing configurations, private keys, certificates and licenses.
```
vrouter> cmd backup export url <backup-url>
OK.
```
Warning

The backup file contains sensitive data, like private keys. Make sure to keep it private.

See also

The command reference for details.

If you are updating from Turbo Router 2.x, move to the installation section. Else, move to the next section.

Update to the new version¶

Import the new image
```
vrouter> cmd system-image import <image-url>
Checking startup configuration compatibility with imported image ...
OK: startup configuration is compatible with version 3.0.0
```
Note

API deprecation notices may be displayed:
- deprecated APIs can safely be fixed after booting with the new version.
- obsolete APIs should be fixed at that step, or the startup configuration will be partially applied. Fix the startup configuration, delete the new image and restart the update procedure.

Reboot on the new image

The new image will be booted automatically on next reboot:

vrouter> cmd system-image list
3.0.0 (default) (current)
3.0.1 (next)

Reboot the appliance:

vrouter> cmd reboot delay 0

Set the new image as the default image

After a successful reboot, you can set the new image as default:
```
vrouter> cmd system-image set-default 3.0.1
```
The old image can be deleted with:
```
vrouter> cmd system-image delete 3.0.0
```
See also

The user guide and command reference for details.

API deprecation¶

When the API changes between Turbo Router versions, the new API coexists with the previous one, which is progressively deprecated, obsoleted and removed, as follows:

GA version	API state
N	API v1 is valid and fully supported.
N + 1	API v2 is introduced; API v1 is deprecated and this is reported at update and when editing the configuration in the CLI. Both APIs are supported; switching to v2 is recommended.
N + 2	API v1 is obsolete. It can still be loaded and displayed in the CLI, but it is ineffective. API v1 is not supported; switching to v2 is required.
N + 3	API v1 is removed and cannot be used.