When working with customers on upgrading NetScaler firmware one of the upgrade tasks that comes up and is often overlooked is the EPA and NetScaler Gateway plug-in updates that are shipped with each firmware version. There are a few caveats to these deployments and documentation around NetScaler client management is really delivered in piecemeal within Citrix blogs and documentation. With this blog post, I’m hoping to bring all of the pieces together to simplify the process.
To make matters a bit complicated, there are different methods depending on which firmware version you are using. I’m going to break this into two parts: prior to 11.0 firmware and 11.0+ firmware.
Prior to NetScaler 11.0
Endpoint Analysis Client Configuration
Since there was no client management built into the NetScaler firmware prior to 11.x there are some custom client side settings and NetScaler rewrite rules to put in place so that the user is not prompted to upgrade either the EPA or NetScaler Gateway Plug-in after a firmware upgrade is performed.
As per this Citrix Blog Article a couple of rewrite policies and actions can be created on the NetScaler and bound by vServer or globally that apply to both the Mac and Windows plug-ins. This inserts a directive which tells the client that the NetScaler build number matches exactly the client’s version by inserting nsversion = epaActiveX.getEPAVersion(); and nsversion = epaPlugin.getEPAVersion();
Below is a sample configuration:
| add rewrite action EPA-NoCheckA insert_before_all "HTTP.RES.BODY(14000)" q/"nsversion = epaPlugin.getEPAVersion();"+"\n"/ -search "text(\"if(epaPlugin.getEPAVersion()!= nsversion)\")" -bypassSafetyCheck YES add rewrite action EPA-NoCheckB insert_before_all "HTTP.RES.BODY(14000)" q/"nsversion = epaActiveX.getEPAVersion();"+"\n"/ -search "text(\"if(epaActiveX.getEPAVersion()!= nsversion)\")" -bypassSafetyCheck YES add rewrite policy EPA-A "HTTP.REQ.URL.PATH.CONTAINS("epa.html")" EPA-NoCheckA add rewrite policy EPA-B "HTTP.REQ.URL.PATH.CONTAINS("epa.html")" EPA-NoCheckB bind rewrite global EPA-A 100 NEXT -type RES_DEFAULT bind rewrite global EPA-B 110 NEXT -type RES_DEFAULT |
Please note that the javascript file that performs the detection for firmware versions on 11.x has changed so after upgrading to those later versions this code no longer exists.
NetScaler Gateway VPN Plug-in
A registry key for Windows clients and a rewrite rule for Mac clients can be applied to tell the client not to auto update when connecting to the NetScaler Gateway for a VPN session. There is more information on this in CTX119658. The registry key can either be deployed using a GPO or part of an SCCM package that's pushed out with installation of a new NetScaler Gateway plug-in version. For the NetScaler Gateway plug-in for Mac this is done through a rewrite rule either bound globally or to a specific NetScaler Gateway vServer. The details are shown below:
Windows Registry Key
To change the auto upgrade or downgrade, change the following registry key value to zero (for both 32-bit and 64-bit):
| [HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Secure Access Client] "EnableAutoUpdate"=dword:00000000 |
NetScaler 11.0+
Thankfully with the new firmware versions of NetScaler 11 Citrix has provided this functionality out of the box! The choices provided for both the EPA and NetScaler Gateway plug-in for Windows, Linux and Mac have the following options:
| Setting | Description |
| Always | The plug-in always gets upgraded whenever there is a mismatch between the end user plug-in version and the NetScaler build version. This is the default behavior. Choose this option if you don’t want multiple plug-in versions running in your enterprise. |
| Essential | The plug-in gets upgraded only when necessary. The decision to upgrade is based on a predefined version compatibility list on the NetScaler appliance and a similar list on the plug-in. The compatibility list changes when a security vulnerability is discovered in a build. Therefore, you will not miss any security updates with this option. |
| Never | The plug-in does not get upgraded. |
GUI Configuration
You can find these options in the following locations in the NetScaler GUI.
For the EPA client
NetScaler Gateway > Edit vServer > Basic Settings
For the NetScaler Gateway Plug-in
NetScaler Gateway > Policies > Session > Edit Session Profile > Client Experience Tab
They can also be set when adding the vServer or session profile using the CLI:
EPA Plug-in
| add vpn vserver -WindowsEPAPluginUpgrade <action> -LinuxEPAPluginUpgrade <action> -MacEPAPluginUpgrade <action> |
NetScaler Gateway Plug-in
| set vpn parameter -WindowsPluginUpgrade <action> -LinuxPluginUpgrade <action> -MacPluginUpgrade <action> |
Parting Words
Unfortunately, these new settings built into the Firmware in version 11.x are not compatible with the plug-ins prior to version 11.x. For example, if you’re EPA client version is at 10.5.57.7 and you upgrade to 11.0.65.31 the user will still be prompted to upgrade or an error presented to the user.
I hope this clarifies the process and caveats of plug-in management out in the wild and stay tuned for the next edition of "Lessons from the Field" from Accelera Solutions!