Converting NetScaler policies with NSPEPI
If you are planning on upgrading your Citrix ADC from any version below Citrix ADC 12.0 build 56.20, you might need to update your 'Classic policies' as these will be deprecated from that version forward.
NSPEPI, a tool by Citrix and available from the Citrix ADC CLI can help us upgrade any classic policies. NSPEPI is capable of upgrading just one policy, or the whole nsconfig file alike.
Please note that NSPEPI is only available from the 'Shell'.
I will show you two examples in this guide:
- The conversion of a nisolated classic policy
- The conversion of all policies
To enter shell mode connect to your Citrix NetScaler with SSH and after logging in enter 'Shell'.
The syntax for NSPEPI is as follows:
nspepi (-e "classic expression" | -f "ns config file") (-v)
Converting a Classic Policy
Take the classic policy that you want to convert and copy it to a notepad (or make sure it's available under your clipboard).
My "classic" policy will be the most basic example 'NS_True'
The same "advanced" policy for that is just 'TRUE'.
The syntax for converting a classic policy is:
nspepi -e "policy"
So with the example in mind if would be:
nspepi -e "ns_true"
The NetScaler will return the converted policy, as expected:
How do I know if a policy is classic or advanced?
The difference between a classic and advanced policy might not always be clear.
A quick tip I would like to give is that in the syntax the most clear difference comes from string.
Advanced policies uses brackets, while classic policies do not.
Another difference we can see on the converted policies, where classic for example uses == and advanced uses .EQ.
A third difference we can see, is that the classic policies use spaces as separators instead of characters at some positions.
Example1:
classic:
REQ.HTTP.HEADER headername CONTAINS example.com
"HTTP.REQ.HEADER(\"headername\").CONTAINS(\"example.com\")"
Example 2
classic:
REQ.IP.SOURCEIP == 192.168.176.100
CLIENT.IP.SRC.EQ(192.168.176.100)
Converting all policies on the NetScaler
NSPEPI can also convert the whole NSConfig (ns.conf) file for you.
Not to worry that it's not the actual file that is being upgraded, a second file is generated with the converted policies for you to review. Still, I would recommend to keep an offline backup of the file during the change period. NSPEPI also creates a warning file /nsconfig/warn_ns.conf. Be sure to read it when the conversion is done.
>Fair warning: in my experience the session policies bound on Gateways don't tend to get converted as they are already bound. NSPEPI can not convert them and will just leave them be. All the session policies must be unbound before you can bind an advanced one, even if you do it manually.
The syntax for the conversion is as follows:
nspepi -f /nsconfig/ns.conf
After entering you get no real confirmation that the conversion was succeeded. I believe that does happen on some versions though. However, the files are created if we check manually via
cd /nsconfig/
ls
Upon opening the warning file, no errors/warnings were mentioned.
The new_ns.conf file however was as expected a ns.conf file.
After reviewing the new file, you can rename the ns.conf file to ns.conf.old and rename the new_ns.conf to ns.conf.
You can do this with the following syntax:
mv
|
Now proceed with a warm reboot, without saving your running config. If you save the running config, the conversion will be nullified.
Exit (to exit the shell)
reboot -warm
All your non gateway/auth polcies should be converted now.