Version 6.7.x

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 ZTNA Compatibility

Appliance compatibility is tested for a maximum of two versions back, so a 6.7 Controller will work with 6.5 Gateways.

AppGate ZTNA client versions should be kept within two versions of AppGate ZTNA appliances. For example, when using 6.5 appliances, clients must be on a version from 6.3 through 6.7.

Upgrading Between Versions

AppGate ZTNA appliance upgrades are allowed from a maximum of two versions back. For example, an upgrade from 6.5 to 6.7 is permissible, but an upgrade from 6.4 to 6.7 is not. Customers running AppGate ZTNA 6.4 would have to upgrade to 6.5 or 6.6 before then upgrading to 6.7.

Downloads

Upgrading AppGate ZTNA with sdpctl

To upgrade AppGate ZTNA, 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, run the prepare phase again 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 version 6.7.x

• Device claim script execution in 6.7 clients requires the inclusion of the profile DNS name in the license file. Upgrading to 6.7 Controllers requires that this license file is already uploaded. Please contact AppGate Support to get the new license file.

• The Appliance Ubuntu version is bumped to Ubuntu 24.04 and chrony replaces ntpq. Make sure that any customization relying on operating system resources (like a specific Python version) is updated and verified to be working before upgrading the Appliances.

• There is a known issue when upgrading to 6.7 from 6.5.x versions of script integrations breaking due to a forced change to their format. To remedy this:

  • If you have already upgraded, navigate to System > Secrets.

  • Note the new names of all secrets. They will all be uppercase with underscores.

  • Search through your scripts for %SECRET:` and update each reference to match the new secret name.

• 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.5.0 or later to perform this upgrade.

• The 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.

• The 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 geolocation data from https://bin.appgate-sdp.com (preferred) in addition to https://updates.maxmind.com. Both need to be allowed in the firewall.

• Autoscaling Gateways with customizations now requires the --enable-customization flag to be set.

Feature Deletions and Deprecations

Removed

• Removed legacy apn_audit_event_log_stat metric.

• 1.3.6.1.4.1.7607.1.1.37.1 APPGATE-MIB::appgate.sdp.sdpApn.apnAudit.apnAuditEventLogStats has been removed from the MIB.

Deprecated

Support for the following has been deprecated and will be removed in an upcoming release:

• IdP DNS settings. A migration guide is available.

• TLSv1.2 and TLSv23.

• DTLS (replaced by QUIC).

• Elasticsearch 6 on the LogForwarder.

• Legacy syntax for resolver resource names. SDPCTL can be used to convert to the new common JSON syntax.

• The following fields from their respective APIs:

  • redHat8 in /admin/auto-update-settings

  • blockLocalDNSRequests in /admin/identity-providers

  • vpn.dtls in /admin/sites

• The risk model/matrix for configuring access and the corresponding APIs. Risk scores can still be used directly.

• cz-restore (use cz-config restore).

• API version 21.

• Prometheus metric ctr_client_sign_in_with_mfa. It is now a label on ctr_client_authentication.

Known Issues

NAT traversal

• Only 1000 concurrent relay sessions are possible for each Connection Broker.

• To change the Connection Broker STUN port in the Broker section of the Appliance, you need to also change the TLS Port under System TLS Connection.

Secrets Management

• A change introduced in 6.6.0 caused script integrations to break by an unintended forced change to secrets included in scripts. See the steps in the Upgrading to version 6.7.x section to fix your scripts after you upgrade.

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.

Authentication

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

Traffic tunneling

• URL access (HTTP up) does not support NTLM authentication.

• DTLS tunneling (deprecated) will not work when entitlements + control message header is > 16KB.

Admin UI

• When downloading appliance logs, there will be no download progress shown.

• It is not possible to fetch resources from resolvers when defining actions in entitlements.

Audit logging

• The status of LogForwarders is not always updated to Healthy when they experience a failure to connect to peer LogForwarders during an upgrade.

Portal

• Upstream verification fails for HTTPS endpoints using Let’s Encrypt issued certificates.

Client

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.

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.

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.