Sessionwright

How to Upgrade a NetScaler® HA Pair Safely (Step-by-Step)

By Sessionwright EngineeringPublished Updated 8 min read

On 27 September 2026, Citrix® published CTX697096. It covers CVE-2026-88771, which affects every NetScaler ADC and Gateway deployment, including the default configuration, and was already being exploited. CISA added it to the KEV catalog the same day with a 30 September due date. The fixed builds were 14.1-73.37 and 13.1-64.23. Eight days later, CTX697174 fixed CVE-2026-88779 in 14.1-73.41 and 13.1-64.28. That one went into KEV on 4 October with a 7 October due date.

So anyone running SAML SP or IdP on 73.37 had to do a second HA upgrade inside two weeks. This is the runbook for doing it the same way every time. Every step is checked against the NetScaler documentation.

Step 1: Run the pre-checks

Read the bulletin and release notes. Note the fixed builds for your release, and check the FIPS/NDcPP builds separately. Note the preconditions too: CVE-2026-88779 only applies if you have add authentication samlAction or add authentication samlIdPProfile in your config (CTX697174). Our CVE-2026-88771 page summarises the September bulletin.

Confirm the upgrade path. NetScaler recommends upgrading one major release at a time, for example 12.1 → 13.1 → 14.1 (Before you begin). Going from 13.1 to 14.1 is a single step. A direct jump from 13.0 to 14.1-66.x or later is blocked by the built-in pre-checks (pre-upgrade validation).

Check licensing. This is the gotcha in 2026. File-based licensing reached end of life on 15 April 2026. Builds 14.1-66.x and later abort the upgrade with "NetScaler Upgrade Blocked: File based licensing in use" until you move to LAS-based licensing (pre-upgrade validation). Every current fixed 14.1 build is past 66.x, so sort this out before the change window. Two older checks still apply:

  • On VPX, the CSS membership must not have expired.
  • For perpetual licences, the Subscription Advantage date must not be earlier than the build date.

show ns license shows what is currently licensed.

Check disk space. Run shell, then df -h. /var needs 7 GB free: 1 GB for the bundle, 2 GB for extraction and 4 GB for the install. /flash needs about 250 MB (free space on /var). If you need space, the usual places to clear are /var/nstrace, /var/core and old builds in /var/nsinstall.

Check HA health. Run show ha node on both nodes. Both should be UP and sync should not be failing. Make sure neither node is set to STAYSECONDARY or STAYPRIMARY: either setting makes a forced failover fail (force HA failover). The upgrade pre-check aborts on unsaved config or an HA pair that is out of sync, so run save ns config on the primary first.

Handle customisations. If the Gateway logon page is customised, set the UI theme to default. Back up /var/customizations and then delete it from the appliance before upgrading (Before you begin). If you have custom files in /etc, follow the customised files guidance.

Plan access and time. Make sure you have working console or LOM access to both nodes. NetScaler's guidance is to allocate twice as much time as you expect the upgrade to take.

Step 2: Take a full backup and get it off the box

save ns config
create system backup -level full -comment "pre-upgrade"
show system backup

