--- title: "Upgrading appliances" slug: "upgrading-appliances-v7-0" description: "Upgrade your AppGate ZTNA appliances seamlessly with our guide, covering version compatibility, backup steps, and rollback procedures for smooth transitions." tags: ["Upgrading Appliances", "Reverting Appliances", "sdpctl", "Appliances"] updated: 2026-06-08T19:33:52Z published: 2026-06-08T19:33:52Z canonical: "support.appgate.com/upgrading-appliances-v7-0" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.appgate.com/llms.txt > Use this file to discover all available pages before exploring further. # Upgrading appliances This section describes the process for upgrading AppGate ZTNA appliances and reverting to the previous version if required. AppGate ZTNA supports upgrades from a maximum of two versions back. For example, you can upgrade to version 6.2 from version 6.0 or 6.1. To upgrade from version 6.1 to version 6.5, you must first upgrade to version 6.3, then upgrade from 6.3 to 6.5. Use [sdpctl](https://github.com/appgate/sdpctl) to upgrade when a new AppGate ZTNA release is available. sdpctl checks for the minimum supported upgrade version and identifies compatibility issues. Back up your Controller before allowing the upgrade to proceed. --- ## Before you start Before starting an upgrade, complete the following steps: 1. Read the release notes for the version you are upgrading to, including any skipped versions. If any feature deprecations affect your upgrade, address them before proceeding. 2. Note the hostname of your primary Controller. You will connect to its admin interface and may need to reference this Controller if you revert the upgrade. 3. Back up your Controller and move the backup file off the appliance. See [Backup and restore](/v1/docs/backup-and-restore-v7-0) for more information. > [!NOTE] > NOTE > > If you created custom folders, back up those folders and their contents off the appliance before proceeding. 1. Download the appliance upgrade file from the [AppGate Support](https://www.appgate.com/support) page. Do not decompress the zip file before starting. If your operating system decompresses the file automatically, use `curl`. Open a terminal that supports `curl` and enter the following: ```plaintext curl -u username:password https://bin.appgate-sdp.com/x.y/appliance/Appgate-SDP-x.y.z.img.zip -o appgate-sdp-x.y.z.img.zip -k ``` 1. Place the file in one of the following locations: - On the local machine running `sdpctl`. The Controller uploads the file. - On a web server the Controller can access. You can download the file directly to the web server from the [AppGate Support](https://www.appgate.com/support) page 1. Verify that you have access to all virtual machines or cloud instances, including iRMC access for hardware appliances. 2. Check for customizations installed on the appliances. Stop all customizations before the upgrade and restart them afterward. > [!NOTE] > **NOTE** > > Temporary customizations provided to address an issue that is fixed in the version you are upgrading to are not tested against the new version and may be incompatible. If you have a temporary customization, remove it and reboot the appliance before starting the upgrade. --- ## Upgrading a Collective using sdpctl `sdpctl` performs an orchestrated upgrade of all appliances in your Collective. You can use `sdpctl` to upgrade an entire Collective or a partially upgraded Collective, upgrading only the appliances that require it. `sdpctl` upgrades in two phases: - **Prepare.** Distributes and verifies the image to ensure the files are not damaged. - **Complete.** Completes the upgrade. > [!NOTE] > NOTE > > `sdpctl` automatically determines whether the upgrade is a patch upgrade (for example, 6.1.1 to 6.1.2) based on the current and target versions. AppGate ZTNA upgrades appliance functions in a defined order. Gateways, Connectors, LogForwarders, and Metrics Aggregators serving the same Site are not upgraded at the same time. > [!NOTE] > **NOTE** > > Do not perform simultaneous appliance upgrades using the host on a Controller in a large Collective. Instructing many appliances to simultaneously request a download of a large file (under 1 GB) places excessive load on the Controller. Use the `--throttle` option to prevent overloading the download server and to avoid `sdpctl` timing out. ### HA Controllers For **patch upgrades**, Controllers remain fully active during the upgrade to maintain high availability (HA). Controllers are upgraded one at a time, starting with the primary Controller, so only one appliance is out of service at a time. For **major upgrades**, such as 6.1 to 6.3, the process is different. The primary Controller puts all other Controllers into maintenance mode. In maintenance mode, Controllers continue to service client requests but do not accept admin or API requests. After the primary Controller completes its upgrade, it handles both client and admin or API requests, and the remaining Controllers begin upgrading. Schedule upgrades during quiet periods. The Collective must complete any outstanding database synchronization before the remaining Controllers upgrade. If problems are detected, the primary Controller can perform an automated rollback. During the upgrade, the Collective performs a database migration. While the migration is in progress, no Controllers accept client connections. This process takes under a minute. After this point, there is no automated rollback capability if the upgrade fails. As each Controller completes its upgrade, it exits maintenance mode and becomes available to handle client and admin or API requests. If a subsequent Controller upgrade fails or times out, you must decide whether to proceed with the upgrade or revert. AppGate recommends proceeding at this point. See the [Controller maintenance and troubleshooting](/v1/docs/controller-maintenance-and-troubleshooting-v7-0) section for guidance on recovering from this situation. Advanced recovery scenarios are also available, but these procedures can compound the problem if performed without training. Contact AppGate Support before attempting them. You can also manually roll back an HA Controller. Follow the steps that apply to your situation: - **Single Controller:** Follow the [Reverting appliances](/v1/docs/upgrading-appliances-v7-0#reverting-appliances) instructions below. - **HA Controllers reduced to a single Controller before upgrade:** Follow the [Reverting appliances](/v1/docs/upgrading-appliances-v7-0#reverting-appliances) instructions below, then SSH to the Controller and enter: `cz-config bdr force-single-controller-ready` - **Multiple upgraded HA Controllers:** Restore from backup using the snapshots and backups taken before the upgrade. If the system configuration has not changed, you should be able to restore a failed upgrade using these backups. To manually roll back an HA Controller outside of the scenarios above, complete the following steps: 1. On all upgraded appliances, run the following command. All appliances revert to the earlier version. You must still restore Controllers from backup due to database migrations. ```plaintext   sudo cz-config switch-partition ``` > [!CAUTION] > WARNING > > Do not use `switch-partition` followed by a reboot to roll back HA Controllers 1. On all Controllers except the primary Controller, run the following command to remove the additional Controllers: ```plaintext   sudo cz-config bdr force-appliance-ready ``` 1. On the primary Controller, run the following command: ```plaintext   sudo cz-config restore /path/to/backup/file ``` > [!NOTE] > NOTE > > If the Collective has a LogServer on a separate appliance, restore it from its backup as well. 1. In the admin UI, enable Controllers one at a time, waiting for each to reach a healthy state before enabling the next. To manually re-enable Controllers if the upgrade does not complete normally: - If the primary Controller upgrade fails, additional Controllers may remain in maintenance mode. If the `cz-configd` daemon is accepting events (normal state), SSH to the Controller and enter the following to disable maintenance mode: ```plaintext  sudo cz-config set -j controller/maintenance false ``` - To bring an appliance back online if it appears to remain offline during or after the upgrade, restart the `cz-configd` daemon: ```plaintext  sudo service cz-configd restart ``` --- ## Reverting appliances > [!NOTE] > NOTE > > LogServers with OpenSearch cannot be reverted. To revert an appliance to the previous software version: 1. Confirm which version the appliance is running. The system may have automatically reverted to the previous version. To confirm, SSH to the appliance and enter: ```plaintext cat /usr/share/cz-image/version ``` If the upgrade version is running and you want to revert, continue to step 2. 1. Revert to the previous version using one of the following options: > [!NOTE] > NOTE > > If you are reverting a Controller, see [HA Controllers](/v1/docs/upgrading-appliances-v7-0#ha-controllers) above. **Option 1 — Temporary revert:** Reboot the appliance. The GRUB boot menu lists both the new and previous versions. The new version is set as the default. Select the previous version from the boot menu. > [!NOTE] > NOTE > > This change is not permanent. The next reboot starts the default version. **Option 2 — Permanent revert:** To check which partition is currently running, enter: ```plaintext   cat /mnt/state/volume-number ``` To change the default partition to the previous version, enter: ```plaintext   cz-config switch-partition ``` This updates the boot menu to make the previous partition the default. > [!NOTE] > NOTE > > Data added in the new version is not migrated to the previous version when you revert. ### Reverting an entire Collective To revert an entire Collective, perform the steps in the reverse order of the upgrade. At each step, verify that the appliance reboots and returns to a healthy state on the previous version: 1. Revert each Portal. 2. Revert each Connector. 3. Revert each Gateway. 4. Revert the LogForwarders and Metrics Aggregators. 5. Revert the Controllers. See [HA Controllers](/v1/docs/upgrading-appliances-v7-0#ha-controllers) for more information. If you have more than one Controller, wait for each to return to a healthy state before proceeding to the next. If you need to restore the Controller function to any former Controllers, verify that all other Controllers are in a healthy state before proceeding. After reverting, use the dashboard to confirm that the entire system is running the previous version and functioning normally. --- ## Confirming the version number After an upgrade or revert, confirm the appliance version number using one of the following methods. #### Terminal window: Sign in to the terminal. The version number appears in the welcome message: ```plaintext Authorized uses only. All activity may be monitored and reported. Last login: Tue Mar 30 14:23:44 2021 Welcome to Appgate SDP (GNU/Linux 5.4.0-64-generic x86_64) appgate 5.3.2-23587-release (image2) Hint: run 'sudo cz-setup' for appliance management. ``` #### Admin UI: Sign in to the admin UI and check the version number from the dashboard. ![Overview of appliances health status, showing all appliances and their version numbers.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/ag61-dash_appliances.png?sv=2026-02-06&spr=https&st=2026-11-21T21%3A49%3A42Z&se=2026-11-21T22%3A49%3A42Z&sr=b&sp=r&sig=klc4UXiqijY8BL21JxE0EJ3TE%2B6%2BWVnj0kSdLOe94rw%3D)