Converting policy expressions using NSPEPI tool

Classic policy-based features and functionalities are deprecated from NetScaler 12.0 build 56.20 onwards. As an alternative, Citrix strongly recommends you to use the Advanced policy infrastructure. As part of this effort, when you upgrade your appliance to Citrix ADC 12.1 build 56.20 or later, you must replace the Classic policy-based features and functionalities to its corresponding non-deprecated features and functionalities. Also, you must convert Classic policies and their expressions to Advanced policies and expressions. To perform this task for hundreds of policies, you can use the nspepi tool. The tool helps you to auto-convert Classic policies and their expressions (in the Citrix ADC commands, expressions, and configurations) to Advanced policy infrastructure.

The nspepi tool can perform the following:

  1. Convert Classic policy expressions to Advanced policy expressions.
  2. Convert certain Classic policies and their entity bindings to Advanced policies and bindings.
  3. Convert a few additional deprecated features to their corresponding non-deprecated features

Note:

After the nspepi tool successfully converts the ns.conf config file, the tool diplays the converted file as a new file with the same name as the passed-in config file but prepended with a prefix, “new_”. If the converted config file has errors or warnings, you must manually fix them as part of the conversion process. Once converted, you must test the file in test environment for correct behavior and then use it to replace the actual ns.conf config file. After testing, you must reboot the appliance for the newly converted or fixed ns.conf config file to get updated.

Features that only support Classic policies or expressions are deprecated and they need to be replaced by the corresponding non-deprecated features.

Note:

Information pertaining to the older version of nspepi tool is available in a pdf format. For more information, see Classic policy conversion using nspepi tool prior to 12.1-51.16 pdf.

Conversion warnings and error files

Before you use the tool for your conversion, there are few warnings to keep in mind:

  1. All warnings and errors are output to the console. There is a warning file created where the configuration files are stored.
  2. The warnings and error file has the same name as the input file but with a prefix “warn_” added to the file name. During expression conversion (when using -e), the warnings will show up in the current directory with a name “warn_expr”.

Note:

This file is in a standard log file format, with date/time stamp and log level. Previous instances of the file are kept with suffixes like “.1”, “.2”, etc. as the tool is run multiple times. At most 10 instances will be kept.

Converted file format

When converting a configuration file (using “-f”), the converted file will be put into the same directory as where the input configuration file exists with the same name but a prefix “new_”.

Commands handled by the nspepi conversion tool

Following are the commands handled during the auto conversion process.

The following Classic policies and their expressions are converted to Advanced policies and expressions. This includes conversion of entity bindings including global bindings.

  1. add appfw policy
  2. add authorization policy
  3. add cmp policy
  4. add cr policy
  5. add cs policy
  6. add tm sessionPolicy.
  7. add vpn trafficPolicy.

Note: However, for “add tm sessionPolicy” and “add vpn trafficPolicy”, you cannot bind to global override in Advanced policies.

  • The rule parameter configured in “add lb vserver” is converted from Classic expression to Advanced expression.
  • The SPDY parameter configured in “add ns httpProfile” or “set ns httpProfile” command is changed to “-http2 ENABLED”.
  • Named expressions (“add policy expression” commands). Each Classic named policy expression is converted to its corresponding Advanced named expression with “nspepi_adv_” set as the prefix. In addition, usage of named expressions for the converted Classic expressions is changed to the corresponding Advanced named expressions. In addition, every named expression will have two named expressions, where one is Classic and the other one is Advanced (as shown below).

For example:

add policy expression classic_expr ns_true
Converts to:
add policy expression classic_expr ns_true
add policy expression nspepi_adv_classic_expr TRUE
  • The policyType parameter configured in the “set cmp parameter” command is changed to Advanced policy type.

Commands not handled by the nspepi conversion tool

Following are some commands that are not handled as part of the auto conversion process.

  • Some bindings cannot be converted if there are certain interleaving of priorities between global and non-global bind points, between users and groups, and also among bindings to different entities. These will have the affected configuration commented out and an error produced. Such configurations must be converted manually.
  • Both Classic and Advanced policies can be bound to cmp global. There are many cases where the functionality will change once Classic policies are converted to Advanced policies. We have converted commands that can be solved by commenting out some policies. Still there are some commands that cannot be converted; in such cases an error will be produced and conversion has to be done manually.
  • Classic content switching policies that are bound to multiple bind points are not handled.
  • Built-in Classic policy bindings in all features are not handled.
  • Not all uses of Classic built-in named expressions are converted to equivalent Advanced named expressions.
  • Named expressions in a load balancing rule are not handled.
  • Client security expressions are not handled.
  • Bindings to GSLB virtual servers are not handled.
  • The “-precedence” option for content switching and cache redirection virtual servers is not handled.

