• Insights

Customizing and branding NetScaler nCore with integrated Citrix Web Interface

Kraft Kennedy

5 min read

All Insights

Sometime last year, Citrix released support for an integrated Web Interface for the NetScaler nCore.  This was a welcome addition to the already versatile NetScaler appliance.  Most of my clients had leveraged a couple Windows Server 2008 R2  hosts to serve as the Citrix Web Interface and used a NetScaler to load balance them.  Integrating the Web Interface function within the NetScaler itself seemed like a no brainer as it reduces two Windows hosts (which need to be patched, managed, maintained, etc.) and unifies management on the NetScaler appliance itself.  The idea of replacing the Web Interface on a NetScaler sounds like a great idea at first blush, but the Web Interface is usually branded and customized to at least some degree that poses a challenge.  Specifically, most of my clients perform at least some level of customization to their Web Interface.  This might be something as simple as adding a logo or disclaimer, deploying the Online Plugin, or something more involved that includes adding multiple links and changing to a custom skin.  Citrix’s own documentation is lacking when it comes to making these customizations on the NetScaler and Web Interface in the form of disparate knowledge base articles.  In practice, most Citrix administrators (myself included) would likely feel more comfortable customizing a Web Server running under the IIS platform over one running on Apache Tomcat, so in this post I step through different ‘basic’ customizations that I expect every organization would want to do if they had a NetScaler nCore running the integrated Web Interface.

(One last thing to note, to be fair, there are some Citrix KB articles that document some of the steps below that I used to help me compile some of this information, but it is not as organized and is disparate.)

Adding a corporate logo to the splash screen

Even if organizations are not doing many advanced customizations, this is a basic task that I see most firms do. It can be done right from the Citrix Web Interface Management console if the Web Interface was running on a Windows Server/IIS box. Completing on the NetScaler is a bit more tedious. Without getting into too many details about where the authentication point is configured (that might only require only one of these logos to be customized) , the two logos in question are as follows:

Citrix Access Gateway logo:


Citrix Web Interface logo:


First thing you’ll want to do is get an SFTP client to login to the NetScaler appliance. I use WinSCP, but any client should do.  The other thing I would recommend procuring before starting is the correct size and file format of your corporate logos . (It is important these logos are the appropriate size or they will get squashed or cut up on the page.) For the ‘Citrix Access Gateway’ splash logo, that would be going with a 265×62 pixel GIF file. Name this file “ctxHeader01.gif“.  For the ‘Web Interface’ logo, that would be a 59×25 pixel PNG file. Name this file “CitrixLogoHeader.png”.  Once you have procured these custom corporate logos, they need to be replaced on the NetScaler appliance itself with the default images.  Once connected to the appliance with an SFTP client, replace the default logos with the newly created ones in the following locations:

    1. Citrix Access Gateway logo: <root>/netscaler/ns_gui/vpn/images

    1. Web Interface logo: <root>/var/wi/tomcat/webapps/Citrix/XenApp/media*

*Note: This location would be the name of whatever the Web Interface site was named on the NetScaler.  In my example, it was “XenApp”.

Once the files have been replaced, the NetScaler splash page and the Web Interface should be reflected immediately with the updated logos.  The one caveat here is that these logos will be replaced back to default every time the appliance is rebooted.  Not to worry though, there are some basic steps to follow to make sure they are copied back the appropriate location each time, so that they are updated after an appliance reboot.

Follow the basic steps below to complete this:

    1. Create “customizations” folder in the following location:  <root>/var/customizations.

    1. Copy the custom “ctxHeader01.gif” and “CitrixLogoHeader.png” files to this newly created folder.

    1. Browse to <root>flash
      and insert the following lines to the bottom of the rc.netscaler file and hit save.

