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.
This document includes the following:
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 version 12.1 build 48.18.
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.
You cannot downgrade NetScaler MAS from a 12.1 build to any build of an earlier release.
- 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.
- 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.
Upgrading single NetScaler MAS server
To upgrade single NetScaler MAS Server
- 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.
- In the User Name and Password fields, enter the administrator credentials.
- Navigate to System > System Administrations. Under the System Administration sub-heading, click Upgrade NetScaler MAS.
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.
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.
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.
6. Click OK. Upgrade process starts along with the following message.
Upgrading NetScaler MAS in high availability mode
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.
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.
3. Configure the floating IP address on the new primary node.
4. Delete the license server IP addresses on the NetScaler instances and reconfigure them to use the floating IP address. Perform this on all NetScaler instances.
Citrix recommends that you perform NetScaler MAS high availability pooled licensing upgrade by creating a maintenance window on the NetScaler instances. This is because removing the license server and adding floating IP address causes the NetScaler 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 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.
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.
After the upgrade is successful, you must configure the floating IP address using the NetScaler MAS user interface.
6. To configure floating IP address, navigate to System > Deployment > Configure Floating IP Address for High Availability Mode.
7. Specify the floating IP address as shown in the following image and click OK.
Upgrading 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 Upgrading NetScaler MAS.
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.
Removing 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.
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:
a. Navigate to System > System Administration > Advanced System Backup Settings.
b. In the Configure Advanced Backup Settings page, select No to disable remote backups.
c. Click Apply Settings. Please wait for your NetScaler MAS server to reboot and apply the changed settings.
d. 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.
To 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 NetScaler disk partitioning tool 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.