Product Documentation

Upgrading to Release 11.1

Feb 13, 2017

You follow the same basic procedure to upgrade either a standalone appliance or each appliance in a high availability pair, although additional considerations apply to upgrading a high availability pair.

This document includes the following information:


Upgrading a Standalone NetScaler

Before upgrading the system software, make sure that you have the required licenses. For more information, see NetScaler Licensing Overview. Existing NetScaler licenses continue to work when you upgrade to version 11.1.

Note

When upgrading from release 10.0, 10.1, 10.5, or 11.0 you have the option to use the configuration utility or the command line interface. We recommend that you use command line interface to upgrade, because it works smoothly with all NetScaler versions.

Note

You cannot upgrade to NetScaler 11.1 from the following builds by using the Upgrade Wizard of the NetScaler GUI:

  • All builds of NetScaler 10.1
  • Any build before Build 57.x of NetScaler 10.5

In the following procedure, <release> and <releasenumber> represent the release version you are upgrading to, and <targetbuildnumber> represents the build number that you are upgrading to. The procedure includes optional steps to avoid losing any updates that are pushed to the /etc directory during the upgrade.

Note

If your NetScaler appliance runs any 9.x or lower release, visit the Product Matrix site for more information.

To upgrade a standalone NetScaler appliance running release 10.0, 10.1, 10.5, or 11 by using the command line interface


Follow these steps to upgrade a standalone NetScaler appliance to version 11.1:
  1. Use an SSH client, such as PuTTy, to open an SSH connection to the appliance.
  2. Log on to the appliance by using the administrator credentials. Save the running configuration. At the prompt, type:save config
  3. Create a copy of the ns.conf file. At the shell prompt, type:
    1. cd /nsconfig
    2. cp ns.conf ns.conf.NS<currentreleasenumber><currentbuildnumber>
    You should backup the configuration file to another computer.
  4. (Optional) If you have modified some of the following files in the /etc directory, and copied them to /nsconfig to maintain persistency, any updates that are pushed to the /etc directory during the upgrade might be lost:
    • ttys
    • resolv.conf
    • sshd_config
    • host.conf
    • newsyslog.conf
    • host.conf
    • httpd.conf
    • rc.conf
    • syslog.conf
    • crontab
    • monitrc

    To avoid losing these updates, create a /var/nsconfig_backup directory, and move the customized files to this directory. That is, move any files that you modified in /etc directory and copied to /nsconfig by running the following command:

    cp /nsconfig/<filename> /var/nsconfig_backup

    Example:
    cp /nsconfig/syslog.conf /var/nsconfig_backup
    
  5. Create a location for the installation package. At the shell prompt type
    1. cd /var/nsinstall
    2. mkdir <releasenumber>nsinstall
    3. cd <releasenumber>nsinstall
    4. mkdir build_<targetbuildnumber>
    5. cd build_<targetbuildnumber>
  6. Download the installation package (build-<release>-<targetbuildnumber>_nc.tgz). To download the installation package from the Citrix website, do the following:
    1. Go to MyCitrix.com, log on with your credentials, and click Downloads.
    2. In Select a Product, select NetScaler ADC.
    3. Under Firmware, click the release and build number to download.
    4. Click Get Firmware.
  7. Copy the installation package to the directory that you created for it in step 5.
  8. Extract the contents of the installation package. Example:
    tar –xvzf build-11.1-47.1_nc.tgz
    
  9. Run the installns script to install the new version of the system software. The script updates the /etc directory. Example:
    ./installns
    
    

  10. When prompted, restart the NetScaler.
  11. (Optional) If you performed step 4, do the following:
    1. Manually compare the files in /var/nsconfig_backup and /etc and make appropriate changes in /etc.
    2. To maintain persistency, move the updated files in /etc to /nsconfig.
    3. Restart the appliance to put the changes into effect.

Note

To install an FIPS appliance, run the installns script with the -F option. 

Warning

When upgrading to the NetScaler nCore build, the installation script prompts you to delete the /var directory if the swap partition is smaller than 32 gigabytes (GB). If this prompt appears, type N, save any important files located in /var to a backup location, and then re-run the installation script.

