NOTE
If a release does not specify Appliance or Client, then it relates to both.
Before upgrading
Consider the following before performing an upgrade:
Get the appliance upgrade file from the AppGate support page and place the file where sdpctl can use it: on your local PC or on a web server the Controller can access.
Read the Known Issues related to the release.
Refer to the latest recommendations for instance sizing.
Check compatibility information for your operating system and hosting environments on the software download page for the release.
Check that any customizations you have installed on the appliances do not address issues that have been fixed in the new version. Temporary customizations should be removed and the system rebooted before starting an upgrade.
Create a backup of the current appliance and move the backup file off the device. See Backup and restore for information on how to create a backup.
Make a note of the primary Controller that sdpctl is using. You will need to know which Controller initiated the upgrade if you need to roll back.
Appgate SDP Compatibility
Appliance compatibility is tested for a maximum of two versions back, so a 6.5 Controller will work with 6.3 Gateways.
Appgate SDP Client versions should be kept within two versions of Appgate SDP appliances. For example, when using 6.3 appliances, SDP Clients must be on a version from 6.1 through 6.5.
Upgrading Between Versions
Appgate SDP appliance upgrades are allowed from a maximum of two versions back. For example, an upgrade from 5.2 to 5.4 is permissible, but an upgrade from 5.1 to 5.4 is not. Customers running Appgate SDP 5.1 would have to upgrade to 5.2 or 5.3 before then upgrading to 5.4. However there are a couple of special cases:
To upgrade from v5 to v6 you must always go through the v5.5 to v6.0 upgrade process (no two version jumps allowed).
To upgrade to v6.2 you must be on at least v6.0.1 (6.0.0 will not work).
Downloads
Supported SDP installers and upgrade files | |
Client software and Client compatibility information | |
sdpctl, API specs, k8s operator, Terraform provider, Cloud marketplace |
Upgrading Appgate SDP with sdpctl
To upgrade Appgate SDP, use the latest release of sdpctl available in Github. sdpctl is available for all the main OS platforms.
NOTE
It is critical to take a snapshot or backup of your Controller prior to upgrading. If the upgrade fails before the first Controller is configured and working, then you can use the switch partitions option to revert the upgrade.
If the first Controller is working and something fails when upgrading the other Controllers, the switch partitions option cannot be used as this will break the one working Controller. In this situation the only way to revert is to restore from backup.
sdpctl performs an orchestrated upgrade of all appliances. sdpctl has two phases: the prepare phase, and the complete phase which is the upgrade itself. The prepare phase performs distribution and verification of the image to avoid damaged files being used.
For more detailed information on upgrading with sdpctl, see the Reference Guide.
For more details on upgrading appliances, upgrading HA controllers, and backup/restoration, see the Admin Guide.
Prepare phase
The prepare phase should be run ahead of time, because in this phase it will:
run a deprecation check and explain why an upgrade may not be able to continue.
distribute all files and perform a verification on them.
set the status of the appliance as ready to upgrade if no issues have been found.
not disturb a running Collective or attempt to perform the actual upgrade.
Once any issues discovered during the prepare phase are fixed, re-run the prepare phase to ensure you are ready to upgrade.
Complete phase
You will now run sdpctl to upgrade the first Controller. It will roll back automatically if it experiences any database migration errors.
After the first Controller migration, the new database schema will be synchronized with additional Controllers. The remaining Controllers are then upgraded.
NOTE
Because of the mixed schemata, if an upgrade fails on the remaining Controllers, there is no way to automatically roll back. To revert the upgrade at this point, you must go back to a single Controller and re-enable additional Controllers. Refer to the Admin Guide for more details.
The remaining appliances are then upgraded in a pre-ordained order that is defined by AppGate but at a rate that can be defined in sdpctl.
If an appliance goes offline during the upgrade process, it can be brought back online by restarting the cz-config daemon with the command sudo service cz-configd restart
NOTE
AppGate recommends testing all upgrades in a development environment to verify that upgrades are successful and don't cause integration problems with third-party solutions or local client tools.
Version specific upgrade issues
Upgrading to SDP version 6.5.x
During the upgrade of the first Controller there will be a 30-60 second window in which the Controller(s) does not accept new Client connections. This will be perceived by the user as a delay in the connection. Token renewals are not affected.
You need to be on v6.3.0 or later to perform this upgrade.
Environments utilizing Portal Appliances should upgrade to 6.5.1 or later. See Known issues.
Upgrade to 6.5.0 from 6.4.7 or later does not work. Appliances running 6.4.6 or later will need to upgrade to 6.5.1 or later.
Gateway will temporarily auto-suspend accepting new sessions when memory usage, number of users' sessions or the event queue reach certain thresholds. These thresholds can be found in the "Gateway Failover when it is suspended" section of the High Availability [HA] page in the admin guide. Check the Appliance utilization before upgrading to avoid hitting those thresholds.
Admin UI may behave oddly during upgrades. This is due to the new containerized Admin UI, and will be improved in future releases.
It is not possible to run Appliances on ESX7.0.0. This is due to a bug that is fixed in ESX7.0.1. Please upgrade to the latest version available.
Gateways will download geo location data from https://bin.appgate-sdp.com (preferred) in addition to https://updates.maxmind.com. Both need to be allowed in the firewall.
Gateway stateful failover will only work for 6.4.4, 6.5.0 or later Clients due to a bug fix in the Gateway.
Auto-scaling Gateways with customizations now require the --enable-customization flag to be set.
Feature deletions/deprecations
Removed
Discovered Apps feature and its APIs (Application Discovery replaces it).
Hourly audit log generation for app discoveries (event_type: discovered_apps_hourly).
The dnsDomains in /admin/appliances API endpoint.
The appliance legacy setting for System DNS Search Domains.
Deprecated
The risk model/matrix for configuring access and the corresponding APIs. Risk scores can still be used directly.
The domain:// scheme to define hosts. Instead glob patterns are introduced. "domain://company.com" is the equivalent of "*.company.com".
Site Short Name.
Site - default TTL for lookups is deprecated for both DNS resolver and DNS forwarder.
cz-restore (use cz-config restore).
Various APIs under /admin/stats have the following fields deprecated: name, creationDate and refreshInterval.
API version 19 is deprecated and has only Qualified Support.
Known issues
Security
Under certain corner case conditions, multiple users may be assigned the same session identifier, potentially allowing a guest user to gain visibility to a logged-in user's Portal Client user interface. Fixed in 6.5.1.
Controller
The HTTP header size limit in the Controller means that only about 500 Gateways can be supported in a Collective. Fixed in 6.6.0.
Authentication
It is not possible to use FIDO2 devices for users with the same username in two different Identity Providers. Fixed in 6.5.1.
LDAP error “cannot connect to the server: Network is unreachable” happens if the LDAP server DNS name resolves to both ipv4 and ipv6 on an ipv6 only appliance.
Loosing connectivity to LDAP certificate server can make the Controller unresponsive under high load. Fixed in 6.5.3.
Gateway
URL access (HTTP up) does not support NTLM authentication.
DTLS tunneling will not work when + control message header is > 16KB.
Applying configuration can fail on Gateways under heavy load. Fixed in 6.5.4.
Name resolving
When more than 1 DNS resolver resolve a hostname and one of them returns error, the error takes precedence and no IP Rules/Routes are created for those IPs. Fixed in 6.5.1.
When a resolver response contains partial errors the resolved IPs are ignored. Fixed in 6.5.1.
Appliance
Running cz-config collect-logs on the Appliance is failing. Fixed in 6.5.2.
Application Discovery
Public IPs are not discovered by Application Discovery. This is intentional in order to limit the number of discovered apps and will be enabled in a later version.
Sometimes the Application Discovery page has to be manually reloaded to get the data after running the troubleshooting analysis. Fixed in 6.5.2.
Opensearch
Most of the saved searches (e.g. "Audit logs") ends up refreshing the content constantly. Saving the search and refreshing the page solves the problem. Fixed in 6.5.3.
Portal
Portal fails to inject the JavaScript file that keeps the session alive, to the visited web page. This makes the session timeout after 5 minutes unless a Portal tab is kept open. Fixed in 6.5.1.
Upstream verification fails for HTTPS endpoints using Let’s Encrypt issued certificates.
Metrics
Prometheus metrics apn_audit_logs and apn_audit_events are not being collected. Fixed in 6.5.1.
Client
During client startup, integrity checks are performed to ensure the application has not been tampered with. This is done by verifying files against our digital signature. These checks also included validation against revocation lists, requiring communication with external servers. When starting the 6.5.3 client, a user may encounter a
Warn : Failed to start service "Appgate SDP Client Service" with error code "1053"error due to the revocation checks. Fixed in 6.5.4.Push MFA is broken. Fixed in 6.5.1.
Windows
Auto-update support for SSO clients no longer works as intended so it has been disabled. This feature will be removed in a future release.
Client driver service crashes on Windows server with DC role. Fixed in 6.5.2.
macOS
When macOS FileVault is enabled, the headless client will not be started on boot by the operating system until a user who has permission to decrypt the drive logs in. This is a limitation in macOS.
Linux
In the new DNS Policy configuration, you can add multiple match-domain DNS servers. Only the first will be used, all others are ignored. Fixed in 6.6.0.
Fedora 41 is not officially supported. Due to changes in the operating system, client profiles will be disappear when upgrading the operating system and auto update downloads will fail. Seems to be fixed in later versions of Fedora 41.
iOS
Memory constraints in iOS mean that the number of Sites and Entitlements should be kept low (i.e., four Sites with average Entitlements).
Client sometimes crashes on iOS version 18.3 or earlier due to a bug in iOS. Please upgrade to iOS 18.4 or later.