Version 6.6.x

  • 7 minute read
Prev Next

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 SDP 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.6 Controller will work with 6.4 Gateways.

AppGate ZTNA Client versions should be kept within two versions of AppGate ZTNA appliances. For example, when using 6.4 appliances, SDP Clients must be on a version from 6.2 through 6.6.

Upgrading Between Versions

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

Downloads

Supported SDP installers and upgrade files

Appgate SDP Support

Client software and Client compatibility information

Client Downloads

sdpctl, API specs, k8s operator, Terraform provider, Cloud marketplace

Software Resources

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, 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 version 6.6.x

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

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

  • 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 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, 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 and Deprecations

Removed

  • Removed the Default TTL for DNS lookups field from DNS resolvers and DNS forwarder.

  • Removed the “Keep me sign in until token expires” checkbox from the Admin UI sign on screen.

  • Removed the following fields from the top level of their respective APIs:

    • Removed name, creationDate, and refreshInterval from:

      • /admin/stats/appliances

      • /admin/stats/top-entitlements

      • /admin/stats/active-sessions/dn

      • /admin/stats/user-logins

      • /admin/status/on-boarded-devices

    • shortName from /admin/sites

    • nameResolution.dnsResolvers.defaultTtlSeconds and nameResolution.dnsForwarding.defaultTtlSeconds from /admin/sites

    • Removed the source query parameter support from DELETE /admin/admin-messages

  • The following deprecated Prometheus/SNMP metrics have been removed and replaced with gw_name_resolver_XXX:

    • gw_azure_resolver_cache_count

    • gw_azure_resolver_cache_ttl

    • gw_illumio_resolver_cache_count

    • gw_illumio_resolver_cache_ttl

    • gw_illumio_resolver_label

  • The following deprecated Prometheus/SNMP metrics have been removed:

    • gw_event_queue_period_peak

Deprecated

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

  • IdP DNS settings. A migration guide can be found here.

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

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

Known Issues

NAT Traversal

  • Lite clients do not support NAT traversal.

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

  • NAT traversal won’t work if SPA mode is UDP (and TCP) and the Site has QUIC as the tunnel protocol. Fixed in 6.6.2 Appliance.

  • If the Gateway uses an IP address in the Client Hostname/IP field, the Connection Broker will not work. The SAN IP of the Connection Broker must be added to Extra hostnames in the Gateway certificate, or ensure that the Gateway uses a hostname. Fixed in 6.6.3 Clients.

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

Application Discovery

  • For custom app types, the port type displays the hit port(s) when it should display the port or ports that define the custom app type. Fixed in 6.6.1.

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

  • “Delete all data” does not actually delete all data and the application will re-appear after the next analysis.

  • Resetting data of a lot of applications at the same time (after creating narrow rules) is very slow. Fixed in 6.6.1.

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.

Gateway

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

  • DTLS tunneling will not work when Entitlements + control message header is > 16KB.

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

  • iOS users who added a profile before 6.3 was released, and has been using the profile since then, may lose that profile on upgrade. Fixed in 6.6.1.

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

Related articles