2.2.11. Update an existing installation¶
This section covers the software update of a Virtual Service Router appliance.
Prerequisites¶
Note
In Virtual Service 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.
Warning
Starting with 3.6.8, upgrade to VSR 3.7 is only possible to 3.7.2 or above.
Backup existing files¶
If you are updating from Virtual Service Router 2.x, make sure that you update to the latest 2.x version first. Refer to Virtual Service 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:
vsr> 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 and certificates.
vsr> 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 Virtual Service Router 2.x, move to the installation section. Else, move to the next section.
Update to the new version¶
Import the new image
vsr> 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:
vsr> cmd system-image list 3.0.0 (default) (current) 3.0.1 (next)
Reboot the appliance:
vsr> cmd reboot delay 0
Set the new image as the default image
After a successful reboot, you can set the new image as default:
vsr> cmd system-image set-default 3.0.1
The old image can be deleted with:
vsr> cmd system-image delete 3.0.0
Warning
When updating from VSR 3.7, online licenses must be re-validated by the license server at least one time after the update.
See also
The user guide and command reference for details.
API deprecation¶
When the API changes between Virtual Service 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. |