Configuring a Rewrite Action

Warning

The Pattern function in a rewrite action is deprecated from NetScaler 12.0 build 56.20 onwards and as an alternative, Citrix recommends you to use the Search rewrite action parameter.

After enabling the rewrite feature, you need to configure one or more actions unless a built-in rewrite action is sufficient. All of the built-in actions have names beginning with the string ns_cvpn, followed by a string of letters and underscore characters. Built-in actions perform useful and complex tasks such as decoding parts of a clientless VPN request or response or modifying JavaScript or XML data. The built-in actions can be viewed, enabled, and disabled, but cannot be modified or deleted.

Target expressions in actions for TCP rewrite must begin with one of the following expression prefixes:

• <CLIENT.TCP.PAYLOAD. For rewriting TCP payloads in client requests. For example, CLIENT.TCP.PAYLOAD(10000).AFTER_STR(“string1”).
• <SERVER.TCP.PAYLOAD. For rewriting TCP payloads in server responses. For example, SERVER.TCP.PAYLOAD(1000).B64DECODE.BETWEEN(“string1”,”string2”).

You can use all types of existing string manipulation functions with these prefixes to identify the strings that you want to rewrite. To configure a rewrite action, you assign it a name, specify an action type, and add one or more arguments specifying additional data. The following table describes the action types and the arguments you use with them.

Note: Action types that can be used only for HTTP rewrite are identified in the Rewrite Action Type column.

See the Rewrite Action Types and their Arguments table.

To create a new rewrite action by using the command line interface

At the command prompt, type the following commands to create a new rewrite action and verify the configuration:

• add rewrite action <name> <type> <target> [<stringBuilderExpr>] [(-pattern <expression> | -patset <string>)] [-bypassSafetyCheck (YES|NO)]
• show rewrite action <name>

Example 1. Inserting an HTTP Header With the Client IP:

> add rewrite action insertact INSERT_HTTP_HEADER "client-IP" CLIENT.IP.SRC
Done

> show rewrite action insertact

        Name: insertact
        Operation: insert_http_header   Target:Client-IP
        Value:CLIENT.IP.SRC
        BypassSafetyCheck : NO
        Hits: 0
        Undef Hits: 0
        Action Reference Count: 0
 Done

Example 2. Replacing Strings in a TCP Payload (TCP Rewrite):

> add rewrite action client_tcp_payload_replace_all REPLACE_ALL
  'client.tcp.payload(1000)' '"new-string"' -search text("old-string")
 Done
> show rewrite action client_tcp_payload_replace_all

        Name: client_tcp_payload_replace_all
        Operation: replace_all
        Target:client.tcp.payload(1000)
        Value:"new-string"
        Search: text("old-string")
        BypassSafetyCheck : NO
        Hits: 0
        Undef Hits: 0
        Action Reference Count: 0
 Done
>

To modify an existing rewrite action by using the command line interface

At the command prompt, type the following commands to modify an existing rewrite action and verify the configuration:

• <set rewrite action <name> [-target <string>] [-stringBuilderExpr <string>] [(-pattern <expression>

  -patset <string>)] [-bypassSafetyCheck (YES

  NO)]

• <show rewrite action <name>

Example:

> set rewrite action insertact -target "Client-IP"
 Done
> show rewrite action insertact

        Name: insertact
        Operation: insert_http_header   Target:Client-IP
        Value:CLIENT.IP.SRC
        BypassSafetyCheck : NO
        Hits: 0
        Undef Hits: 0
        Action Reference Count: 0
 Done

To remove a rewrite action by using the command line interface

At the command prompt, type the following commands to remove a rewrite action :

rm rewrite action <name>

Example:

> rm rewrite action insertact
Done

To configure a rewrite action by using the GUI

1. Navigate to AppExpert > Rewrite > Actions.
2. In the details pane, do one of the following:
   • To create a new action, click Add.
   • To modify an existing action, select the action, and then click Open.