cp /var/customizations/ctxHeader01.gif /netscaler/ns_gui/vpn/images/ctxHeader01.gif
cp /netscaler/ns_gui/vpn/images/ctxHeader01.gif /var/customizations/
cp /var/customizations/CitrixLogoHeader.png /var/wi/webapps/Citrix/XenApp/media/CitrixLogoHeader.png*
cp /var/wi/webapps/Citrix/XenApp/media/CitrixLogoHeader.png /var/customizations/*

*Note: This location would be the name of whatever the Web Interface site was called on the Netscaler

Adding a disclaimer to the NetScaler splash page

Similar to adding a corporate logo, most organizations opt to add some type of disclaimer to the Citrix Web Interface site for legal reasons.  The process to complete this is significantly more tedious when doing this on a NetScaler than doing this on a Citrix Web Interface/Citrix Secure Gateway setup that leverages Windows IIS.   Follow the steps below to add a disclaimer to the NetScaler:

    1. Edit the index.html in the location: <root>/netscaler/ns_gui/vpn/index.html.

    1. Underneath line 116 in index.html, input the following text with the organizations custom disclaimer and save the file.

<td></td><td></td><td align=”right”><span style=”display:none”><img src=”/vpn/images/LoginButtonRolloverGlow.gif”/></span><input type=”submit” id=”Log_On” value=”” class=”CTX_CaxtonButton” onclick=”ns_check();” onmouseover=”this.className=’CTX_CaxtonButton_Hover’;” onmouseout=”this.className=’CTX_CaxtonButton’;”/></td>
<!– Disclaimer customization –>
This is a private computer system. It is for authorized use only. Users, whether authorized or unauthorized, acknowledge that there is no right or expectation of privacy with respect to any communication, information, or file sent, received or stored through this computer, e-mail, voicemail or other electronic systems.
<!– End of Disclaimer customization–>

<script language=”javascript” type=”text/javascript”>

    1. The disclaimer should apply immediately once the index.html is saved.

    1. Again, like the corporate logos in the previous step, this setting will reset if the NetScaler appliance is rebooted.  In the “customizations” (created in the previous step) folder copy the newly edited index.html

    1. Browse to <root>flash
      and insert the following lines to the bottom of the rc.netscaler file and hit save.

cp /var/customizations/index.html /netscaler/ns_gui/vpn/index.html
cp /netscaler/ns_gui/vpn/index.html /var/customizations/


Deploying the Citrix Online Plugin

One of the most basic customizations that I recommend organizations do is deploy the Citrix Online Plugin from the organizations web interface site instead of the default redirection to the Citrix download page if a client is not detected.  Deploying the client from the Web Interface simplifies the experience for users who are connecting with non firm workstations and ensures the same version that was tested and deployed on firm workstations is deployed to non workstations that require the client.  Again, completing this task from the Windows IIS Web Interface is a fairly straightforward, however the task is not as a straight forward on the Web Interface running on the Netscaler.  Actually, I found the task to be particularly challenging because I could not find good documentation, but below are the steps that worked for me:

    1. Create ‘Clients’ folder structure in the following location and copy the Citrix Online Plugin executable in the following path: <root>/var/wi/tomcat/webapps/Citrix/XenApp/Clients/Windows/On-line Plugin/CitrixOnlinePluginWeb.exe*

    1. Update the WebInterface.conf file (see below for more details) and uncomment “UpgradeClientsAtLogin=On

    1. Save configuration and reboot NetScaler.

*Note: The folders here are case sensitive.

General Management of the Web Interface running on NetScaler

Most administrators who managed the Citrix Web Interface are accustomed to leveraging the management console that is bundled with the install.  Not only does it allow for basic management of the Web Interface site, over the years Citrix has added more and more functionality within the GUI console to handle most customizations and advanced options that previously required folks to manually update the Webinterface.conf file.  Unfortunately, Citrix takes a few steps back with the integrated Web Interface on the NetScaler.  There is absolutely no management console for it and administrators are forced to make update the Webinterface.conf file to configure any custom settings they might need to make.  This link to Citrix’s eDocs library details out all the parameters that can be configured in the Webinterface.conf file for all the different settings the Web Interface accepts for any additional customization/management that needs to be done.