Upgrade

Each Citrix ADM release offers new and updated features with increased functionality. Citrix recommends you upgrade Citrix ADM to the latest release to avail of the new features and bug fixes. A comprehensive list of enhancements, known issues, and bug fixes is included in the release notes accompanying every release announcement. It is also important to understand the licensing framework and types of licenses that can be used before you start to upgrade. For Citrix ADM licensing information, see Licensing.

Before you upgrade

Download the upgrade package from the Citrix ADM Downloads page and follow the instructions in this article to upgrade your system to the latest 12.1 build. After the upgrade operation is started, Citrix ADM restarts and the existing connections are terminated and reconnected when the upgrade is completed successfully. The existing configuration is preserved, but Citrix ADM does not process any data until the upgrade is successfully completed.

Points to note before upgrading to 12.1:

  • If you are upgrading to Citrix ADM 12.1 build 48.18 version from either version 11.1 or from version 12.0 build earlier than 56.x, perform the following steps.

    • Upgrade from existing version to 12.0 build 57.24.

    • Then, upgrade to the latest build of version 12.1.

      You must follow this two-step process because there are certain clean-up procedures required to upgrade successfully to 12.1 release. These procedures are available only from 12.0 build 56.x onwards.

  • With 12.1, the high availability deployment has the ability to configure a floating IP address on the primary node and eliminate the need for a separate Citrix ADC load balancer. Because of this improvement, the high availability deployment must be on the same subnet. If your current deployment is on different subnets, you must review this article to learn about the upgrade process.

  • With 12.1, the advanced backup support has been removed. The advanced backup feature is no longer available after you upgrade to Citrix ADM 12.1. Review this article for more details.

Note

You cannot downgrade Citrix ADM from a 12.1 build to any build of an earlier release.

Recommended precautions:

  • Back up the Citrix ADM server before you upgrade.

  • After the upgrade, you might have to reestablish connections between the Citrix ADM server and the managed instances. A confirmation prompt warns you that connections can fail if you proceed.

  • For Citrix ADM servers in high availability setup, when upgrading, do not make any configuration changes on either of the nodes.

Warning

  • Do not refresh the browser until the upgrade process is successfully completed. It might take a few minutes for the upgrade process to finish.
  • After upgrade, the active node can change in a high availability pair.

Upgrade single Citrix ADM server

To upgrade single Citrix ADM Server:

  1. In a web browser, type the IP address of the Citrix ADM server.

    Note

    For Citrix ADM servers in a high availability mode, type the IP address of either of the Citrix ADM servers in the HA pair, or the load balancing virtual server.

  2. In the User Name and Password fields, enter the administrator credentials.

  3. Navigate to System > System Administrations. Under the System Administration sub-heading, click Upgrade NetScaler MAS.

    localized image

  4. On the Upgrade NetScaler MAS page, select the Clean software image on successful upgrade check box to delete image files after upgrade. Selecting this option removes the Citrix ADM image files automatically upon upgrade.

    Note

    This option is selected by default. If you do not select this check box before starting the upgrade process, you must manually delete the images.

    localized image

  5. You can then upload a new image file by selecting either Local (your local machine) or Appliance. The build file must be present on the Citrix ADM virtual appliance.

    localized image

  6. Click OK. Upgrade process starts along with the following message.

    localized image

Upgrade a high availability pair from earlier releases to 12.1

For Citrix ADM servers in a high availability mode, you can upgrade by either accessing the active node or the load balancing virtual server IP address. Both the Citrix ADM servers are automatically upgraded to the latest build once you initiate the upgrade process in either of the servers.

Important

Points to note while upgrading Citrix ADM in a high availability mode

While upgrading Citrix ADM in high availability mode to 12.1 from an earlier release, the high availability connection is established internally by the “join HA” script that runs on the secondary node. The time taken for the upgrade process is dependent on the network infrastructure, the data present in the database, and the speed of the link. It might take a few hours to reestablish the connection between the two nodes. During this period, the primary node does not receive any heartbeat from the secondary node. You see a notification for missing heartbeat on the primary UI until the upgrade process gets completed. After the upgrade process is over, the secondary node restarts and the high availability deployment is complete.

Note

To know the status of upgrade, log on to each node using SSH, run the following commands and check the output:

pgrep  -lf  installmas

pgrep -lf maintenance

pgrep -lf join_streaming_replication

pgrep -lf pg_basebackup

If any of these commands shows a running process on any of the nodes, then the upgrade is in progress and should not be interrupted. Do not restart Citrix ADM during this time or do not try force failover on the secondary node.

After the upgrade process is complete, sometimes you might not be able to log on with the nsroot/nsroot or your user credentials. This is because the Citrix ADM subsystem has not completely restarted or migration might still be in progress. Do not restart Citrix ADM or do not attempt password recovery. This might have an undesired effect and the system might behave inconsistently. If required, you can try to log on using the nsrecover/<your_password_for_the_nsroot_user> credentials.

