Product Documentation

Configuring a Rewrite Action

Nov 24, 2014

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.
Table 1. Rewrite Action Types and Their Arguments
Rewrite Action Type Argument 1 Argument 2
INSERT_HTTP_HEADER: Inserts the HTTP header you specify into the HTTP request or response. This is the default choice. This action type can be used only with HTTP requests and responses.

The HTTP header you want to insert.

For example, if you want to insert the client IP from which a request is sent, type Client-IP.

A string expression that describes the contents of the header you want to insert.

For example, if you want to insert the Client IP from which a request is sent, type CLIENT.IP.SRC.

INSERT_BEFORE: Inserts a new string before the designated string.

A string expression that describes the string before which you want to insert a new string.

For example, if you want to find the hostname www.example.com and insert a string before the example.com portion, type the following: HTTP.REQ.HOSTNAME.BEFORE_STR ("example.com")

A string expression that describes the new string you want to insert.

For example, if you want to insert the new string en. before the string example in the hostname, type en followed by a period.

INSERT_AFTER: Inserts a new string after the designated string.

A string expression that describes the string after which you want to insert a new string.

For example, if you want to find the hostname www.example.com, and insert a string after the www. portion, type the following: HTTP.REQ.HOSTNAME.AFTER_STR ("www.")

A string expression that describes the new string you want to insert.

For example, if you want to insert the new string en. after the string www. in the hostname, type en followed by a period.

REPLACE: Replaces the designated string with a different string.

A string expression that describes the string you want to replace with a new string.

For example, if you want to replace the entire hostname in the Host header, type HTTP.REQ.HOSTNAME.SERVER.

A string expression that describes the new string you want to insert.

For example, if you want to replace the current host header with the string web01.example.net, type web01.example.net.

DELETE: Deletes the designated string.

A string expression that describes the string you want to delete.

For example, if you want to find and delete the string .en in the hostname of HTTP response headers, type the following: HTTP.RES.HEADER("Host").SUBSTR("en.")

 
DELETE_HTTP_HEADER: Deletes the designated HTTP header, including all header contents. This action type can be used only with HTTP requests and responses.

The name of the HTTP header you want to delete.

For example, if you want to delete the cache-control header from HTTP responses, type HTTP.RES.HEADER ("Cache-Control").

 
CORRUPT_HTTP_HEADER: Replaces the name of the given HTTP header with a corrupted name so that it will not be recognized by the receiver. This action type can be used only with HTTP requests and responses.

The name of the HTTP header that you want to corrupt. If the specified header occurs more than once in a request, all the occurrences are corrupted.

For example, if you want to corrupt the Host header in an HTTP request, you can use the following rewrite action command:

add rewrite action corrupt_header_act CORRUPT_HTTP_HEADER Host.

 
REPLACE_HTTP_RES: Replace the http response with the value specified in the target field. This action type can be used only with HTTP requests and responses.

A string expression that describes the string you want to replace the HTTP response with.

For example, type HTTP 200 OK You are not authorized to view this page to replace the entire HTTP response with this warning.

 
REPLACE_ALL: Will replace all occurrences of a pattern in the target text reference with the value specified in the string builder expression.

The part of either the HTTP request or response where you want to carry out the replacement.

A string expression that describes the new string you want to insert.

DELETE_ALL: Delete every occurrence of the pattern specified in the target text reference.

The part of either the HTTP request or response where you want the deletion to occur.

A string pattern after which the deletion should occur.

INSERT_AFTER_ALL: Inserts the value specified by string builder expression after each occurrence of a specified pattern in the target text reference.

The part of either the HTTP request or response where you want the insertion to occur.

A string expression that describes the new string you want to insert.

INSERT_BEFORE_ALL: Inserts the value you specify before each occurrence of the pattern you specify.

The part of either the HTTP request or response that you want to delete.

A string expression that describes the new string you want to insert.

CLIENTLESS_VPN_ENCODE: Encodes the URL you specify in clientless VPN format.

The URL you want to encode.

 
CLIENTLESS_VPN_ENCODE_ALL: Encodes all of the URLs you specify in clientless VPN format.

A pattern that matches the URLs you want to encode.

 
CLIENTLESS_VPN_DECODE: Decodes the URL you specify from clientless VPN format and returns it as unencoded text.

The URL you want to decode.

 
CLIENTLESS_VPN_DECODE_ALL: Decodes all of the URLs you specify from clientless VPN format and returns them as unencoded text.

A pattern that matches all of the URLs you want to decode.

 

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 configuration utility

  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 configuration utility. 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.