Product Documentation
ADC
14.1 - Current Release 13.1 13.0 12.1
View PDF

Troubleshooting issues related to the installation, upgrade, and downgrade processes

August 20, 2024
Contributed by: 
C C S

If the appliance does not work as expected after you complete the installation, upgrade, or downgrade process, the first thing to do is to check for the most common causes of the problem.

Resources for troubleshooting

For best results, use the following resources to troubleshoot an issue related to installing, upgrading, or downgrading a Citrix ADC:

  • The configuration files from the appliance. In case of a High Availability pair, the configuration files from both appliances.
  • The following files from the appliance(s):
    • The relevant newnslog files.
    • The ns.log file.
    • The messages file.
  • A network topology diagram.

Issues and resolutions

Following are the most common installation, upgrade, and downgrade issues, and tips for resolving them:

  1. Issue

    Upgrading a Citrix ADC MPX appliance fails due to hardware and software incompatibility.

    Resolution

    See the Citrix ADC MPX hardware-software compatibility matrix and check whether the software release is supported on the Citrix ADC MPX hardware.

  2. Issue

    Upgrading a Citrix ADC VPX appliance fails due to Citrix ADC VPX appliance and hypervisor incompatibility.

    Resolution

    See the Citrix ADC VPX appliance and hypervisor compatibility matrix and check whether the Citrix ADC VPX appliance model is supported on the hypervisor.

  3. Issue

    Upgrading a Citrix ADC appliance fails due to hardware errors.

    Resolution

    Validate the integrity of the Citrix ADC appliance. If you have a Citrix ADC hardware appliance, Citrix recommends running fsck for running a disk check and validating the integrity of the Citrix ADC hard drive.

    For more information, see How to Verify the File System Integrity of a Citrix ADC appliance.

  4. Issue

    Upgrading a Citrix ADC appliance by using the GUI stalls.

    Resolution

    Refresh the browser to check whether the upgrade is progressing or not.

  5. Issue

    Upgrading a Citrix ADC appliance fails due to low Space in /var Directory

    Resolution

    Free up space on the /var directory. For more information, see Refer to How to free space on /var directory.

  6. Issue

    The Citrix ADC is not accessible after the software downgrade

    Cause

    During the software downgrade process, if the configuration file of the existing release and build does not match the configuration file of the earlier release and build, the appliance cannot load the configuration, and the default IP address is assigned to the appliance.

    Resolution

    • Verify that the appliance is accessible from the console.
    • Verify the NSIP address and the routes on the appliance.
      • If the IP address has changed to the default 192.168.100.1 IP address, change the IP address as required.
      • Verify that the appliance is accessible.

  7. Issue

    During an upgrade, if I run the command for synchronizing, the following message appears:

    Command failed on the secondary node but succeeded on the primary node.

    Resolution

    Do not run any dependent commands (set /unset /bind /unbind) when High Availability (HA) synchronization is in progress.

  8. Issue

    During an upgrade process, traffic does not pass through the new primary node when you run the force failover command.

    Resolution

    • Check for problems with the network topology and the switch configurations.
    • Run the set L2param -garpreply ENABLED command to enable the GARP reply.
    • Try using Virtual MAC if not already used.
    • Run the sendarp –a command from the primary node.

  9. Issue

    After upgrading or downgrading a Citrix ADC appliance, connecting to the appliance fails through SSH.

    Resolution

    Perform the following operations in the Citrix ADC appliance:

    • Remove old or insecure host keys at /nsconfig/ssh/ssh_host_*.
    • Review the custom SSHD configuration at /nsconfig/sshd_config and check if it is still relevant and compatible. Rename or remove the custom SSHD configuration accordingly.
    • Cold reboot the Citrix ADC appliance

  10. Issue

    In an HA pair, after you run the force HA failover command the devices keep rebooting. The secondary device does not come up after an upgrade.

    Resolution

    Check to see if the /var directory is full. If so, remove the old installation files. Run the df –h command to show the available disk space.

  11. Issue

    After upgrading an HA pair, one of the nodes is listed as state UNKNOWN.

    Resolution

    • Check to see if both nodes are running the same build. If the builds are not same and HA nodes have a version mismatch, some of the fields are shown as UNKNOWN when you run the show ha node command.
    • Check to see if the secondary appliance is reachable.

  12. Issue

    After you upgrade the Citrix ADC, the interface shows most of the load balancing virtual servers and services are DOWN.

    Resolution

    Verify that the SNIP address is active on the secondary appliance. Also, type the show service command to see if the service is running.

  13. Issue

    After performing an upgrade, all virtual servers are down on the secondary appliance.

    Resolution

    Enable the HA state and HA synchronization by running the following commands:

    • set node hastate enable
    • set node hasync enable

    Disabling HA is not recommended.

  14. Issue

    After performing a downgrade, the Citrix ADC does not boot up properly.

    Resolution

    Check to see if the correct license has been installed.

  15. Issue

    In an HA pair, some features do not get synchronized after an upgrade is performed.

    Resolution

    Run the sync ha file misc command to synchronize the configurations files from the primary node to secondary node.

  16. Issue

    During reboot, the following error message appears:

    One or more commands in ns.conf failedWhat should I do?

    Resolution

    Make sure that no command in the ns.conf file exceeds the 255 byte limit. In commands that create policies that are too long for the 255-byte limit, you can use pattern sets to shorten the policies.

    Example:

    add cs policy p11 -rule 'HTTP.REQ.URL.ENDSWITH_ANY("ctx_file_extensions")'
Done
<!--NeedCopy-->

    ctx_file_extensions is a default patset that covers a large number of extensions. In addition to the default pattern sets, you can create user-defined pattern sets. Add a patset by running the following command:

    add patset <name>
<!--NeedCopy-->

    Note: Patsets are supported only in release 9.3 or later.

  17. Issue

    When upgrading a Citrix ADC VPX appliance, I am told to free up space in /var. What files do I remove?

    Resolution

    Remove the old installation files from /var/tmp/ directory. Also remove unwanted files from /flash.

  18. Issue

    There is no connectivity to the graphical user interface (GUI) when you run the force HA failover command on the secondary appliance.

    Resolution

    Log on to the secondary appliance using the command line interface and enable the access to GUI by running the set ns ip <IP> -gui enabled command.

  19. Issue

    After performing an upgrade, and when I click on any link on the GUI that has to load a java applet (Upgrade Wizard or license Wizard), the following error message appears: GUI version does not match with the kernel version. Please close this instance, clear java plug-in cache and reopen.

    Resolution

    • Log on to the Citrix ADC using the GUI.
    • Navigate to Citrix ADC Gateway > Global Settings.
    • Click Change Global Settings under Settings.
    • In the details pane, under Client Experience, select Default from the UI theme list.
    • Click OK.

Note

These troubleshooting steps also apply to issues with configuration loss when downgrading the software across multiple releases.

For any other issue, see the release notes, Knowledge Center articles, and FAQs.

Troubleshooting issues related to the installation, upgrade, and downgrade processes
August 20, 2024
Contributed by: 
C C S
August 20, 2024
Contributed by: 
C C S

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.