If the free space available on the flash drive is insufficient to install the new build, the appliance prompts you to clean up the flash drive. 

Example Copy

login: nsroot
Password: nsroot
Last login: Thu Jun 23 15:05:05 2016 from 10.252.243.134
Done
> save config
> shell
Last login: Thu Jun 23 15:05:05 2016 from 10.252.243.134
root@NSnnn# cd /var/nsinstall
root@NSnnn# cd 11.1nsinstall
root@NSnnn# mkdir build_47.10
root@NSnnn# cd build_47.10
root@NSnnn# ftp <FTP server IP address>
ftp> mget build-11.1-47.10_nc.tgz
ftp> bye
root@NSnnn# tar xzvf build-11.1-47.10_nc.tgz
root@NSnnn# ./installns
installns version (11.1-47.10) kernel (ns-11.1-47.10_nc.gz)
...
...
...
Copying ns-11.1-47.10_nc.gz to /flash/ns-11.1-47.10_nc.gz ...

...
Installation has completed.

Reboot NOW? [Y/N] Y

To upgrade a standalone NetScaler running release 10.0, 10.1, 10.5, and 11.0 by using the configuration utility

  1. In a web browser, type the IP address of the NetScaler, such as http://10.102.29.50.
  2. In User Name and Password, type the administrator credentials and then click Login, as shown in the following figure.

  3. In the configuration utility, in the navigation pane, click System.
  4. In the System Overview page, click System Upgrade.
  5. Follow the instructions to upgrade the software.
  6. When prompted, select Reboot.

Note

After the upgrade, close all browser instances and clear your computer's cache before accessing the appliance.

Directory Locations of Script Files for User Monitors

In release 10.1 build 122.17, the script files for user monitors are at a new location. If you upgrade an appliance or virtual appliance to release 10.1 build 122.17 or later, the changes are as follows:

  • A new directory named conflicts is created in /nsconfig/monitors/ and all the built-in scripts of the previous builds are moved to this directory.
  • All new built-in scripts are available in the /netscaler/monitors/ directory. All custom scripts are available in the /nsconfig/monitors/ directory.
  • You must save a new custom script in the /nsconfig/monitors/ directory.
  • After the upgrade is completed, if a custom script is created and saved in the /nsconfig/monitors/ directory with the same name as that of a built-in script, the script in the /netscaler/monitors/ directory takes priority. That is, the custom script is not run.

If you provision a virtual appliance running release 10.1 build 122.17 or later, the changes are as follows:

  • All built-in scripts are available in the /netscaler/monitors/ directory
  • The directory /nsconfig/monitors/ is empty.
  • If you create a new custom script, you must save it in the /nsconfig/monitors/ directory.

For more information about user monitors, see "Understanding User Monitors."

Upgrading a High Availability Pair

To upgrade the system software on NetScaler units in a high availability (HA) pair, first upgrade the secondary node, and then the primary node.
Points to Note
  1. If the two nodes in an HA configuration are running different NetScaler software releases, the following information does not get synchronized on the primary and secondary nodes:
    -Configuration propagation and synchronization
    -States of the services
    -Connection failover sessions
    -Persistence sessions
    The above information might not get synchronized on the primary and secondary nodes if the two nodes are running different builds of the same release. Refer to the Known Issues section of the release notes to check if your NetScaler build has this issue.
  2. Synchronization of the files in the All mode of the Sync HA files command works successfully if the two nodes in an HA configuration are running different NetScaler software releases, or the two nodes are running different builds of the same release. For more information, see Synchronising Configuration Files in High Availability Setup.
Figure 1. Upgrading a High Availability Pair

In the following procedure, machine A is the primary node and machine B is the secondary node before the upgrade.

To upgrade NetScaler units in a high availability pair running release 10.0, 10.1, 10.5, or 11.0 by using the command line interface

