Routing to a subset of servers by using routing rules

You can use routing rules to select requests for special routing behavior based on up-to-date request information. Web server routing rules are created, listed, updated, deleted by using AdminTask commands.

1. Determine the value of the expression parameter that is used to select the rule. The value of the expression parameter is typically an operand followed by an operator, then followed by some constant value. The exception is the percentage operand, which does not support an operator. See Table 1 for the operands that are supported. See Table 2 for the operators that are supported.

   Table 1. matchExpression operands that are supported . Include an operand in a matchExpression definition.

   Operand	Syntax	Description
   Client IPV4	clientipv4	The IP address of the client that uses the Internet Protocol version 4 (IPv4) dotted quad address type of n.n.n.n.
   Client IPV6	clientipv6	The Internet Protocol version 6 (IPv6) 128-bit address type of x:x:x:x:x:x:x:x that follows Request for Comments 1924 (RFC 1924) of the client computer.
   Cookie name	cookie$name	A cookie name. For example, the expression cookie$My_Cookie_Name='My_Cookie_Value' tests a request to see if it contains a cookie that is named My_Cookie_Name with a My_Cookie_Value value. To test for the presence or absence of a particular cookie, use one of the following expressions: cookie$MyCookieName IS NOT NULL cookie$MyCookieName IS NULL
   Header name	header$name	A header name and value. For example, the expression header$Host='localhost' tests a request to see if it contains an HTTP host header with a locahost value. To test for presence or absence of the host header, use one of the following expressions: header$Host IS NOT NULL header$Host IS NULL
   Percentage	percentage$val	The percentage operand evaluates to true some percentage of the time. For example, percentage$50 evaluates to true on average 50% of the time.
   Query parameter	queryparm$name	A query parameter name and value. For example, the expression queryparm$timezone='EST' tests a request to see if the request contains an HTTP query parameter that is named timezone with an EST value. To test for the presence or absence of a query parameter, use one of the following forms: queryparm$timezone IS NOT NULL queryparm$timezone IS NULL
   URI	uri	Uniform Resource Identifier
   Virtual host	virtualhost	Virtual host target of the request
   Virtual port	virtualport	Virtual port target of the request

   Table 2. matchExpression operators that are supported . Include an operator in a matchExpression definition as needed.

   Operator	Syntax	Description
   Equals	=	The equality operator expresses a case-sensitive match.
   Equals ignore case	EQUALSIGNORECASE	Identical to 'String = String' except that the case of the strings is ignored. For example, 'ABC' EQUALSIGNORECASE 'abc' evaluates to true and ('ABC' = 'abc') evaluates to false.
   IN	IN	Expresses an operand with multiple values in a single expression. For example, for an operand that is called port, to express that the port value can be any or all of the integers 9080, 9090, and 9091, the expression fragment is port IN (9080,9090,9091). How the values inside the parentheses are expressed depends on the data type. For example, if port is an integer, the correct syntax is the value without quotation marks. If port is a string, the correct syntax is port IN ('9080','9090','9091').
   Is not null	IS NOT NULL	Evaluates to true if the specified operand exists.
   Is null	IS NULL	Evaluates to true if the specified operand does not exist.
   Like	LIKE	Expresses pattern matching for string operand values. The value must contain the wildcard character percent sign (%) in the position where the pattern matching starts. For example: The host LIKE %blanca expression matches the word blanca or any other word that ends in blanca. The host LIKE blanca% expression matches the word blanca or any other word that starts with blanca. The host LIKE %blanca% expression matches the word blanca or any word that contains blanca.
   Like ignore case	LIKEIGNORECASE	Identical to 'string LIKE string' except that the case of the strings is ignored.
   Like in	LIKEIN	Evaluates whether a string exists in a list of strings. For example, string likein (string1%, string2%, string3%, etc.) evaluates to true if string matches one or more of the strings in the parentheses. In this example, the parentheses contain three string values.

   An example expression parameter might appear as the following example:

   -expression “uri LIKE ‘/AppA%’”
   or
   -expression “queryparm$myparm = ‘test’”
   

   You can use and, or, not, and parenthesis to form complex sets of operators and operands for evaluation. See the following example:

   -expression “(uri LIKE ‘/AppA%’ and queryparm$myparm = ‘test’) or clientipv4 = \‘127.0.0.1\’”

   Important: The and, or, not operands must be specified as lowercase.
2. Determine the value of the actionType parameter that specifies what action to take when the rule expression is matched.

   The four possible actionTypes are permit, permitMM, redirect, or reject. Specify exactly one of the four possible action types for each routing rule. The permit actionType routes requests to a set of available servers. The permitMM actionType routes to servers even if the chosen server is in maintenance mode. The reject actionType rejects a request with a specific return code. The redirect actionType redirects the request to a specific URL. See the following example:

   actionType permit
   or
   -actionType permitMM
   or
   -actionType reject
   or 
   -actionType redirect
   