Known Issues

The following errors can be produced by the nspepi tool:

  • If there is an issue when converting an expression.
  • If a named policy expression uses the clientSecurityMessage parameter because this parameter is not supported in advanced policy expression.

Note: All classic policy bindings with -state option disabled are commented out. The -state option is not available for Advanced policy bindings.

Running the nspepi tool

The following is a command line example for running the nspepi tool. This tool is run from the command line of the shell (you will need to type the “shell” command to the NetScaler “CLI” to get to that). Either “-f” or “-e” must be specified to perform a conversion. Use of “-d” is mainly intended for Citrix personnel to analyze for support purposes.

usage: nspepi [-h]
              (-e <classic policy expression> | -f <path to ns config file>)
              [-d] [-v] [-V]

Convert classic policy expressions to advanced policy
expressions and deprecated commands to non-deprecated
commands.
optional arguments:
  -h, --help            show this help message and exit
  -e <classic policy expression>, --expression <classic policy expression>
                        convert classic policy expression to advanced policy
                        expression (maximum length of 8191 allowed)
  -f <path to ns config file>, --infile <path to ns config file>
                        convert netscaler config file
  -d, --debug           show debug output
  -v, --verbose         show verbose output
  -V, --version         show program's version number and exit

Following are few examples of running nspepi tool from the command line interface:

Example output for –e parameter:

root@ns# nspepi -e "req.http.header foo == \"bar\"
"HTTP.REQ.HEADER(\"foo\").EQ(\"bar\")"

Example output for -f parameter:

root@ns# cat sample.conf
add c**Input**r vserver cr_vs HTTP -cacheType TRANSPARENT -cltTimeout 180 -originUSIP OFF
add cr policy cr_pol1 -rule ns_true
bind cr vserver cr_vs -policyName cr_pol1

Running nspepi with -f parameter:

root@ns# nspepi -f sample.conf  
root@ns#

Example output of -f parameter along with -v parameter

root@ns# nspepi -f sample.conf -v
INFO - add cr vserver cr_vs HTTP -cacheType TRANSPARENT -cltTimeout 180 -originUSIP OFF
INFO - add cr policy cr_pol1 -rule TRUE -action ORIGIN
INFO - set cmp parameter -policyType ADVANCED
INFO - bind cr vserver cr_vs -policyName cr_pol1 -priority 100 -gotoPriorityExpression END -type REQUEST
root@ns#

Example output with converted file and warning files generated.

Converted Config file:

root@ns# cat new_sample.conf
add cr vserver cr_vs HTTP -cacheType TRANSPARENT -cltTimeout 180 -originUSIP OFF
add cr policy cr_pol1 -rule TRUE -action ORIGIN
set cmp parameter -policyType ADVANCED
bind cr vserver cr_vs -policyName cr_pol1 -priority 100 -gotoPriorityExpression END -type REQUEST

Example output of a sample configuration with no errors or warnings:

root@ns# cat warn_sample.conf
root@ns#

Example output of a sample configuration with warnings:

root@ns# cat sample_2.conf
add policy expression security_expr "req.tcp.destport == 80" -clientSecurityMessage "Not allowed"
set cmp parameter -policyType CLASSIC
add cmp policy cmp_pol1 -rule ns_true -resAction COMPRESS
add cmp policy cmp_pol2 -rule ns_true -resAction COMPRESS
add cmp policy cmp_pol3 -rule TRUE -resAction COMPRESS
bind cmp global cmp_pol1
bind cmp global cmp_pol2 -state DISABLED
bind cmp global cmp_pol3 -priority 1 -gotoPriorityExpression END -type RES_DEFAULT
bind lb vserver lb_vs -policyName cmp_pol2
root@ns#

Example of running nspepi with -f parameter:

root@ns# nspepi -f sample_2.conf
ERROR - Error in converting expression security_expr : conversion of clientSecurityMessage based expression is not supported.
WARNING - Following bind command is commented out because state is disabled. Advanced expressions only have a fixed ordering of the types of bindings without interleaving, except that global bindings are allowed before all other bindings and after all bindings. If you have global bindings in the middle of non-global bindings or any other interleaving then you will need to reorder all your bindings for that feature and direction. Refer to nspepi documentation. If command is required please take a backup because comments will not be saved in ns.conf after triggering 'save ns config': bind cmp global cmp_pol2 -state DISABLED
Warning - Bindings of advanced CMP policies to cmp global are commented out, because initial global cmp parameter is classic but advanced policies are bound. Now global cmp parameter policy type is set to advanced. If commands are required please take a backup because comments will not be saved in ns.conf after triggering 'save ns config'. Advanced expressions only have a fixed ordering of the types of bindings without interleaving, except that global bindings are allowed before all other bindings and after all bindings. If you have global bindings in the middle of non-global bindings or any other interleaving then you will need to reorder all your bindings for that feature and direction. Refer to nspepi documentation.
root@ns#

