Migrate NetScaler VPX™ from 14.1 (FreeBSD) to 15.1 Tech Preview (Linux)

Note:

This tech preview feature is provided for evaluation purposes only and is not intended for production use.

Overview

NetScaler® 15.1 introduces a Linux-based VPX, replacing the FreeBSD-based VPX available in release 14.1 and earlier. In-place migration from 14.1 (FreeBSD) to 15.1 (Linux) is supported across the following on-premises hypervisor platforms:

• VMware ESXi
• Citrix Hypervisor™ (XenServer)
• Linux KVM
• Microsoft Hyper-V

The migration process ensures that your existing configuration is carried over automatically.

You can migrate by using either of the following methods:

• Method 1: In-place upgrade: Upgrades a single appliance, or one node at a time.
• Method 2: Node-by-node HA replacement: Provides a zero-downtime upgrade for HA pairs.

Method 1: In-place upgrade

Prerequisites

Before you start the migration, ensure that the following requirements are met:

Critical pre-upgrade considerations

Review the following considerations before you begin:

• VM snapshot (mandatory): Take a hypervisor snapshot of the VPX before you begin. The migration repartitions the disk and is not internally reversible. The snapshot is your guaranteed rollback path. Do not start the migration without a snapshot.
• External backup (recommended): Back up critical configuration and any custom data.
• Confirm that your deployment does not rely on a feature that is not yet available in the 15.1 Tech Preview. For more information, see Limitations.

Data backup and preservation

The migration automatically preserves the NetScaler configuration, certificates, licenses, and signatures held in a fixed set of directories. Representative preserved locations include:

• /flash/nsconfig (ns.conf, licenses, SSL, custom scripts)
• /flash/boot
• /flash/configdb
• /var/tmp/*.csv
• /var/AAA
• /var/analytics_conf
• /var/download
• /var/krb
• /var/learnt_data
• /var/metrics_conf
• /var/netscaler/gui
• /var/netscaler/locdb
• /var/netscaler/logon
• /var/netscaler/ssl
• /var/nstemplates
• /var/vpn
• /var/vpns
• /var/clusterd/nsclusterd.conf
• /var/mastools
• /var/log/ns-upgrade.log

The active installer’s files and the generated support bundle are also retained. Anything stored outside the preserved directories is removed during the disk repartition and must be backed up manually beforehand.

Note:

If you have customized configuration files in the /etc directory, see Upgrade considerations for customized configuration files in the /etc directory before proceeding with the migration.

Customizations to rc.netscaler, nsbefore.sh, nsafter.sh, and crontab are preserved on disk. However, because the base OS changes from FreeBSD to Linux, they might not work as before. Review and update them after migrating.

Upgrade procedure

To perform the in-place upgrade, complete the following steps:

1. Verify the current build. Log in to the NetScaler CLI and confirm that the build is 14.1-56.x or later:

   show ns version
   <!--NeedCopy-->
   

2. Save the configuration:

   save ns config
   <!--NeedCopy-->
   

3. Take the mandatory VM snapshot from your hypervisor (ESXi, XenServer, KVM, or Hyper-V), and copy any data held outside the preserved directories off the appliance.
4. Go to Citrix.com > Downloads > NetScaler > Virtual Appliances, and download the NetScaler VPX upgrade bundle.
5. Copy the downloaded build-<version-build>_lx_64.tgz file to the /var/nsinstall/ directory on the NetScaler VPX shell and extract it.

6. Run ./installns and reboot the appliance when prompted.

   Important:

   Do not turn off the VM during the multiple reboots required for the process.

Post-upgrade validation

After the upgrade completes, validate the deployment:

• Log in to the NetScaler VPX GUI or CLI and verify that the running version matches the target upgrade bundle version.
• Validate all virtual services, SSL certificates, and policies to ensure correct functionality.

Method 2: Node-by-node HA replacement

The node-by-node HA replacement method enables a zero-downtime upgrade to a 15.1 Linux-based appliance.

Step 1. Lock the HA state of your legacy primary node.

1. Log in to your 14.1 (FreeBSD) primary node and run the following command:

   set ha node -hastatus STAYPRIMARY
   <!--NeedCopy-->
   

2. On the legacy secondary node, remove its HA pairing with the primary node:

   rm ha node <primary-nsip>
   <!--NeedCopy-->
   

3. Verify that the primary node continues to serve traffic without interruption while you proceed with the migration or replacement tasks.

Step 2. Deploy a new secondary node.

1. Provision a new NetScaler VPX by using the 15.1 image.
2. Assign the management IP address previously used by your legacy secondary node.
3. Complete the initial setup, apply the license, and verify that the network configuration is correct.

4. Join the HA nodes:

   add ha node <primary-nsip>
   <!--NeedCopy-->
   

5. Verify that the HA status is UP and synchronization is successful:

   show ha node status
   <!--NeedCopy-->
   

Step 3. Promote the new secondary node to primary.

1. On the old primary node, unset the stay-primary status:

   unset ha node -stayprimary
   <!--NeedCopy-->
   

2. Force a failover:

   force ha failover
   <!--NeedCopy-->
   

3. Verify that the newly deployed secondary node has successfully become the primary node and is fully operational:

   show ha node status
   <!--NeedCopy-->
   

4. Set the new primary node to stay primary:

   set ha node -hastatus STAYPRIMARY
   <!--NeedCopy-->
   

Note:

• If HA synchronization fails, manually synchronize the RPC passwords on both nodes by using the set rpcNode <peer-ip> -password <password> command.
• If any problems arise during this step, fail back to the old primary and restore the legacy secondary node. For assistance, contact the Citrix Support team.

Step 4. Replace the legacy secondary with a new VPX.

1. Remove the legacy secondary node from the HA configuration:

   rm ha node <legacy-secondary-nsip>
   <!--NeedCopy-->
   

2. Provision another new VPX instance by using the 15.1 (Linux) image.
3. Assign the management IP address of the legacy secondary node to the new VPX instance.
4. Complete the setup and license activation.

5. Join this new VPX to the HA pair:

   add ha node <new-primary-nsip>
   <!--NeedCopy-->
   

6. Verify that the HA status is stable, UP, and synchronized:

   show ha node status
   <!--NeedCopy-->
   

Step 5. Validate and finalize.

1. Verify the HA roles and synchronization status across both new nodes.
2. Validate all virtual services, SSL certificates, and policies to ensure correct functionality.
3. Perform failover and failback tests to verify redundancy.
4. Back up all configurations and snapshot the new environment.
5. After successful validation, delete the legacy VPX instances to free up resources.

Rollback or downgrade to 14.1 (FreeBSD)

If you need to return to 14.1 (FreeBSD) after migrating, use either of the following options:

• Revert from the VM snapshot taken before migration. This option is the fastest and recommended.
• In-place downgrade: You can downgrade only to the NetScaler release version 14.1-73.x, which is not yet released. Follow the migration process described in Method 1: In-place upgrade, but use a FreeBSD _nc_* bundle (build-14.1-<build>_nc_64.tgz) instead of the _lx_64 bundle. The configuration held in the preserved directories is retained.

Critical considerations

• Backup: Retain backups of your legacy nodes until the new VPX environment is fully validated and stable.
• Linux KVM only: If the appliance does not boot after the upgrade to Linux, power off the VM, set its CPU mode to host-passthrough (libvirt domain XML: <cpu mode='host-passthrough'/>, or virt-install --cpu host-passthrough), then power it back on.
• Unsupported features: Migration is not recommended if your current deployment relies on features that are not supported. For more information, see Limitations.