Product Documentation

Configuring SureConnect

Feb 13, 2017

The following topics describe how to configure SureConnect for scenarios involving alternate server failure.

  • Configuring the Response for Alternate Server Failure
  • Configuring the SureConnect Policies
  • Customizing the Alternate Content File
  • Configuring SureConnect for Citirx NetScaler Features

Configuring the Response for Alternate Server Failure

Updated: 2013-09-03

If the alternate server fails, and the primary server cannot immediately deliver the requested content to the client, SureConnect does not display alternate content from the failed alternate server in the client Web browser.

The Citrix NetScaler appliance automatically sends a response to the client browser. You can customize the server response to display information suited to your needs.

The default response is:

Your Request is being processed… Estimated Time: ____ Secs

Customizing the Default Response

The NetScaler appliance automatically sends the response to the client if the alternate server fails, or if the appliance is configured to send the default response.

To customize the default response of the appliance, create a vsr.htm file (a sample is provided in this section) as follows:
  • The file can contain any valid HTML statements other than embedded objects.
  • The file size cannot exceed 800 bytes.
  • The file must reside on the NetScaler appliance. If you have a high availability (HA) setup, the file must reside on the primary and secondary nodes. Any changes made to the file on the primary node must also be applied to the file on the secondary node.
  • Put vsr.htm file in the /etc directory.

To customize the default response

Change any of the contents between the </HEAD> and </HTML> tags in the vsr.htm file. Following is the sample content from vsr.htm file. The sections that you can edit are in bold text.

 
HTTP/1.1 200 OK 
Server: NS_WS3.0 
Content-Type: text/html 
Cache-control: no-cache 
Pragma: no-cache 
Set-Cookie: NSC_BPIP=@@SID@@; path=/ 
<HTML> <HEAD> <META HTTP-EQUIV="Refresh" CONTENT="0"> 
</HEAD> <font color=blue size=5>Your request is being processed... 
<br>Estimated Delay: @@DELAY@@ Sec </font> </HTML> 
Note: Include @@DELAY@@ to display the predicted delayed response time in seconds.

SureConnect with In-Memory response (NS action)

Updated: 2013-09-03

When defining the SureConnect policy by using the add sc policy command, you can configure the NetScaler Appliance to serve alternative content to the client.

To enable SureConnect and configure the in-memory response, perform the following tasks:
  • Enable the SureConnect feature on the appliance by using the enable feature SC command
  • Define the services by using the add service <servicename> <IP address> <servicetype> <port> command. This identifies the original server for which the SureConnect is configured and the types of services.
  • Add a SureConnect policy by using the add sc policy command. You can configure a URL-based policy or a rule-based policy. The incoming requests are validated against the URL or rule you specify in the policy.
Note: You can configure the SureConnect feature on a load balancing virtual server. In that case, perform the following additional actions:
  • Enable Load Balancing by using the enable feature LB command.
  • Enable SureConnect feature on the virtual server by using the set lb vserver <vservername> -sc ON command.
  • Bind services to the virtual server by using the bind lb vserver <name> <serviceName> command.
  • Bind policies to the virtual server by using the bind lb vserver <name> -policyname <name> command.

The following example illustrates how to configure SureConnect for the load balancing feature so that SureConnect will display alternative content from the NetScaler appliance.