3. For permit or permitMM actionTypes, determine the destinations where requests that match the rule are sent. Use the routingLocations parameter to specify the destinations.
   1. Specify the primary set of destinations to route to when the rule expression is matched. Use one or more cluster or server destinations, which are separated by the ampersand (&) symbol.
      To specify a server-typed endpoint, specify server= followed by a three-part server specification, with parts delimited by a forward slash (/):

      server=cell_name/node_name/server_name

      cell name

      The name of the cell where the server is a member.

      node_name

      The node where the server is located.

      server_name

      The server name.

      To specify a cluster-typed endpoint, specify cluster= followed by a two-part cluster specification, with parts delimited by a forward slash (/):

      cluster=cell_name/cluster_name

      cell name

      The name of the cell where the cluster is defined.

      cluster_name

      The cluster name.

      All parts of a server or cluster destination specification can use the wildcard character (*) to match any string.

      -routingLocations “cluster=cell1/cluster1&cluster=cell1/cluster2”
      or 
      -routingLocations “server=cell1/node1/server1&server=cell1/node2/server2”
      or
      -routingLocations “cluster=cell1/cluster1&server=cell1/*/server1”
      

   2. Optional: Specify sets of failover destinations that route requests if all primary destinations are not available. Separate the sets of failover destinations by using the vertical bar (|) symbol. Multiple sets of failover destinations can be specified. The sets of destinations are examined in order until an available server is found.
      See the following example:

      -routingLocations “cluster=cell1/*|cluster=cell2/*”

      In the previous example, if a server that can handle the request is available in cell1, the server in cell1 is chosen. If there are no servers in cell1 available that can handle the request, a server in cell2 that can handle the request is chosen.

4. For the redirect actionType specify the location to redirect to. Use the redirectURL parameter to specify the location. See the following example:

   -redirectURL"http://some.other.destination"

5. For the reject actionType specify the response code to return. Set the errorCode parameter to the HTTP response code to use when the request matches the rule. The code must be an error code that the web server supports.
   See the following example:

   -errorCode"500”

6. Determine the order number of the rule. Use the order parameter to specify where the rule fits in relation to other rules. Each order number can be used only once. Rules are evaluated from lowest order number to highest. The first rule with a matching expression is used. It is best practice to leave gaps between the order numbers so that new rules can be inserted without having to renumber existing rules.
7. Add the routing rule to a web server. Use the parameters that are determined in the previous steps to call the addWebServerRoutingRule method of AdminTask. For example,

   AdminTask.addWebServerRoutingRule(‘[-serverName webserver1 ‑nodeName node1  -order 100 -expression “uri LIKE
           \’/AppA%\’”  -actionType permit
         -routingLocations “cluster=cell1/*|cluster=cell2/*”]’)

   Important: If the nodename parameter value contains a dash (-), then the parameter value needs to be enclosed in quotation marks ("") like this -nodename "WIN-VNN7A0NHS03Node01"
8. Optional: Specify the overrideAffinity property for routing rules. By default, a request that has affinity to a particular server is sent to that server, even if the request matches a routing rule that does not contain the affinity server as a destination. If the overrideAffinity property is set to true, then selecting a destination that is in a matched rule takes precedence over selecting the affinity server. If the affinity server satisfies the matched rule, the affinity server is chosen, even if the affinity server is in a failover set of endpoints. The overrideAffinity property applies to all routing rules, the overrideAffinity property cannot be set on a per rule basis. For example:

   AdminTask.setWebServerRoutingRulesProperty('[-serverName webserver1 -nodeName "node1"
         -propertyName overrideAffinity ‑propertyValue true]')

   Note: Application Edition routing rules always override affinity if the affinity server is not among the permit destinations of the application edition rule.

AdminTask.addWebServerRoutingRule(‘[-serverName webserver1  nodeName 
node1  -order 100 -expression “uri LIKE \’/AppX%\’”  -actionType 
permit -routingLocations “cluster=cell1/clusterA&cluster=cell2/clusterA”]’)
AdminTask.addWebServerRoutingRule(‘[-serverName webserver1  nodeName 
node1  -order 200 -expression “uri LIKE \’/myapp%\’”  -actionType 
permit -routingLocations “server=cell1/*/*|server=cell2/*/*”]’)
AdminTask.addWebServerRoutingRule(‘[-serverName webserver1  nodeName 
node1  -order 300 -expression “uri LIKE \’/AppY%\’ and queryparm$test 
= \’true\’”  -actionType permitMM -routingLocations 
“server=cell1/node1/server1”]’)
AdminTask.addWebServerRoutingRule(‘[-serverName webserver1  nodeName 
node1  -order 400 -expression “uri LIKE \’/myoldapp%\’”  -actionType 
redirect -redirectURL “http://mysite/mynewapp”]’)
AdminTask.addWebServerRoutingRule(‘[-serverName webserver1  nodeName 
node1  -order 500 -expression “uri LIKE 
\’/myveryoldapp%\’”   actionType reject -errorCode 503]’)