Routing to a subset of servers using web server routing rules

(Dist) (ZOS)
Routing to a subset of servers using web server routing rules

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 using AdminTask commands.

See AdminTasks for web server routing rules for a complete description of the commands available to manage Web server routing rules.

For example, to add a routing rule, use AdminTask.addWebServerRoutingRule(). The parameters needed for the addWebServerRoutingRule command are described in the following procedure:

Tasks

Determine the value of the expression parameter 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.
Operands

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 numeric Virtual port target of the request

Operators

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 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 containing 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'"

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'"

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

For permit or permitMM actionTypes, determine the destinations where requests that match the rule are sent. Use the routingLocations parameter to specify the destinations.

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/node/server

cell name

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

node

The node where the server is located.

server

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/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"

Optional: Specify sets of failover destinations that route requests if all primary destinations are not available. Separate the sets of failover destinations 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.
-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.

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"

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"

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.
Add the routing rule to a web server. Use the parameters that are determined in the previous steps.
AdminTask.addWebServerRoutingRule([-serverName webserver1 -nodeName node1 -order 100 -expression "URI LIKE \'/AppA%\'" -actionType permit -routingLocations "cluster=cell1/*|cluster=cell2/*"]')

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]')

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

After the rules are defined, when a web server connects to the cell, the rules that are associated with that web server are delivered. The web server matches requests against the match expressions that are found in the rules. The expressions are evaluated according to the rule order, from lowest order to highest. The first rule with a matching expression is used. The action associated with the rule determines how the request is handled. If no rules are matched, the request balances the load across all servers that can handle the request.

By default, when a request has session affinity, server selection is based on affinity. If an affinity server is found, that server is chosen and the routing rules are not evaluated. To allow routing rules to override affinity selection, set the overrideAffinity attribute of WebServerRoutingRules to true.

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

Example

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]')

The routing Rule with -order 100 limits the destinations where requests for /AppX are routed to two particular clusters across two cells.

The routing Rule with -order 200 shows how to enable failover from one set of endpoints to another. Rule 200 routes all requests that match the expression to any servers that can handle the request in cell1. If all servers that can handle the request in cell1 are not available, servers that can handle the request in cell2 are chosen for requests that match the rule expression.

The routing Rule with -order 300 shows an example of routing test requests to a server that is in maintenance mode. If test=true is added as a query parameter, then those requests are sent to server1 in cell1, even if that server is in maintenance mode.

The routing Rule with -order 400 shows an example of a redirect rule. The routing Rule with -order 500 shows an example of a reject rule.

Related:

AdminTasks for web server routing rules

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	numeric	Virtual port target of the request

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 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 containing 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.