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.

  1. 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.

  2. 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

  1. 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.

  2. 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
    
  3. 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.