In this example, two physical servers, with IP addresses, 10.101.3.187 and 10.101.3.188 are load balanced by the NetScaler appliance. The appliance has one configured virtual server, vs-NSact, whose IP address is 10.101.3.201. The file that contains the alternative content is vsr.htm. It is copied from the file system into system memory. Services are loaded until the SureConnect policy triggers, and the appliance supplies the alternate content.

 
enable feature SC LB 
add service psvc1 10.101.3.187 http 80 
add service psvc2 10.101.3.188 http 80 
add lb vserver vs-NSact HTTP 10.101.3.201 80 
bind lb vserver vs-NSact psvc1	 
bind lb vserver vs-NSact psvc2 
add sc policy policyNS -url /cgi-bin/*.cgi -delay 400000  
-action NS 
set sc parameter -vsr /nsconfig/ssl/vsr.htm 
bind lb vserver vs-NSact -policyName policyNS 
set lb vserver vs-NSact -sc ON 
save config 
Table 1. Parameter values used in this example
Service  
Name psvc1, psvc2
Server 10.101.3.187, 10.101.3.188
Protocol HTTP
Port 80
Load Balancing Virtual Server  
Name vs-NSact
IP Address 10.101.3.201
Protocol HTTP
Port 80
SureConnect Policy  
Name policyNS
URL /cgi-bin/*.cgi
Delay(microseconds) 400000
SC Parameter  
VSR File Name vsr.htm

To configure this example by using the configuration utility

  1. In the In the navigation pane, navigate to System > Settings. In the Modes and Features pane, perform the following actions:
    1. Click Configure Basic Features, select Load Balancing, and Click Go.
    2. Click Configure Advanced Features, select SureConnect, and Click Go.
  2. In the navigation pane, navigate to Security > Protection Features > SureConnect. In the details pane, click Parameters. In the Configure SureConnect Parameters window, browse and select the VSR filename.
  3. Navigate to Traffic Management > Load Balancing > Services. In the details pane, click Add. In the Create Services window, enter the paramter values as shown in Table 5-1, and click OK.
  4. Navigate to Traffic Management > Load Balancing > Virtual servers. In the details pane, click Add. In the Create Virtual Server (Load Balancing) dialog box, enter the values shown in Table 5.1 for the Load Balancing Virtual Server parameters and click OK.
  5. In the navigation pane, navigate to Traffic Management > Load Balancing > Virtual servers. Select the virtual server vs-NSact and click Open in the details pane. The Configure Virtual system (Load Balancing) dialog box, displays the list of configured services. Select services psvc1 and psvc2 and click OK.
  6. In the navigation pane, expand Security > Protection Features > SureConnect. In the details pane, click Add. Create the policy with the values as given in the parameters table.
  7. In the navigation pane, navigate to Traffic Management > Load Balancing > Virtual servers. Select the virtual server vs-NSact and click Open in the details pane. In the Configure Virtual system (Load Balancing) dialog box, click the Policies tab. Click >> to expand the features. Select SureConnect. When the list of SureConnect polices appear, select policyNS and click OK.
  8. In the navigation pane, navigate to Traffic Management > Load Balancing > Virtual servers. Select the virtual server vs-NSact and click Open in the details pane. In the Configure Virtual system (Load Balancing) dialog box, on the Advanced tab, select SC and click OK.

Configuring the SureConnect Policies

You can configure the following SureConnect policies. The NetScaler appliance matches incoming requests in the order the policies are configured:
  • Exact URL-based policies
  • Wildcard rule-based policies

Configuring Exact URL Based Policies

Updated: 2013-09-03

When you configure an exact URL based policy, the NetScaler appliance matches the incoming request against the URL that has been configured in the policy. URL based policies take precedence over rule based policies.

To configure an exact URL based policy by using the command line interface

At the command prompt, type:

add sc policy <name> [-url <URL> | -rule <expression>] [ -delay <usecs>] [ -maxConn <positive_integer>] [ -action (ACS <altContentSvcName> <altContentPath>) | NS | NOACTION)]

To configure an exact URL based policy by using the configuration utility

  1. Navigate to Security > Protection Features > SureConnect.
  2. In the details pane, click Add.
  3. In the Create SureConnect Policy dialog box, set the following parameters:
    • Name*
    • URL (Make sure that the URL check box is selected)
    • Value*
    • Delay (microseconds)*
    • Maximum Client Connections
    • Action (Select from the Choose Action list.)
    • Alternate Service Name (if you select ACS as the Action)
    • Alternate Content Path (if you select ACS as the Action)
    *A required parameter
  4. Click Create, and click Close. The URL based policy appears in the right pane, and a message displays in the status bar that the policy is successfully configured.

Configuring Wildcard Rule-Based Policies

Updated: 2013-09-03

SureConnect matches the incoming requests to a defined rule, if you configure a rule-based policy.

To configure a SureConnect policy based on a wildcard rule by using the command line interface

  1. Create the expression(s).

    Use the add expression command to create each expression.

  2. Create the rule(s).

    Use the add sc policy command with the -rule expression_logic argument to specify the rule(s). In the -rule expression_logic argument, refer to the expression(s) you created in step 1.

    Repeat this command to create and name each rule.

The following example creates a rule “rule = = /*.cgi”:

 
add vserver vs-lb http 1.1.1.1 80 
add expression expr1 url == /cgi-bin/*.cgi 
add expression expr2 url == /index.html 
add sc policy surecpolicy1 -rule (expr1||expr2) -delay 1000000 -action NS 
bind lb vserver vs-lb -policyName surecpolicy1 

To complete the SureConnect configuration, you will need to enter additional commands, beyond those shown in the example.

To configure a wildcard rule-based policy by using the configuration utility

  1. Navigate to Security > Protection Features > SureConnect.
  2. In the details pane, click Add.
  3. In the Create SureConnect Policy dialog box, in the Name text box, type the name of the policy.
  4. Under What to Monitor, click Expression, and then click Configure.
  5. In the Create Expression dialog box, click Add.
  6. In the Add Expression dialog box, enter an expression. For example, you can select an Expression Type of General, a Flow Type of REQ, a Protocol of HTTP, a Qualifier of URLQUERY, an Operator of CONTAINS, and in the Value text box, type AA. For more information about expressions, see "Policies and Expressions."
  7. Click OK, and click Close.
  8. In the Create Expression dialog box, click Create.

Examples of wildcard rules:

“/sports/*” matches all URLs under /sports

“/sports*” matches all URLs whose prefix matches “/sports”, starting at the beginning of the URL.

“/*.jsp” matches all URLs whose file extension is “jsp”

When configuring rule-based policies, first add the more specific rule-based policies, before adding more generic rules (for example, add /cgi-bin/sports*.cgi before adding /cgi-bin/*.cgi).

Displaying the Configured SureConnect Policy

To view the SureConnect policy that you have configured, at the NetScaler command prompt, enter the show sc policy command.

Customizing the Alternate Content File

When SureConnect activates, it can display alternate content from one of the following files that you have configured:
  • progressbar.htm. Displays the progress information.
  • alternatepage.htm. Displays an alternate page.
  • barandpage.htm. Displays both the progress information and an alternate page.

The alternate content files are JavaScript files. During SureConnect installation, these files are copied onto the server that contains the alternate content. These files can contain alternate content (including an alternate page) or references to other files that contain the alternate content.

This section describes the changes you can make to the alternate content file provided by the appliance.
 
//**** DEFINE YOUR VALUES HERE **** 
var alt_url = "/Citrix NetScaler system /sample.gif"; 
var alt_url = "http://www.DomainName.com"; 
var Citrix NetScaler system _logo = "netscaler_logo.gif"; 
var our_logo = "netscaler_logo.gif"; 
var height = 450; 
var width = 550; 
var top = 200; 
var left = 200; 
var popunder = "no"; //specify yes for pop-under & no for pop-up 
var shift_focus = "yes" //if you want to send pop-up to background on getting primary content else specify no 
//**** YOUR DEFINITIONS ENDS HERE **** 
You can make these changes:
  • var alt_url. Specify the URL for the alternate content if a file provides the alternate content. For example:
    var alt_url = “/Citrix NetScaler system/sports.htm”
    Note: The alternate content file must be present in the /Citrix NetScaler system directory under the documents root of the Web server.
  • var our_logo. Specify the image file of your organization logo.
  • var height. Specify the height of the SureConnect window.
  • var width. Specify the width of the SureConnect window.
  • var top and var left. Specify the position of the SureConnect window.
  • var popunder. Specifies the position of the alternate content window. Specify the value as NO to place the alternate content window above the original window. Specify the value as YES to place the alternate content window beneath the original window.
  • var shift_focus. Specify the focus of the alternate content window. YES places the pop-up window in the background when getting the primary content. NO always keeps the pop-up window in focus, even when getting the primary content.
Note: For more information, see the README.txt file provided by the appliance with other alternate content files.

Configuring SureConnect for Citrix NetScaler Features

Updated: 2013-09-03

This section describes how SureConnect works in combination with the load balancing, content switching, cache redirection, and high availability features of the NetScaler appliance.

Configuring SureConnect for Load Balancing

You can use SureConnect in environments where the primary servers use the load balancing feature, with or without alternate servers. If the load balancing virtual server configured for SureConnect fails, the backup virtual server (if there is one) handles the traffic. Backup virtual servers do not support SureConnect policies.

Note: For information about load balancing, see "Load Balancing."

Configuring SureConnect for Cache Redirection

You can use SureConnect in environments where cache redirection is configured. The primary server is a load balancing virtual server bound to the cache redirection virtual server. Regardless of any rules configured for the cache redirection feature:
  • You can configure any URL for SureConnect.
  • Once SureConnect is activated for a client, requests from the client are always sent to the origin server.

Configuring SureConnect for High Availability

SureConnect is compatible with NetScaler appliances operating in high availability mode.

Note: If the optional vsr.htm file is used, it must be present in both nodes (primary and secondary) and must use the same name and directory.