A full backup adds /nsconfig/ssl, licence and FIPS files to the basic set. It is written to /var/ns_sys_backup/ (backup and restore). Copy that .tgz to another machine. Also keep a dated copy of the config from the shell (cp /nsconfig/ns.conf /nsconfig/ns.conf.NS<release><build>), and copy off /nsconfig/monitors/*.pl and /nsconfig/rc.netscaler if you use them.

Step 3: Upgrade the secondary node

On the secondary, stage the build in /var/nsinstall as described in the standalone CLI procedure. Create the 14.1 directory only if it doesn't already exist. Copy the .tgz into build_73.41 with SCP or WinSCP before you extract it.

shell
cd /var/nsinstall
mkdir 14.1
cd 14.1
mkdir build_73.41
cd build_73.41
tar -xvzf build-14.1-73.41_nc_64.tgz
./installns --pre_check
./installns

If you're asked "Do you wish to delete old signature files and kernel images?", answer No unless /flash is short of space. Then reboot when prompted.

There are two alternatives. In the GUI, go to System > System Upgrade, which runs the same validation checks. From the CLI, you can use the install <url> command, which takes -preCheck, -y and http/https/sftp/scp/ftp/file URLs (install).

After the reboot, run show ns version. Then run show ha node, which should show this node as secondary with sync disabled.

Step 4: Fail over to the upgraded node

Run this from the upgraded secondary:

force HA failover

The docs explain what happens while the two nodes run different builds (HA pair upgrade). If the builds have different internal HA versions, the following are disabled: HA config sync, command propagation, state-service sync, connection mirroring and persistence-session sync. In show ha node that shows up as Sync State: AUTO DISABLED and Propagation: AUTO DISABLED. If the internal HA versions match, those functions keep working. The same page has a table of builds where the internal HA version changed, so check whether your source and target builds fall either side of one.

The failover itself has some quirks (forcing a failover):

  • A forced failover is not propagated or synchronised.
  • Forcing a failover while an HA sync is in progress can drop active data sessions, so wait for any sync to finish.

Optional: use ISSU instead of a plain failover

If the internal HA versions differ, existing data connections are lost at failover. In Service Software Upgrade (ISSU) fixes that by replacing the failover with a migration (ISSU docs). After the migration, the new primary sends existing connections back to the old primary until they close.

  • start ns migration starts the migration. show ns migration shows its progress.
  • complete ns migration force-completes it on 14.1-47.x and later.
  • stop ns migration rolls back, but only while the migration is still running.

ISSU has prerequisites and limits:

  • A SYNC VLAN is required on both nodes, and that only works in L2 HA, not INC mode.
  • It is not supported on Azure, on IPv6 HA, or with admin partitions.
  • Jumbo frames, IPv6 sessions and LSN sessions are not migrated.

Step 5: Upgrade the former primary

The original primary is now secondary. Upgrade it exactly as in Step 3. Keep the mixed-version window short, and make no config changes until both nodes match.

Step 6: Fail back (optional) and verify sync and propagation

The documented procedure finishes with a second force HA failover, which makes the original primary primary again. Skip it only if nothing depends on which node is primary. Then run:

show ha node

You should see Sync State: ENABLED (or SUCCESS on the secondary) and Propagation: ENABLED. If someone disabled sync or propagation by hand, re-enable them on each node, because set HA node settings are not propagated:

set HA node -haSync ENABLED
set HA node -haProp ENABLED
force HA sync

The docs say to force a sync after re-enabling propagation (propagation, sync).

Step 7: Kill sessions if the bulletin says so

Only do this when the vendor tells you to. For CitrixBleed (CVE-2023-4966) and CVE-2025-5777, the guidance is to terminate sessions after every node is on the fixed build. CTX697096 and CTX697174 contain no such step. The commands, and the reasons behind them, are in the NetScaler post-patch checklist.

Step 8: Validate

  • Build: run show ns version on both nodes.
  • Entities: check that virtual servers and monitors are UP, GSLB sites sync, and all certificates and licences are present. NetScaler's post-upgrade list covers this. show lb vserver gives you the states.
  • STA: run show vpn vserver <name> and confirm staState is UP for each STA server. A server shows as UP once its Authority ID has been learned (vpn vserver).
  • Gateway logon test: log on from outside the network with MFA. NetScaler has documented a "broken" login page after 14.1-47.46/13.1-59.19 caused by the Content Security Policy header being on by default (NetScaler blog). Test SAML, RADIUS and custom-script logons.
  • ICA launch: launch an app and a desktop through the Gateway, then run show vpn icaConnection.
  • Logs: check /var/log/ns.log and run /netscaler/nsconmsg -K /var/nslog/newnslog -d event (event logs).
  • GUI: clear your browser cache before using the GUI.

Step 9: Have a rollback plan

  • If the secondary misbehaves before the failover, stop there. The primary is untouched and still serving traffic.

  • Downgrades are CLI-only. Do the secondary first, then the primary (downgrade HA). On each node:

    1. Restore the config for the old release: cp ns.conf.NS<releasenumber> ns.conf.
    2. Stage the old build and run installns.
    3. Compare the config before and after, because some config can be lost.

    On 14.1 build 17.x and later, the downgrade fails if the target build's config file is missing; use ./installns -a in that case (downgrade standalone).

  • Use the console if the node comes back unreachable. If the node boots on 192.168.100.1, its configuration didn't load (troubleshooting). restore system backup <file> followed by reboot restores a backup.

  • Rolling back reopens the CVE. On a KEV-listed fix, try fixing forward first.

FAQ

Can I upgrade NetScaler 13.1 to 14.1 directly?

Yes. 13.1 to 14.1 is a single major-release step. Check licensing first, because LAS licensing is required for 14.1-66.x and later.

What is the NetScaler upgrade path from 12.1 or 13.0?

Upgrade one major release at a time. From 12.1 that means 13.1 and then 14.1. A direct upgrade from 13.0 to 14.1-66.x is blocked.

Does session reliability survive an HA failover during an upgrade?

Not reliably. If the two builds have different internal HA versions, existing data connections are lost at failover even with connection failover enabled. ISSU exists to address this.

Can I upgrade a NetScaler HA pair entirely from the CLI?

Yes. Both upgrades and failovers can be done in the CLI or the GUI. Downgrades are CLI-only.

Want a second pair of eyes?

Before the window, paste your show ns version output into the free NetScaler build and CVE checker. It maps your build to the bulletins, fixed builds and KEV status in your browser, and scans nothing. If you'd rather not run this procedure by hand twice in a fortnight, Sessionwright's Nightpatch Gateway patch workflow works through it as plan → approve → execute. It is read-only by default, and every change is approved and logged.

Sources

Check your build before the next bulletin

Paste a NetScaler build or your show ns version output into the free checker to see the CVEs that affect it, their CISA KEV status and the fixed build for your release. It runs in your browser and never touches the appliance.

Check your NetScaler buildSee how Nightpatch upgrades

Related guides

Citrix and NetScaler are trademarks of Citrix Systems, Inc. and/or its affiliates. Azure is a trademark of the Microsoft group of companies. Sessionwright is not affiliated with or endorsed by Cloud Software Group, Citrix or Microsoft.