Upgrade

Each NetScaler MAS release offers new and updated features with increased functionality. Citrix recommends you upgrade NetScaler MAS 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 NetScaler MAS licensing information, see Licensing.

Before you upgrade

Download the upgrade package from the NetScaler MAS 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, NetScaler MAS restarts and the existing connections are terminated and reconnected when the upgrade is completed successfully. The existing configuration is preserved, but NetScaler MAS does not process any data until the upgrade is successfully completed.

Points to note before upgrading to 12.1:

  • If you are upgrading to NetScaler MAS 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 NetScaler 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 NetScaler MAS 12.1. Review this article for more details.

Note

You cannot downgrade NetScaler MAS from a 12.1 build to any build of an earlier release.

Recommended precautions:

  • Back up the NetScaler MAS server before you upgrade.

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

  • For NetScaler MAS 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 NetScaler MAS server

To upgrade single NetScaler MAS Server:

  1. In a web browser, type the IP address of the NetScaler MAS server.

    Note: For NetScaler MAS servers in a high availability mode, type the IP address of either of the NetScaler MAS 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 NetScaler MAS 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 NetScaler MAS 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 NetScaler MAS 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 NetScaler MAS 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 NetScaler MAS in a high availability mode

While upgrading NetScaler MAS 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 NetScaler MAS 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 NetScaler MAS subsystem has not completely restarted or migration might still be in progress. Do not restart NetScaler MAS 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 NetScaler MAS in high availability mode using the CLI.

Pooled licensing in NetScaler MAS servers in a high availability:

When NetScaler MAS 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 NetScaler MAS 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 NetScaler MAS 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 NetScaler MAS in high availability mode from 12.0 to 12.1 and configure pooled license feature:

  1. Log on to the primary node of the NetScaler MAS 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.
  1. Configure the floating IP address on the new primary node.

  2. 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 NetScaler MAS 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 NetScaler MAS 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 NetScaler MAS 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 NetScaler MAS servers deployed in high availability mode on the same subnet is handled automatically by NetScaler MAS 12.1.

To upgrade NetScaler MAS 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 NetScaler MAS 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 NetScaler MAS servers deployed in high availability mode on different subnets must be handled by an administrator.

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

To upgrade NetScaler MAS 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 NetScaler MAS standalone node 1. For more information on how to upgrade NetScaler MAS, see Upgrade single NetScaler MAS server.

  3. Setup and register a new NetScaler MAS 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 NetScaler MAS node 2.

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

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

To upgrade NetScaler MAS deployed in high availability mode:

  1. Download the NetScaler MAS 12.1 build 49.3 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 NetScaler MAS disaster recovery deployment

Upgrading NetScaler MAS disaster recovery deployment is a two-step process:

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

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

Upgrade the NetScaler MAS disaster recovery node

  1. Download NetScaler MAS 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 NetScaler MAS agent deployment is a three-step process. Ensure that you have completed the following tasks before upgrading the on-prem agents:

  1. Upgrade the NetScaler MAS servers that are deployed in high availability.

  2. Upgrade the NetScaler MAS disaster recovery node.

    For more information, see Upgrade NetScaler MAS disaster recovery deployment.

Upgrade the on-prem agent

  1. Download NetScaler MAS 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 NetScaler MAS

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

Important

  1. The advanced backup feature is no longer available after you upgrade to NetScaler MAS 12.1. To remove the advanced backup feature, and to continue backing up using the Disaster Recovery feature, see Back up your NetScaler MAS after upgrading to NetScaler MAS 12.1. Disaster Recovery is supported only with NetScaler MAS HA.
  2. To continue to take a partial backup of the NetScaler MAS server that includes the configuration files, instance details, system data, and so on and then, to restore your NetScaler MAS server in a standalone deployment (partial backup), see How to back up and restore your NetScaler MAS server in a single-server deployment.

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

Back up your NetScaler MAS server after upgrading to NetScaler MAS 12.1

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

  1. Delete your remote backup settings on NetScaler MAS 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 NetScaler MAS server to reboot and apply the changed settings.

    4. Delete your remote backup node.

  2. Deploy and configure a new NetScaler MAS server, create a high availability setup with the existing NetScaler MAS 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 NetScaler MAS server

If your NetScaler MAS 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 NetScaler MAS 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 NetScaler MAS 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 NetScaler MAS.

Provision Citrix ADC instances in OpenStack using StyleBooks

From NetScaler MAS 12.1 build 49.23 onwards, the architecture of OpenStack orchestration workflow has been updated. The workflow now uses NetScaler MAS StyleBooks to configure Citrix ADC instances. If you are upgrading to NetScaler MAS 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