After the upgrade and before starting the operations, ensure that both the primary and the secondary nodes are upgraded and the reboot is complete.

Note

You cannot upgrade Citrix ADM in high availability mode using the CLI.

Pooled licensing in Citrix ADM servers in a high availability:

When Citrix ADM servers are deployed in a high availability mode, the license file is attached to the primary node and configured (node-locked) with the hostID or the MAC address of the primary server. Pooled licenses feature is now supported by Citrix ADM in high availability from 12.1 build onwards. To configure pooled licensing feature on both nodes, you must have identical license files on both nodes. To install an identical license on the secondary node, you must rehost the license to the hostID (MAC address) of the secondary node.

Consider a scenario where the Citrix ADM has two server nodes S1 and S2 in high availability mode. The original license file, L1 is installed on server S1. The rehosted license file L2 should now be assigned to S2.

Follow the steps to upgrade Citrix ADM in high availability mode from 12.0 to 12.1 and configure pooled license feature:

  1. Log on to the primary node of the Citrix ADM servers in high availability mode and perform the upgrade process.

  2. Install the rehosted license file L2 on the secondary server node S2.

    At this time:

    • If S2 is the primary node, you can install the L2 license by accessing the GUI of that instance.

    • If S2 is the secondary node, you must manually perform a failover so that S2 now becomes the primary node. Install the license L2 on the new primary node by using the GUI.
      This is because you can access only the primary server in high availability through the GUI.

  3. Configure the floating IP address on the new primary node.

  4. Delete the license server IP addresses on the Citrix ADC instances and reconfigure them to use the floating IP address. Perform this on all Citrix ADC instances.

Citrix recommends that you perform Citrix ADM high availability pooled licensing upgrade by creating a maintenance window on the Citrix ADC instances. This is because removing the license server and adding floating IP address causes the Citrix ADC instances to move back temporarily to the minimum bandwidth support.

High availability upgrade scenarios

There might be two scenarios in which the Citrix ADM servers are deployed in high availability mode.

  • The primary and secondary servers are deployed on the same subnet.

  • The primary and the secondary servers are deployed in different subnets.

This upgrade document assists you in upgrading the Citrix ADM in both these scenarios.

  • Upgrading a high availability setup on the same subnet

  • Upgrading a high availability setup in different subnets

Upgrade a high availability setup on the same subnet

Upgrading of Citrix ADM servers deployed in high availability mode on the same subnet is handled automatically by Citrix ADM 12.1.

To upgrade Citrix ADM deployed in high availability mode on the same subnet:

  1. Log on to the primary node and navigate to System > System Administrations.

  2. Under System Administration, click Upgrade NetScaler MAS.  

  3. If there is an error during upgrade, the following error message is displayed. Follow the instructions as mentioned in the message on the primary server.

    localized image

  4. As part of the upgrade process, you must perform clean-up procedure through the CLI. During the clean-up process, the secondary node becomes the primary node. The old primary node cannot be accessed through its GUI. Do not restart the old primary node as well as the new primary node while the clean-up process is in progress. After the clean-up process is complete, continue the upgrade procedure through the new primary node.

  5. After the upgrade process is complete, the two nodes must synchronize their databases. The time taken for complete synchronization and the new secondary node to come up depends on the data present in the databases.

Note

After the upgrade is successful, you must configure the floating IP address using the Citrix ADM user interface.

  1. To configure floating IP address, navigate to System > Deployment > Configure Floating IP Address for High Availability Mode.

  2. Specify the floating IP address as shown in the following image and click OK.

    localized image

Upgrade a high availability setup in different subnets

Upgrading of Citrix ADM servers deployed in high availability mode on different subnets must be handled by an administrator.

In this scenario, Citrix ADM HA node 1 (primary) is in subnet 1, and Citrix ADM HA node 2 (secondary) is in subnet 2.

To upgrade Citrix ADM deployed in high availability mode on different subnets:

  1. Manually break the high availability setup. For more information, see Disabling high availability.

  2. Upgrade the Citrix ADM standalone node 1. For more information on how to upgrade Citrix ADM, see Upgrade single Citrix ADM server.

  3. Setup and register a new Citrix ADM standalone node 3 in subnet 1.

  4. After registering node 1 and node 3, deploy both these nodes in high availability mode. For details see, Deploying the primary and secondary node as a high availability pair.

    Note

    Configuring the floating IP address is mandatory.

  5. Delete the Citrix ADM node 2.

Upgrade a high availability pair from previous 12.1 versions to the latest version

You can upgrade Citrix ADM servers deployed in high availability from from an earlier 12.1 build to a later 12.1 build.

To upgrade Citrix ADM deployed in high availability mode:

  1. Download the Citrix ADM 12.1 build 49.37 image file from Citrix.com downloads page.

  2. Log on to the primary node and navigate to System > System Administrations.

  3. Under System Administration, click Upgrade NetScaler MAS.

  4. Navigate to the folder where the image is located.

    While upgrading, do not make any configuration changes to either of the nodes.

