NetScaler Gateway Theme and Customization Troubleshooting

Important! Citrix does not support customizations and cannot offer support to resolve the issue beyond reverting to a default theme.

When customizing NetScaler Gateway themes, there are various issues you may encounter. These can vary due to previous builds where customizations may have been present before upgrading; this is especially true if the customizations were made on a build prior to 11.0.

Themes are complex in the NetScaler Gateway. There are many ways to break them and it can be difficult to recover. To successfully fix the theme system can be difficult, however the following methods can be used to troubleshoot and resolve the issue.

Portal Themes will not apply to the NetScaler Gateway

  1. Global theme is configured

    • In firmware 10.x, customers were given the option to customize the portal theme and bind it globally as per CTX200920. If using a manually modified and customized portal using the method in CTX200920, you must set the customized portal as a global portal configuration. Doing so though means that an applied global portal configuration cannot be overridden with VPN (CitrixNetScaler Gateway) virtual server level portal theme bindings (a newer method of creating and applying portal customizations in 11.x and above firmware). The solution is to first remove the global portal configuration so that the portal theme binding is used. Note this may require clearing browser cache on client after switching.


      1 – Navigate to Citrix Gateway > Global Settings

      2 – Click “Change Global Settings” under “Settings” header

      3 – Under Client Experience tab, locate UI Theme and switch from “Custom” to “Default”

      4 – Click OK

  2. Earlier version of NetScaler (v8 to v10.5 prior to use or availability of CTX200920 method) required you to write a customization theme, then use either /nsconfig/ns.after or /nsconfig/rc.netscaler to run a script to apply the theme. This causes issues in newer versions of NetScaler. Remove the entries in the ns.after and rc.netscaler files and reboot your NetScalers.

    • Verify there are no entries in /nsconfig/ns.after or /nsconfig/rc.netscaler. If there are, remove them. You may also need to restore the default VPN pages. The easiest way is to do a firmware upgrade to the NetScaler using the same version of NetScaler it’s already on.

Newly created themes will not appear as an available theme

  1. Files in /var/vpn/vpn can overwrite the existing VPN GUI folders. Remove everything in this folder. Also verify there are no entries in /nsconfig/ns.after or /nsconfig/rc.netscaler file.

  2. Existing default theme files are modified in a way that breaks the theme system. If this has happened, your only option is to replace the entire theme folder structure. There are two ways to attempt this.

    • Method 1 – Do a firmware upgrade to the NetScaler using the same version of NetScaler it’s already on.

    • Method 2 – If that does not work, the other method is to spin up a VPX on the same version of NetScaler that your main system is on. Then use these commands to make a copy of the needed folders from the new VPX.

    1. Run the following commands:

      cd /var/netscaler/gui/

      tar -zcvf vpn.tar.gz vpn

      cd /var/netscaler/

      tar -zcvf logon.tar.gz logon

    2. Then use WinSCP to copy the vpn.tar.gz and logon.tar.gz files and copy them to the exact same location on the destination NetScaler.

    3. Now on the destination NetScaler, make backups of the /var/netscaler/gui/vpn and /var/netscaler/logon folders:

      mv /var/netscaler/gui/vpn /var/netscaler/gui/vpn-old

      mv /var/netscaler/logon /var/netscaler/logon-old

    4. Run the following commands to extract the files:

      cd /var/netscaler/gui/

      tar -zxvf vpn.tar.gz

      cd /var/netscaler/

      tar -zxvf logon.tar.gz

    5. Reboot the NetScalers and test. This procedure usually works to restore theme files to defaults.

Changes to a theme from the GUI do not apply

The cause and solution of this are the same as when newly created themes do not appear. Follow the steps for that section.

Theme does not work when you fail over

This is typically caused by corrupted GUI folders on either the Primary or Secondary. We have seen instances where a NetScaler GUI was modified such that the theme would not work on any other NetScaler. This was due to corruption of the GUI theme folders. This caused the Secondary to fail to apply the theme. The solution, in this case, is to revert to defaults and recreate your theme from scratch. The solution is the same as when newly created themes do not appear. Follow the steps for that section above.

Logins do not work for specific browsers and Logins fail or get hung for mobile devices, particularly iOS

These are both due to customizations. Revert to the default theme and test. If it works on the default theme then you will need to troubleshoot your customizations.

Responder policies do not work on RFWebUI theme

All requests by RfWebUI are done using AJAX and the response are all generated by the Packet Engine (PPE). Currently, we cannot apply responder policies for PPE-generated responses. Therefore, responder policies are NOT supported currently for the RfWebUI theme.


Leave a Reply