This article provides instructions for reverting to a previous major release version of AppGate SDP (e.g., reverting from 5.5 to 5.4 or 5.3), and details the steps to perform if a reversion to a previous version of SDP is required outside of an upgrade, or if a significant amount of time has elapsed since the last upgrade.
NOTE: The SDP reversion methods detailed in this article are not intended for routine use, and should not be performed without engaging AppGate SDP Support.
Prerequisites
Reverting to a different major release version of AppGate SDP requires:
A backup performed before the upgrade to your current version, using the AppGate SDP backup script or a VM snapshot. If you use a VM snapshot, we recommend that you also perform a backup using the AppGate SDP backup script for safety.
An appliance capable of having the backup restored to it.
You must use an appliance running the same version of AppGate SDP from which the backup you are trying to use was performed, or a version that is one (1) version newer. For example, a 5.3 backup can be restored to a 5.4 appliance, however a 5.3 backup cannot be restored to a 5.2 or 5.5 appliance. If you need to restore a backup to an appliance that is more than one version different, you will need to boot the appliance from the previous partition (as long as the backup is from the previously upgraded version) and wipe the appliance (using the cz-config advanced configuration command) before the backup is applied.
When reverting a collective, user Clients must be within two (2) versions of the reverted collective, or they may not be able to connect. For example, if you have 5.5 appliances and you revert to a 5.3 collective, your user’s Clients must be version 5.3, 5.4, or 5.5. If you have version 6.0 clients and 5.5 appliances, and then revert to a 5.3 collective, the 6.0 clients may not work correctly, as they are outside of the tested and supported version compatibility.
Note: Any new data that you have added to the 'new version' of the appliance or changes you have made in the SDP Admin user interface will not be migrated to the previous version when you revert.
Reversion Methods
There are several ways to revert an SDP collective, depending on which backup tools you have available, and the differences in the SDP versions being reverted. The following sections detail instructions for each method.
Reverting a Collective Using Snapshots
To fully revert a collective from a different version using snapshots (e.g.,version 5.5.X to version 5.3.X):
Power down the Gateways and revert them to the snapshot one at a time, ensuring they return to a healthy state.
If the Gateways do not return to a healthy state, ensure that they are using the correct version, and wipe the appliances.
Reseed the appliances once the Controllers have been reverted.
Power down the logforwarders and revert them to the snapshot one at a time, ensuring they return to a healthy state.
If the logforwarders do not return to a healthy state, ensure they are using the correct version, and wipe the appliances.
Reseed the appliances once the Controllers have been reverted.
Power down all of the Controllers and revert them to the snapshot. Note that it is critical that ALL Controllers are powered down before starting to revert any to the snapshot. If you do not revert all of the Controllers at the same time, online Controllers using different versions may attempt to synchronize databases, which will cause problems.
Reseed all appliances that did not properly connect to the Controllers.
Ensure that the appliances are using a compatible version, and that they have been wiped before attempting to reseed them.
NOTE: If you have renewed the appliance certificates since the backup/snapshot was taken, you will need to re-seed those appliances.
Reverting a Collective Using Backup Scripts and New Appliances
To fully revert a collective from a different version using the backup script and deploying new appliances (e.g. version 5.5.X to 5.3.X):
Power down all AppGate appliances.
Deploy new appliances next to all of the powered down appliances.
SSH into the main controller’s replacement appliance, place the appropriate controller backup onto the appliance, place a file containing the backup passphrase on the appliance and use the restore command:
sudo cz-restore --passphrase-file <passphrase filename> <backup filename>
Repeat Step 3 with the other controllers.
After the controllers are in a healthy state, reseed all of the appliances one at a time or similarly restore them using a backup.
Once you have a fully healthy collective, delete all of the old appliance VM’s.
NOTE: This will lose all logs in a logserver appliance if one is configured and the logs were not part of the backup. A logserver appliance is not recommended for productions deployments. If you are using a logserver and wish to keep the logs then you should ensure the logserver logs are also backed up when you performed the backup and use the restore process to restore the logserver as well.
Reverting a Collective Using Backup Scripts and Wiping Appliances
To fully revert a collective from a different version using the backup script and the wipe command (e.g. version 5.5.X to 5.3.X):
Remove the appliance role from all non-controller appliances.
Note:This will lose all logs in a logserver appliance if one is configured. A logserver appliance is not recommended for productions deployments. If you are using a logserver and wish to keep the logs then you should ensure the logserver logs are also backed up when you performed the backup.
Revert the non-controller appliance’s partitions:
sudo cz-config switch-partition --reboot
Wipe the non-controller appliances:
sudo cz-config wipe-appliance --force
Take the collective to a single controller state by removing the controller role from each controller one at a time. Ensure the other controllers return to a healthy state before continuing.
Revert the partitions for the appliances that were previously controllers:
sudo cz-config switch-partition --reboot
Wipe the partitions for the appliances that were previously controllers:
sudo cz-config wipe-appliance --force
Revert the remaining controller’s partition:
sudo cz-config switch-partition --reboot
Wipe the remaining controller appliance:
sudo cz-config wipe-appliance --force
SSH into the appliance, and place the appropriate controller backup onto the appliance.
Place a file containing the backup passphrase on the appliance and use the restore command:
sudo cz-restore --passphrase-file <passphrase filename> <backup filename>
After the controller is in a healthy state reseed all of the appliances one at a time starting with the controllers.
Reverting a Point Release
Reverting a point release is easier to revert due to the fact that the controller version can be “older” than the gateways (e.g. version for example, 5.5.4 to 5.5.2):
Take the collective to a single controller state.
Remove the controller role from each controller one at a time. Ensure the other controllers return to a healthy state before continuing.
Revert the previous controller appliance partition.
sudo cz-config switch-partition --reboot
Wipe the previous controller appliance.
sudo cz-config wipe-appliance --force
SSH into one of the wiped controller appliances.
Place the appropriate controller backup onto the appliance and use the restore command:
sudo cz-restore --passphrase <pass> <filename>
Remove the controller role from the controller still on the undesirable version.
Revert the remaining undesirable controller appliance partition.
sudo cz-config switch-partition --reboot
Wipe the remaining undesirable controller appliance.
sudo cz-config wipe-appliance --force
Reseed the rest of the controllers.
If the issue that caused the reversion requires the other appliances to be reverted also then remove the role from those appliances, switch the appliance partitions, and reseed the appliances as outlined below:
Remove the appliance role from all non-controller appliances.
NOTE: This will lose all logs in a logserver appliance if one is configured. A logserver appliance is not recommended for productions deployments. If you are using a logserver and wish to keep the logs then you should ensure the logserver logs are also backed up when you performed the backup.
Revert the appliance’s partitions.
sudo cz-config switch-partition --reboot
Wipe the appliances.
sudo cz-config wipe-appliance --force
Reseed the appliances.
Reverting a Collective by Switching the Partition
To fully revert a collective by switching the partition if, for example, there has been a problem with the upgrade process, you should follow the outlined steps below. These steps are also outlined in the Reverting Appliances section of the Admin Guide found here. Be sure to check the Admin Guide to ensure no steps have changed.
NOTE:
Switch Partitions is not a viable option to revert Controllers you are upgrading to version 6.x or later. Using the above snapshot or backup techniques are the best practice to revert a Controller to an older version in this scenario. These steps are valid to revert other Appliance Types including Gateways, Log Servers, etc..
These steps should not be done if any significant time has elapsed since an upgrade completed successfully. If the upgrade completely successfully then AppGate should be contacted so the reason for the reversion can be discussed.
Option 1 (temporary change):
Reboot the appliance. The GRUB boot menu will list the new and previous versions of the appliance. The new version will be set as the default. Select the other version from the boot menu if required.
NOTE: This will not be a permanent change. The next time you reboot, the default version of the appliance will be started.
Option 2 (change default version):
To check which partition is currently running – type: cat /mnt/state/volume-number, this will return the partition number currently running (eg. 2).
To change the default partition to the other partition type: cz-config switch-partition --reboot, this changes the boot menu to make the original partition the default version.
NOTE: Any new data that you have added to the 'new version' of the appliance will not be migrated to the previous version when you revert.
You should perform the steps in the opposite order from the upgrade. At each step you should ensure that each appliance reboots and returns to a healthy state at the previous version.
Revert each Portal.
Revert each Connector.
Revert each Gateway.
Revert the LogServer / LogForwarders.
Refer to one of the above methods for reverting a Controller.
Using the Dashboard, confirm the entire system is at the previous version and is functioning normally.
Validation
The collective is on the previous version and users are able to log in without issue.