Policy extensions
The policy extension feature enables you to write extension functions for built-in policy types. The extensions can be used in policy expressions, just like built-in functions. They are executed when the corresponding policy expressions are evaluated. This feature is useful for:
- Adding customized functions to existing Policies.
- Implementing logical constructs for complex customer requirements.
The policy extension feature addresses these limitations by enabling users to write extension functions for built in Policy types. The extensions can then be used in the policy expressions, just like built-in functions. They are executed when the corresponding policy expressions are evaluated.
The following table lists the policy types that can be used when writing an extension, and their associated mappings.
| Policy Type | Mapped Policy Type | Output |
|---|---|---|
| TEXT_T | NSTEXT | String |
| BOOL_AT | NSBOOL | Boolean |
| NUM_AT | NSNUM | Number (double-precision floating point) |
| DOUBLE_AT | NSDOUBLE | Number (double-precision floating point) |
Prerequisites for using policy extensions
The imported functions must conform to the existing policy standards. Therefore:
- The function name must start with a letter and may contain numbers or underscores.
- The function name is treated as case insensitive by Citrix ADC policies.
- The function must return a single value even if the extension language returns multiple values.
- Functions with a variable number of arguments are not supported.
How do policy extensions work?
The existing policies on a Citrix ADC appliance use an interpreter to evaluate the functions, which are imported in a policy extension file. When a user imports a new function in a policy extension file:
- The extension file is validated for syntax and other conditions.
- If the validation fails, the error is reported to the user.
- If the validation succeeds, the extension file is imported to the Citrix ADC appliance and its contents can be used in policy expressions, just like any built-in policy function
- If the policy expression evaluation returns an error during runtime, it is reported as an undef event and the associated error counter is incremented.
Note: If a policy undef event occurs and the policy rule contains one or more policy extension functions, the
show ns extension <name>command displays the undef hits when applied to those policy extensions. If the extension function is aborted, the abort counter value is incremented. - If the policy expression evaluation is successful, expression evaluation resumes until the entire expression is evaluated, or until it is aborted because of an error.
- If the policy expression evaluation returns an error during runtime, it is reported as an undef event and the associated error counter is incremented.
Note: If a policy undef event occurs and the policy rule contains one or more policy extension functions, the
If the extension function takes too long to run, it is aborted, and the error counter pertaining to that extension function is incremented. The extension function is sandboxed, which prevents:
- Excessive CPU usage on the Citrix ADC appliance.
- Excessive memory usage on the Citrix ADC appliance.
- Usage of harmful built-in libraries or third-party libraries or binaries.
- Long-running scripts that could potentially cause the Citrix ADC appliance to reboot.