On machine B (original secondary node)

  1. Follow the procedure for upgrading a standalone node as described in "Upgrading a Standalone NetScaler Appliance". The procedure includes optional steps to avoid losing any updates that are pushed to the /etc directory during the upgrade.
  2. After the appliance restarts, log on with the administrator credentials and enter the show ha node command to verify that the appliance is a secondary node.
  3. Test the new build by entering the force failover command on the secondary node (machine B). At the command prompt type force failover.

    When you do so, machine B becomes the primary node. If machine B does not function as expected, enter the force failover command on the new primary node (machine B) forcing it to again become the secondary node, and contact Citrix Customer Service before proceeding.

  4. Enter the show ha node command to verify that machine B is the new primary node.

    Example

    login: nsroot 
    Password: nsroot 
    Last login: Thu Jun  23 08:37:26 2016 from 10.102.29.9 
    Done 
    show ha node 
            2 nodes: 
    1)      Node ID:      0 
            IP:        10.0.4.2 
            Node State: UP 
            Master State: Primary 
            ... 
            Sync State: AUTO DISABLED 
            Propagation: AUTO DISABLED 
            ... 
    Done 
    
    Note: After machine B is upgraded successfully, both synchronization and propagation are automatically disabled until you upgrade machine A.

    On machine A (original primary node)

  5. Follow the procedure for upgrading a standalone node as described in "Upgrading a Standalone NetScaler Appliance." The procedure includes optional steps to avoid losing any updates that are pushed to the /etc directory during the upgrade.
  6. After the appliance restarts, log on by using the administrator credentials, and enter the show ha node command to verify that the appliance is a secondary node and that synchronization is disabled.
    Note: After both nodes are upgraded successfully, synchronization and propagation are automatically enabled.

    On machine A and machine B

  7. After successfully upgrading both the nodes, run the show ha node command to verify that synchronization and propagation are enabled on the primary node and synchronization is successful and propagation is enabled on the secondary node.

    Example

    On Primary node (Machine B)

    show ha node 
            Node ID:      0 
            IP:   10.0.4.2 
            Node State: UP 
            Master State: Primary 
    ... 
    ... 
            INC State: DISABLED 
            Sync State: ENABLED 
            Propagation: ENABLED 
            Enabled Interfaces : 1/1 
            Disabled Interfaces : None 
            HA MON ON Interfaces : 1/1 
    ... 
    ... 
            Local node information 
            Critical Interfaces: 1/1 
    Done 
     
    
    On Secondary node (Machine A)
    Show ha node 
            Node ID:      0 
            IP:   10.0.4.11 
            Node State: UP 
            Master State: Secondary 
            .. 
    	      .. 
            INC State: DISABLED 
            Sync State: SUCCESS 
            Propagation: ENABLED 
            Enabled Interfaces : 1/1 
            Disabled Interfaces : None 
            HA MON ON Interfaces : 1/1 
            . . . 
            . . .  
            Local node information: 
            Critical Interfaces: 1/1 
    Done
    
    On machine B (new primary node)
  8. Enter the save ns config command to save the configuration.

Machine B (original secondary node) is now the primary node and machine A (original primary node) is now the secondary node.

Note

You can enter the force failover command again to make machine A (original primary node) as the primary node and machine B (original secondary node) as the secondary node.

To upgrade NetScaler units in a high availability pair running release 10.1, 10.5, or 11.0 by using the configuration utility

  1. Log on to the secondary node and perform the upgrade as described in "To upgrade a standalone NetScaler running release 10.0, 10.1, 10.5, or 11 by using the configuration utility.

    Note: Before upgrading the primary node (machine A), you have the option to test the new release by entering the force failover command at the command line interface on the secondary node (machine B). When you do so, machine B becomes the primary node. If machine B does not function as expected, enter the force failover command at the command line interface on the new primary node (machine B) forcing it to again become the secondary node, and contact Citrix Customer Service before proceeding. If machine B properly assumes the role of primary node, proceed with upgrading the former primary node (machine A).

  2. Log on to the primary node and perform the upgrade as described in "To upgrade a standalone NetScaler running release 10.0, 10.1, 10.5, or 11 by using the configuration utility".