Warning

  • Do not refresh the browser until the upgrade process is successfully completed. It might take a few minutes for the upgrade process to finish.

  • After upgrade, the active node can change in a high availability pair.

Upgrade Citrix ADM disaster recovery deployment

Upgrading Citrix ADM disaster recovery deployment is a two-step process:

You must first upgrade the Citrix ADM nodes configured in high availability mode in the primary site. Later you must upgrade the disaster recovery node.

Ensure that you have upgraded the Citrix ADM servers that are deployed in high availability before upgrading the disaster recovery node.

Upgrade the Citrix ADM disaster recovery node

  1. Download Citrix ADM upgrade image file from Citrix download site.

  2. Upload this file to the disaster recovery node using “nsrecover” credentials.

  3. Log on to the disaster recovery node using the “nsrecover” credentials.

    localized image

  4. Navigate to the folder where you placed the image file and unzip the file.

  5. Run the following script:

    ./installmas

    localized image

Upgrade on-prem agents for multisite deployment

Upgrading Citrix ADM agent deployment is a three-step process. Ensure that you have completed the following tasks before upgrading the on-prem agents:

  1. Upgrade the Citrix ADM servers that are deployed in high availability.

  2. Upgrade the Citrix ADM disaster recovery node.

    For more information, see Upgrade Citrix ADM disaster recovery deployment.

Upgrade the on-prem agent

  1. Download Citrix ADM agent upgrade image file from Citrix download site.

  2. Upload this file to Agent node using “nsrecover” credentials.

  3. Ensure that you download the correct agent upgrade image. The image file name is of the following format:

    build-masagent-12.1-48.18.tgz

  4. Log on to the on-prem agent using the “nsrecover” credentials.

  5. Navigate to the folder where you placed the image file and unzip the file.

    localized image

  6. Run the following script:

    ./installmasagent

    localized image

Remove support for the Advanced Backup and Restore feature of Citrix ADM

Instead of using the advanced backup capability to take a complete backup of your Citrix ADM server, you can now use the new Disaster Recovery feature made available in Citrix ADM version 12.1 to take a complete backup of your Citrix ADM high availability setup and help with business continuity use cases.

Important

  1. The advanced backup feature is no longer available after you upgrade to Citrix ADM 12.1. To remove the advanced backup feature, and to continue backing up using the Disaster Recovery feature, see Back up your Citrix ADM after upgrading to Citrix ADM 12.1. Disaster Recovery is supported only with Citrix ADM HA.

  2. To continue to take a partial backup of the Citrix ADM server that includes the configuration files, instance details, system data, and so on and then, to restore your Citrix ADM server in a standalone deployment (partial backup), see How to back up and restore your Citrix ADM server in a single-server deployment.

In case of a disaster on the primary server, use the Disaster Recovery feature to start and configure Citrix ADM on the same primary server without losing data. The feature is only available on Citrix ADM servers deployed in a high availability setup from Citrix ADM version 12.1.

Back up your Citrix ADM server after upgrading to Citrix ADM 12.1

To continue to back up your Citrix ADM server Citrix recommends the following:

  1. Delete your remote backup settings on Citrix ADM by doing the following:

    1. Navigate to System > System Administration > Advanced System Backup Settings.

    2. In the Configure Advanced Backup Settings page, select No to disable remote backups.

    3. Click Apply Settings. Please wait for your Citrix ADM server to reboot and apply the changed settings.

    4. Delete your remote backup node.

  2. Deploy and configure a new Citrix ADM server, create a high availability setup with the existing Citrix ADM server that was rebooted in the step above.

  3. Configure Disaster Recovery to continue to backup and restore data. For more information about Disaster Recovery, see Configure disaster recovery for high availability.

Add an additional disk to the Citrix ADM server

If your Citrix ADM storage requirement exceeds the default disk space (120 gigabytes), you can attach an additional disk. You can attach additional disk in both single-server and high availability deployments.

When you upgrade Citrix ADM from release version 12.0 to 12.1, the partitions that you had created on the additional disk in the earlier version remain the same. The partitions are not removed nor are they resized.

The procedure to attach additional disk remains the same in the upgraded build. You can now use the new disk partitioning tool in Citrix ADM to create partitions in the newly added disk. You can also use tool to resize the partitions in the existing additional disk. For more information on how to attach additional disks and to use the new disk partitioning tool, see How to attach an additional disk to Citrix ADM.

Provision Citrix ADC instances in OpenStack using StyleBooks

From Citrix ADM 12.1 build 49.23 onwards, the architecture of OpenStack orchestration workflow has been updated. The workflow now uses Citrix ADM StyleBooks to configure Citrix ADC instances. If you are upgrading to Citrix ADM 12.1 build 49.23 from either version 12.0 or from version 12.1 build 48.18, you must run the following migration script:

/mps/scripts/migration_scripts/migrate_configurations.py

For more information about the “os-cs-lb-mon” StyleBook and the migrtaion script, see Provisioning of Citrix ADC VPX instance on OpenStack using StyleBook