Converted file:

root@ns# cat new_sample_2.conf  
add policy expression security_expr "req.tcp.destport == 80" -clientSecurityMessage "Not allowed"
set cmp parameter -policyType ADVANCED
add cmp policy cmp_pol1 -rule TRUE -resAction COMPRESS
add cmp policy cmp_pol2 -rule TRUE -resAction COMPRESS
add cmp policy cmp_pol3 -rule TRUE -resAction COMPRESS
#bind cmp global cmp_pol2 -state DISABLED
#bind cmp global cmp_pol3 -priority 1 -gotoPriorityExpression END -type RES_DEFAULT
bind cmp global cmp_pol1 -priority 100 -gotoPriorityExpression END -type RES_DEFAULT
bind lb vserver lb_vs -policyName cmp_pol2 -priority 100 -gotoPriorityExpression END -type RESPONSE
root@ns#

Warning file:

root@ns# cat warn_sample_2.conf
2019-02-28 06:20:10,590: ERROR - Error in converting expression security_expr : conversion of clientSecurityMessage based expression is not supported.
2019-02-28 06:20:12,187: WARNING - Following bind command is commented out because state is disabled. Advanced expressions only have a fixed ordering of the types of bindings without interleaving, except that global bindings are allowed before all other bindings and after all bindings. If you have global bindings in the middle of non-global bindings or any other interleaving then you will need to reorder all your bindings for that feature and direction. Refer to nspepi documentation. If command is required please take a backup because comments will not be saved in ns.conf after triggering 'save ns config': bind cmp global cmp_pol2 -state DISABLED
2019-02-28 06:20:12,191: WARNING - Bindings of advanced CMP policies to cmp global are commented out, because initial global cmp parameter is classic but advanced policies are bound. Now global cmp parameter policy type is set to advanced. If commands are required please take a backup because comments will not be saved in ns.conf after triggering 'save ns config'. Advanced expressions only have a fixed ordering of the types of bindings without interleaving, except that global bindings are allowed before all other bindings and after all bindings. If you have global bindings in the middle of non-global bindings or any other interleaving then you will need to reorder all your bindings for that feature and direction. Refer to nspepi documentation.
root@ns#

Binding Priorities

Advanced policies do not allow arbitrary interleaving by priority between global and non-global and between different binding types. If you rely on such interleaving of Classic policy priorities, you will need to adjust the priorities to conform to the Advanced policy rules and to get the behavior you desire. Priorities in Advanced policies are local to a bind point. A bind point is a unique combination of protocol, feature, direction, and entity (entities are specific virtual servers, users, groups, services, and either global override or global default). Policy priorities are not followed across bind points.

For a given protocol, feature, and direction the order of evaluation of Advanced policies is given below:

  • Global override.
  • (Current) AAA user.
  • AAA groups (that the user is a member of) in order of weight - ordering is undefined if two or more groups have the same weight.
  • LB virtual server that either the request was received on or that Content Switching selected.
  • Content switching virtual server, cache redirection virtual server that the request was received on.
  • Service selected by load balancing.
  • Global default.

For authorization policy evaluation, the order is:

  • System override.
  • Load balancing virtual server that either the request was received on or that CS selected.
  • Content switching virtual server that the request was received on.
  • System default.

Within each bind point, the polices are evaluated in order of priority from lowest numbered to highest numbered. Of course policies are only evaluated for the protocol used and direction that the message was received from.

Classic policy bindings that require manual reprioritization

Here are some types of Classic policy bindings that will require manual reprioritization to accomplish your needs. All these are for a given feature and direction.

  • Classic priorities that increase in priority number opposite to the direction of the above entity type lists. For example a content switching virtual server binding lower than a load balancing virtual server binding.
  • Classic priorities that interleave AAA groups. One part of one group is before some other group and yet another part is after part of that other group.
  • Classic priorities that increase in number other than the order of weights of AAA groups.
  • Classic global priorities that are less than some non-global priority and the same global priorities are greater than some other non-global priority (in other words, any segment of priorities that are a non-global, followed by one or more globals, followed by a non-global).