3. Click Create or OK. A message appears in the status bar, stating that the Action has been configured successfully.
4. Repeat steps 2 through 4 to create or modify as many rewrite actions as you wish.
5. Click Close.

To add an expression by using the Add Expression dialog box

1. In the Create Rewrite Action or Configure Rewrite Action dialog box, under the text area for the type argument you want to enter, click Add.

2. In the Add Expression dialog box, in the first list box choose the first term for your expression.

   • HTTP

     The HTTP protocol. Choose this if you want to examine some aspect of the request that pertains to the HTTP protocol.

   • SYS

     The protected Web site(s). Choose this if you want to examine some aspect of the request that pertains to the recipient of the request.

   • CLIENT

     The computer that sent the request. Choose this if you want to examine some aspect of the sender of the request.

   When you make your choice, the rightmost list box lists appropriate terms for the next part of your expression.

3. In the second list box, choose the second term for your expression. The choices depend upon which choice you made in the previous step, and are appropriate to the context. After you make your second choice, the Help window below the Construct Expression window (which was blank) displays help describing the purpose and use of the term you just chose.

4. Continue choosing terms from the list boxes that appear to the right of the previous list box, or typing strings or numbers in the text boxes that appear to prompt you to enter a value, until your expression is finished. For more information about the PI expressions language and creating expressions for responder policies, see “Policies and Expressions.”

   If you want to test the effect of a rewrite action when used on sample HTTP data, you can use the Rewrite Expression Evaluator.

   Note: The Rewrite Expression Evaluator is only available in the GUI. There is no NetScaler command line version.

To evaluate a rewrite action by using the Rewrite Action Evaluator dialog box

1. In the Rewrite Actions details pane, select the rewrite action that you want to evaluate, and then click Evaluate.

2. In the Rewrite Expression Evaluator dialog box, specify values for the following parameters. (An asterisk indicates a required parameter.)

   • Rewrite Action*—If the rewrite action you want to evaluate is not already selected, select it from the drop-down list. After you select a Rewrite action, the Details section displays the details of the selected Rewrite action.
   • New*—Select New to open the Create Rewrite Action dialog box and create a new rewrite action.
   • Modify*—Select Modify to open the Configure Rewrite Action dialog box and modify the selected rewrite action.
   • Flow Type*—Specifies whether to test the selected rewrite action with HTTP Request data or HTTP Response data. The default is Request. If you want to test with Response data, select Response.
   • HTTP Request/Response Data*—Provides a space for you to provide the HTTP data that the Rewrite Action Evaluator will use for testing. You can paste the data directly into the window, or click Sample to insert some sample HTTP headers.
   • Show end-of-line—Specifies whether to show UNIX-style end-of-line characters (\n) at the end of each line of sample HTTP data.
   • Sample—Inserts sample HTTP data into the HTTP Request/Response Data window. You can choose either GET or POST data.
   • Browse—Opens a local browse window so that you can choose a file containing sample HTTP data from a local or network location.
   • Clear—Clears the current sample HTTP data from the HTTP Request/Response Data window.
3. Click Evaluate. The Rewrite Action Evaluator evaluates the effect of the Rewrite action on the sample data that you chose, and displays the results as modified by the selected Rewrite action in the Results window. Additions and deletions are highlighted as indicated in the legend in the lower left-hand corner of the dialog box.

4. Continue evaluating Rewrite actions until you have determined that all of your actions have the effect that you wanted.

   • You can modify the selected rewrite action and test the modified version by clicking Modify to open the Configure Rewrite Action dialog box, making and saving your changes, and then clicking Evaluate again.
   • You can evaluate a different rewrite action using the same request or response data by selecting it from the Rewrite Action drop-down list, and then clicking Evaluate again.

5. Click Close to close the Rewrite Expression Evaluator and return to the Rewrite Actions pane.

   To delete a rewrite action, select the rewrite action you want to delete, then click Remove and, when prompted, confirm your choice by clicking OK.