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’.
To enter shell mode connect to your Citrix ADC with SSH and after logging in enter ‘Shell’.
I will show you two examples in this guide:
1. The conversion of a classic policy
2. The conversion of the whole nsconfig file
Syntax Input:
nspepi (-e "classic expression" | -f "ns config file") (-v)*Max expression length = 1449
Syntax Output:
<Converted advanced expression> | <Convertered ns config>
Converting a Classic Policy
It’s rather simple really. 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 all time favorite ‘NS_True’
The same Advanced Expression for that is just ‘TRUE’.
The syntax for converting a classic policy is:
nspepi -e "policy"So for my policy it would be:
nspepi -e "ns_true"
Comes out as expected!
How do I see the difference?
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.
*Please mind that I have not tested these policies, they are direct conversions
Example1:
classic: REQ.HTTP.HEADER headername CONTAINS example.com
advanced: “HTTP.REQ.HEADER(\”headername\”).CONTAINS(\”example.com\”)”
Example2:
classic: REQ.IP.SOURCEIP == 192.168.176.100
advanced: CLIENT.IP.SRC.EQ(192.168.176.100)
Converting the NSConfig File
NSPEPI can also conver 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.confAfter entering I got no real confirmation that the conversion was succeeded. I believe that does happen on some versions though. However, the files are created!
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 <current file name> <new file name>
Now proceed with a warm reboot
Exit (to exit the shell)reboot -warm
You should be good to go now! :).
22 Comments on Converting Citrix ADC policies with NSPEPI
Alex Gabra
Hello thanks for this information. I have a couple questions…Do you convert the policies after or before the upgrade to latest version of 13? Also when you run a conversion of the polies on the whole ns.conf file, are there steps different than what you mentioned when having an HA pair?
Thanks!
Mick Hilhorst
Hi Alex,
You can do it both before and after; I would choose before so your bindings do not stop working.
Be mindful that if you upgrade to the latest version of 13 your ”Citrix Gateway Virtual Server” policies will probably not auto-convert with this.
I believe this is due to the fact that all gateway policies need to be ‘unbinded’ first if any classic policy is present. Otherwise advanced policies can’t be bound.
As for HA, the configuration get’s synced (unless you disabled this). Only need to do this on the primary ADC, the secondary will copy the configuration automatically in a couple of minutes. So no different steps, just no real need to do it on the secondary ADC.
Kind Regards,
Mick Hilhorst
Robert Arnett
I just tried this on a test ADC and the new_nsconfig does not have the Virtual servers in the new file?
Mick Hilhorst
Hi Robert,
Sorry to hear that, most likely something went wrong.
Are there any logs in the warn_ns.conf?
If you like you can upload the nsconfig file of your test environment (as long no sensitive data is in there) and the new_nsconf and your warn file.
Would be happy to take a look at it for you.
Kind Regards,
Mick Hilhorst
Ray Davis
Nice write-up. Just what I was looking for.
Mick Hilhorst
Glad it helped Ray. If you have any questions left; I’m sure you know where to find me on slack.
Mark
Hi Mick,
I tried this on a 13.0 HA pair
Run nspepi against the current ns.conf on the primary NS, renamed ns.conf to ns.conf.old and renamed new_ns.conf to ns.conf.
There were no warnings in the warn_ns.conf.
Rebooted the primary NS, so it became secondary. After it was up again did a failover so it was primary again.
Checked ns.conf but noticed it was the old ns.conf from before the conversion.
Did the failover force the old config to get synchronized over the converted one?
Mick Hilhorst
Hi Mark,
That could very well be, you probably already know but; you can disable the synchronization in the HA settings.
You can also choose to set the primary ADC to ‘Stayprimary’.
I normally disable the HA sync, do it on the secondary node and reboot that one.
If all is well, I do the failover and repeat the steps on the new secondary, this should not be required as the sync takes care of it (if you re-enable it again) but I just like to be sure.
If you need any help with these steps, let me know.
Kind Regards,
Mick
Rajan
I am going to test this on my 13.1 HA, hopefully it will work. 13.1 has lots of setting missing for some reason. will update with result.
Corné
Hi Mick,
Thanks for the write-up! It helped me on some key issues where the Ctx doc’s left off.
In your latest reply you state ‘If all is wel …’
How do you verify if the ADC is functioning correctly, while the node is still secondary?
Kind Regards,
Corné
Mick Hilhorst
Hi Corné,
Happy it helped! That is an excellent question, and something I maybe should have clarified better.
It depends on the configuration you have set up, but here is a baseline of what I would do for a quick glance.
Please mind that I just state steps, it’s up to you if they are applicable or not :).
-First failover your node, so you used the upgraded one (I recommend doing this during off-hours for minimal impact)
-Check if your certificates are all present (compare with the old config)
-Check if your virtual servers / content switching vserver / gateways are all up.
-Check if you can still login with your ldap accounts on the NS (if applicable)
-Check if your syslogging still works (if applicable)
If those things are all fine and dandy, you are probably good to go.
Kind Regards,
Mick
Pascal
Hey Mick,
any idea regarding this?:
Converted the ns.conf, replaced the old one with the new one and rebooted the primary NS. HA was disabled.
After reboot logged on to the NS and saw that a running config awaits his saving. When saving the running config the ns.conf got the old configuration settings again..
Thanks in advance!
Mick Hilhorst
Hi Pascal,
This is behavior can occur when you save the running configuration before the reboot.
In that case, the file gets overwritten with the pre-converted ns.conf again as it is in the ‘running configuration’.
The NetScaler has both a ‘running configuration’ and a ‘saved configuration’. Upon saving, the running configuration gets written to the saved configuration. So you want to evade that save button before rebooting.
Hope that helps,
Mick
simon
Hi Mick,
thanks for this post. I noticed that session policies bound on a GW are not converted, so i had to manually unbound them.
How do I now that there are any classic policies still bounded, is there maybe a command to check it?
Mick Hilhorst
Hi Simon,
Most welcome!
The gateway policies indeed do not get converted and need to be done manually.
There is no easy way to check for remaining classic policies inside the NetScaler, but the folks I work with created a tool: app.xconfig.io
Here you can upload your ns.conf file and it will also report on any classic policies.
Kind Regards,
Mick Hilhorst
simon
Thanks Mick, I will check the tool, looks really promising
Torquise
Hello,
Can you help me with this?
Expression/Rule: REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver
Do you think it is convertible using the NSPEPI tool? they told me that it can’t be converted using the tool.
If so, can you provide me a step-by-step on how to do it manually without using the NSPEPI tool?
Mick Hilhorst
Hi,
Sorry for my late response, but for any future readers; the expression is very much convertable by NSPEPI. It however, will not automatically convert it if you convert the whole ns.conf file.
This is due to the fact that the expression cant be changed to an advanced expression if it’s bound. If you unbind all the classic expressions relating to the Gateway, you can convert it just fine.
Kind Regards,
Mick
Peso Treday
My site YW9 covers a lot of topics about Internet Marketing and I thought we could greatly benefit from each other. Awesome posts by the way!
Beulah Eusebio
Bookmarked, so I can continuously check on new posts! If you need some details about Thai-Massage, you might want to take a look at ZH5 Keep on posting!
Serena Sauceda
This is some awesome thinking. Would you be interested to learn more? Come to see my website at UQ6 for content about Domains.
Lelia Paulson
You absolutely know how to keep your readers interest with your witty thoughts on that topic. I was looking for additional resources, and I am glad I came across your site. Feel free to check my website 94N about Airport Transfer.