Rule Set Management

Learn to use rule sets composed of actions that are applied to traffic at a Load Balancer resource's listener.

A rule set is a named set of rules associated with a load balancer and applied to one or more listeners on that load balancer. To apply a rule set to a listener, you first create the rule set that contains the rules. Rules are objects that represent actions applied to traffic at a load balancer listener. The rule set becomes a part of the load balancer's configuration. You can specify the rule set to use when you create or update a listener for the load balancer.

You can include the following types of rules in a rule set:

Note

Rule sets apply only to HTTP listeners.

You can apply an existing rule set when you edit a listener. You can apply the same rule set to multiple listeners on the same load balancer.

Rule sets are not shared between load balancers. To use the same set of rules on another load balancer, you must create a new, identical rule set under that load balancer.

You can have up to 20 rules in a rule set. You can associate a maximum of 50 rules with a load balancer.

Access Control Rules

Learn about access control rules for Load Balancer resources.

Access control rules permit access to application resources based on user-specified IP address or address range match conditions. If you do not specify any access control rules, the default rule is to allow all traffic. If you add access control rules, the load balancer denies any traffic that does not match the rules.

The service accepts only classless inter-domain routing (CIDR) format (x.x.x.x/y or x:x::x/y) strings for the match condition.

Specify 0.0.0.0/0 or ::/0 to match all incoming traffic.

Note

Only US Government Cloud regions currently permit IPv6 values.

Access Method Rules

Learn about access method rules for Load Balancer resources.

Access method rules specify the HTTP methods allowed at the associated listener. The load balancer does not forward a disallowed request to the backend servers and returns a 405 Method Not Allowed response with a list of the allowed methods. You can associate only one list of allowed methods with a given listener.

By default, you can specify only the standard HTTP methods defined in the HTTP Method Registry. The list of HTTP methods is extensible. If you need to configure custom HTTP methods, contact My Oracle Support to remove the restriction from your tenancy. Your backend application must be able to handle the specified methods.

The following list shows the default HTTP methods:

ACL

LABEL

OPTIONS

SEARCH

BASELINE-CONTROL

LINK

ORDERPATCH

TRACE

BIND

LOCK

PATCH

UNBIND

CHECKIN

MERGE

POST

UNCHECKOUT

CHECKOUT

MKACTIVITY

PRI

UNLINK

CONNECT

MKCALENDAR

PROPFIND

UNLOCK

COPY

MKCOL

PROPPATCH

UPDATE

DELETE

MKREDIRECTREF

PUT

UPDATEREDIRECTREF

GET

MKWORKSPACE

REBIND

VERSION-CONTROL

HEAD

MOVE

REPORT

URL Redirect Rules

Learn about URL redirect rules for Load Balancer resources.

URL redirect rules specify how to route incoming HTTP requests to a different destination URL. URL redirect rules apply only to HTTP listeners. You configure each redirect rule for a particular listener and a designated path. A listener can have only one redirect rule for a given incoming URL path.

When you create a URL redirect rule, you specify the path string and match condition the service uses to evaluate an incoming URL for redirection. You also define the redirect URL and response code.

Incoming Path String Evaluation

You specify the path string, or pattern, to evaluate in the incoming URL. For example:

/video

You also specify the match condition to apply when evaluating the incoming URL for redirection. The available match types are:

  • FORCE_LONGEST_PREFIX_MATCH

    The system looks for a redirect rule path string with the best, longest match of the beginning portion of the incoming URL path.

  • EXACT_MATCH

    The incoming URL path must exactly and completely match the specified path string.

  • PREFIX_MATCH

    The beginning portion of the incoming URL path must exactly match the specified path string.

  • SUFFIX_MATCH

    The ending portion of the incoming URL path must exactly match the specified path string.

Redirection URL Construction

You define the redirect URL applied to the original request. URL redirect rules recognize the following URL components:

<protocol>://<host>:<port>/<path>?<query>

You can specify a literal string or provide a token for any component. Tokens extract values from the incoming HTTP request URL. Tokens are case-sensitive. For example, {host} is a valid token, but {HOST} is not.

  • Protocol

    The HTTP protocol to use in the redirect URL. Valid values are HTTP and HTTPS.

    The {protocol} token extracts the protocol from the incoming HTTP request URL. It is the only valid token for this property.

  • Host

    The valid domain name or IP address to use in the redirect URL.

    The {host} token extracts the host from the incoming HTTP request URL. All URL Redirect tokens are valid for this property. You can use any token more than once.

    Curly braces {} are valid in this property only to surround tokens.

  • Port

    The communication port to use in the redirect URL. Valid values include integers from 1 to 65535.

    The {port} token extracts the port from the incoming HTTP request URL. It is the only valid token for this property.

  • Path

    The HTTP URL path to use in the redirect URL. To omit the path from the redirect URL, set this value to an empty string.

    The {path} token extracts the path string from the incoming HTTP request URL. All URL Redirect tokens are valid for this property. You can use any token more than once.

    If the path string does not begin with the {path} token, it must begin with a forward slash /.

  • Query

    The query string to use in the redirect URL. To omit all incoming query parameters from the redirect URL, set this value to an empty string.

    The {query} token extracts the query string from the incoming HTTP request URL. All URL Redirect tokens are valid for this property. You can use any token more than once.

    If the query string does not begin with the {query} token, it must begin with a question mark? .

    You can specify multiple query parameters as a single string. Separate each query parameter with an ampersand &.

    If the specified query string results in a redirect URL ending with ? or &, the last character is truncated. For example, if the incoming URL is http://host.com:8080/documents and the query property value is ?lang=en&{query}, the redirect URL is http://host.com:8080/documents?lang=en. The system truncates the final ampersand & because the incoming URL included no value to replace the {query} token.

Important

Failure to specify a value for at least one URL component field can result in a redirect loop.

Manual Redirect URL Construction

The Console provides text entry fields for each URL component. Alternatively, you can manually specify the full redirect URL.

You can retain the literal characters of a token when you specify values for the path and query properties of the redirect URL. Use a backslash \ as the escape character for the \, {, and } characters. For example, if the incoming HTTP request URL is /video, the path property value /example{path}123\{path\} appears in the constructed redirect URL as /example/video123{path}.

Some path and query string examples:

  • /example/video/123 appears as /example/video/123 in the redirect URL.

  • /example{path} appears as /example/video/123 in the redirect URL when /video/123 is the path in the incoming HTTP request URL.

  • {path}/123 appears as /example/video/123 in the redirect URL when /example/video is the path in the incoming HTTP request URL.

  • {path}123 appears as /example/video123 in the redirect URL when /example/video is the path in the incoming HTTP request URL.

  • /{host}/123 appears as /example.com/123 in the redirect URL when example.com is the hostname in the incoming HTTP request URL.

  • /{host}/{port} appears as /example.com/123 in the redirect URL when example.com is the hostname and 123 is the port in the incoming HTTP request URL.

  • /{query} appears as /lang=en in the redirect URL when the query is lang=en in the incoming HTTP request URL.

  • lang=en&time_zone=PST appears as lang=en&time_zone=PST in the redirect URL.

  • {query} appears as lang=en&time_zone=PST in the redirect URL when lang=en&time_zone=PST is the query string in the incoming HTTP request. If the incoming HTTP request has no query parameters, the {query} token renders as an empty string.

  • lang=en&{query}&time_zone=PST appears as lang=en&country=us&time_zone=PST in the redirect URL when country=us is the query string in the incoming HTTP request. If the incoming HTTP request has no query parameters, this value renders as lang=en&time_zone=PST.

  • protocol={protocol}&hostname={host} appears as protocol=http&hostname=example.com in the redirect URL when the protocol is http and the hostname is example.com in the incoming HTTP request.

  • port={port}&hostname={host} appears as port=8080&hostname=example.com in the redirect URL when the port is 8080 and the hostname is example.com in the incoming HTTP request URL.

Response Code

You can specify the HTTP status code to return when the incoming request is redirected. Valid response codes for redirection from the standard HTTP specification are:

  • 301 Moved Permanently

  • 302 Found

  • 303 See Other

  • 307 Temporary Redirect

  • 308 Permanent Redirect

The default value is 302 Found.

Request and Response Header Rules

Learn about request and response header rules for Load Balancer resources.

Request and response header rules add, alter, or remove HTTP request or response headers. These rules can help you pass metadata to your backend servers to do things like:

  • Identify which listener sent a request.

  • Notify a backend server about SSL termination.

Examples of how rule sets can help you enhance site security include:

  • Adding headers to prevent external domains from iframing your site.

  • Removing debug headers, such as "Server," sent by backend servers. This action helps you hide the implementation details of your backend.

  • Adding the "strict-transport-security" header, with a proper value, to responses. This header helps guarantee that access to your site is HTTPS only.

  • Adding the "x-xss-protection" header with a proper value. This header helps you enforce the cross-site scripting (XSS) protection built into modern browsers.

  • Adding the "x-content-type" header with a proper value. This header helps you prevent attacks based on content type shifting.

Note

Adding or removing the built-in Host header or one of the X-Headers as described in HTTP "X-" Headers does not remove or override the header value. Instead, performing these actions can append other values or duplicate the header.

Example: Notify WebLogic that the Load Balancer Terminated SSL

You can configure your load balancer to perform SSL termination. Often, your backend applications require notification of this action. For example, HTTPS WebLogic e-commerce online transaction processing looks for the WL-Proxy-SSL header to confirm that a request came in over SSL. You can use rule sets to add this header at the load balancer listener.

Note

For security reasons, WebLogic ignores this header unless you check the WebLogic Plugin Enabled box in WebLogic's Administration Console.

  1. Create a rule set with the following settings. See Creating Rule Sets for more information.

    • Choose the Add Request Header option from the Action list.

    • Enter WL-Proxy-SSL as the Header name.

    • Set the header Value:

      • If your load balancer is configured to perform SSL termination, set this value to "true."

      • If the SSL termination point is in the web server where the plugin operates, set this value to "false."

  2. Create a listener, or edit an existing listener, and add the new rule set. See Listener Management for more information.

HTTP Header Rules

Learn about HTTP header rules for Load Balancer resources.

HTTP header rules specify the size of the HTTP header and the kinds of characters that are permitted within the header. Because some applications require a URL header size greater than the default 8k to support their features, HTTP header rules allow you to set header buffers of up to 64k to avoid "414" (large URI requests) errors.

HTTP header rules allow periods (".") and underscores ("_"), providing you more flexibility in your naming structures.

Creating Rule Sets

Create a rule set for a Load Balancer resource.

Use one of the following methods to create a rule set for a selected load balancer.

To create a rule set using the Console

Use the OCI Console to create a rule set for a Load Balancer resource.

  1. Open the navigation menu, click Networking, and then click Load Balancers.

  2. Select the Compartment from the list.

    All load balancers and network load balancers in that compartment are listed in tabular form.

  3. (optional) Select a State from the list to limit the load balancers displayed to that state.

  4. (optional) Uncheck Load Balancer under Type to only display load balancers.

  5. Select the load balancer for which you want to create a rule set.

    The Load Balancer Details dialog box appears.

  6. Click Rule Sets under Resources.

    The Rule Sets list appears. All rule sets are listed in tabular form.

  7. Click Create Rule Set.

    The Create Rule Set dialog box appears.

  8. Enter the following:

    • Name: Required. Specify a friendly name for the rule set. The name must be unique, and cannot be changed. Avoid entering confidential information.
    • Specify Access Control Rules: Optional. Check this box to add access control rules.

      • IP Address CIDR: Enter the IP address CIDR block from which access is allowed.
      • + Another Access Control Rule: Optional. Click this button to enter another IP address CIDR or click the corresponding X to remove an existing entry.
    • Specify Access Method Rules: Optional. Check this box to add access method rules.

      • Allowed Methods: From the list, select the HTTP methods to allow. You can select multiple methods. Click the label's X to remove an existing method.
    • Specify URL Redirect Rules: Optional. Check this box to add URL redirect rules.

      • Source Path: Specify the incoming path string that triggers the redirect rule. For example, /video.
      • Match Type: Choose the match condition to apply when evaluating an incoming path string. The available match types are:

        • FORCE_LONGEST_PREFIX_MATCH

          The system looks for a redirect rule path string with the best, longest match of the beginning portion of the incoming URL path.

        • EXACT_MATCH

          The incoming URL path must exactly and completely match the specified path string.

        • PREFIX_MATCH

          The beginning portion of the incoming URL path must exactly match the specified path string.

        • SUFFIX_MATCH

          The ending portion of the incoming URL path must exactly match the specified path string.

      • Redirect to: Specify a value for at least one URL component field. Any component fields that you do not modify retain the incoming URL's values.

        Optionally, click the Switch to full URL link to enter the redirect URL manually.

        Caution

        Failure to specify a value for at least one URL component field can result in a redirect loop.
        • Protocol: Specify the HTTP protocol to use in the redirect URL. Valid values are:

          • {protocol}

          • HTTPS
          • HTTP
        • Host: Specify a valid domain name (hostname) or IP address for the redirect URL. All redirect URL tokens are valid for this property.
        • Port: Specify the communication port to use in the redirect URL. Valid values include integers from 1 to 65535.
        • Path: The HTTP URL path to use in the redirect URL. All redirect URL tokens are valid for this property.

          Important

          If the path string does not begin with the {path} token, it must begin with the forward slash character /.
        • Query: Specify the query string to use in the redirect URL. All redirect URL tokens are valid for this property.

          Important

          If the query string does not begin with the {query} token, it must begin with the question mark ? character.
        • Response Code: Specify the HTTP status code to return when the incoming request is redirected. The default response code is 302 Found.

          Valid response codes for redirection from the standard HTTP specification are:

          • 301 Moved Permanently
          • 302 Found
          • 303 See Other
          • 307 Temporary Redirect
          • 308 Permanent Redirect
      • + Another URL Redirect Rule Optional. Click this button to create another rule or click the corresponding X to delete an existing rule.
    • Specify Request Header Rules: Optional. Check this box to add request header rules.

      • Order: Optional. If you have multiple rules, you can click the up or down arrows to move the corresponding rule.
      • Action: Select the action that the rule applies. Available actions include:

        • Add Request Header

          Adds the specified header and value to the incoming request.

          If the specified header is already present, the system replaces it.

          If more than one header with the same name is present, the system removes all of them and adds one header corresponding to the specified header and value.

        • Extend Request Header

          Adds the specified prefix or suffix to the incoming request.

          Provide a prefix value, a suffix value, or both when you choose this action.

          The system does not support this rule for headers with multiple values.

        • Remove Request Header

          Removes the specified header.

          If the same header appears more than once in the request, the load balancer removes all occurrences of the specified header.

        Note

        These rules apply only to HTTP or HTTP2 headers.
      • Header: A header name that conforms to RFC 7230.

        Caution

        The system does not distinguish between underscore and dash characters in headers. That is, it treats example_header_name and example-header-name as identical. Oracle recommends that you do not rely on underscore or dash characters to uniquely distinguish header names.
      • Value: (Add rules only.) A header value that conforms to RFC 7230.
      • Prefix: (Extend rules only.) A character string to add to the beginning of the existing header name. The resulting header must conform to RFC 7230.
      • Suffix: (Extend rules only.) A character string to add to the end of the existing header name. The resulting header must conform to RFC 7230.
      • + Another Request Header Rule Optional. Click this button to create another rule or click the corresponding X to delete an existing rule.
    • Specify Response Header Rules: Optional. Check this box to add response header rules.

      • Order: Optional. If you have multiple rules, you can click the up or down arrows to move the corresponding rule.
      • Action: Select the action that the rule applies. Available actions include:

        • Add Response Header

          Adds the specified header and value to the outgoing response.

          If the specified header is already present, the system replaces it.

          If more than one header with the same name is present, the system removes all of them and adds one header corresponding to the specified header and value.

        • Extend Response Header

          Adds the specified prefix or suffix to the incoming request.

          Provide a prefix value, a suffix value, or both when you choose this action.

          The system does not support this rule for headers with multiple values.

        • Remove Response Header

          Removes the specified header.

          If the same header appears more than once in the response, the load balancer removes all occurrences of the specified header.

        Note

        These rules apply only to HTTP or HTTP2 headers.
      • Header: A header name that conforms to RFC 7230.

        Caution

        The system does not distinguish between underscore and dash characters in headers. That is, it treats example_header_name and example-header-name as identical. Oracle recommends that you do not rely on underscore or dash characters to uniquely distinguish header names.
      • Value: (Add rules only.) A header value that conforms to RFC 7230.
      • Prefix: (Extend rules only.) A character string to add to the beginning of the existing header name. The resulting header must conform to RFC 7230.
      • Suffix: (Extend rules only.) A character string to add to the end of the existing header name. The resulting header must conform to RFC 7230.
      • + Another Response Header Rule Optional. Click this button to create another rule or click the corresponding X to delete an existing rule.
    • Specify HTTP Rules: Optional. Check this box to specify HTTP header options for a listener.

      • HTTP Header Buffer Size: Select one of the following buffer sizes for the HTTP header from the list: None, 8k, 16k, 32k, 64k.
      • Allow Invalid Characters in HTTP Header: Check this box to allow periods (".") and underscores ("_") in the HTTP header.
    • Specify HTTP Header Options: Optional. Check this box to specify HTTP header options for a listener.
      • HTTP Header Buffer Size: Select one of the following buffer sizes for the HTTP header from the list: None, 8k, 16k, 32k, 64k.
      • Allow Invalid Characters in HTTP Header: Optional. Check this box to allow invalid characters in the HTTP header.
  9. Click Create.

After you create a rule set, the set becomes available for use with the associated load balancer. Update a listener to apply the rule set.

To create a rule set using the CLI

Use the command line interface (CLI) to create a rule set for a Load Balancer resource.

Enter the following command:

oci lb rule-set create --name name --load-balancer-id load_balancer_id --items items [OPTIONS]

See the CLI online help for a list of options:

oci lb rule-set create --help

See oci lb rule-set create for a complete description of the command.

To create a rule set using the API

Use the API to create a rule set for a Load Balancer resource.

Run the CreateRuleSet method to create a rule set for a load balancer. See CreateRuleSet for a complete description.

Listing Rule Sets

List the rule sets for a Load Balancer resource.

Use one of the following methods to display a list of rule sets for a selected load balancer.

To list the Rule Sets using the Console

Use the OCI Console to list the rule sets for a Load Balancer resource.

  1. Open the navigation menu, click Networking, and then click Load Balancers.

  2. Select the Compartment from the list.

    All load balancers and network load balancers in that compartment are listed in tabular form.

  3. (optional) Select a State from the list to limit the load balancers displayed to that state.

  4. (optional) Uncheck Load Balancer under Type to only display load balancers.

  5. Select the load balancer for which you want to create a rule set.

    The Load Balancer Details dialog box appears.

  6. Click Rule Sets under Resources.

    The Rule Sets list appears. All rule sets are listed in tabular form.

To list the Rule Sets using the CLI

Use the command line interface (CLI) to list the rule sets for a Load Balancer resource.

Enter the following command:

oci lb rule-set list --load-balancer-id load_balancer_id [OPTIONS]

See the CLI online help for a list of options:

oci lb rule-set list --help

See oci lb rule-set list for a complete description of the command.

To list the Rule Sets using the API

Use the API to list the rule sets for a Load Balancer resource.

Run the ListRuleSets method to list the rule sets for a load balancer. See ListRuleSets for a complete description.

Getting Rule Set Details

Get the details of a rule set for a Load Balancer resource.

Use one of the following methods to get the details of a rule set for a selected load balancer.

To get the details of a rule set using the Console

Use the OCI Console to get the details of a rule set for a Load Balancer resource.

  1. Open the navigation menu, click Networking, and then click Load Balancers.

  2. Select the Compartment from the list.

    All load balancers and network load balancers in that compartment are listed in tabular form.

  3. (optional) Select a State from the list to limit the load balancers displayed to that state.

  4. (optional) Uncheck Load Balancer under Type to only display load balancers.

  5. Select the load balancer for which you want to create a rule set.

    The Load Balancer Details dialog box appears.

  6. Click Rule Sets under Resources.

    The Rule Sets list appears. All rule sets are listed in tabular form.

  7. Click the rule set whose details you want to get.

    The Rule Set Details page appears.

To get the details of a rule set using the CLI

Use the command line interface (CLI) to list the rule sets for a Load Balancer resource.

Enter the following command:

oci lb rule-set get --rule-set-name rule_set_name --load-balancer-id load_balancer_id [OPTIONS]

See the CLI online help for a list of options:

oci lb rule-set get --help

See oci lb rule-set get for a complete description of the command.

To get the details of a rule set using the API

Use the API to get the details of a rule set for a Load Balancer resource.

Run the GetRuleSet method to get the details of a rule set for a load balancer. See GetRuleSet for a complete description.

Editing Rule Sets

Update a rule set for a Load Balancer resource.

Use one of the following methods to edit and update a rule set for a selected load balancer.

To edit a rule set using the Console

Use the OCI Console to update a rule set for a Load Balancer resource.

  1. Open the navigation menu, click Networking, and then click Load Balancers.

  2. Select the Compartment from the list.

    All load balancers and network load balancers in that compartment are listed in tabular form.

  3. (optional) Select a State from the list to limit the load balancers displayed to that state.

  4. (optional) Uncheck Load Balancer under Type to only display load balancers.

  5. Select the load balancer for which you want to create a rule set.

    The Load Balancer Details dialog box appears.

  6. Click Rule Sets under Resources.

    The Rule Sets list appears. All rule sets are listed in tabular form.

  7. Click the rule set whose settings you want to edit.

    The Rule Set Details page appears.

  8. Click Edit.

    The Edit Path Route Set dialog box appears.

  9. Make your edits.

    See Creating Rule Sets for details on the rule set settings.

  10. Click Save Changes.

To edit a rule set using the CLI

Use the command line interface (CLI) to update a rule set for a Load Balancer resource.

Enter the following command:

oci lb rule-set update --rule-set-name rule_set_name --load-balancer-id load_balancer_id [OPTIONS]

See the CLI online help for a list of options:

oci lb rule-set update --help

See oci lb rule-set get for a complete description of the command.

To edit a rule set using the API

Use the API to update a rule set for a Load Balancer resource.

Run the UpdateRuleSet method to edit a rule set for a load balancer. See UpdateRuleSet for a complete description.

Deleting Rule Sets

Delete a rule set from a Load Balancer resource.

Run the DeleteRuleSet method to delete a rule set from a load balancer. See DeleteRuleSet for a complete description.

To delete a rule set using the Console

Use the OCI Console to delete a rule set from a Load Balancer resource.

  1. Open the navigation menu, click Networking, and then click Load Balancers.

  2. Select the Compartment from the list.

    All load balancers and network load balancers in that compartment are listed in tabular form.

  3. (optional) Select a State from the list to limit the load balancers displayed to that state.

  4. (optional) Uncheck Load Balancer under Type to only display load balancers.

  5. Select the load balancer whose rule set you want to delete.

    The Load Balancer Details dialog box appears.

  6. Click Rule Sets under Resources.

    The Rule Sets list appears. All rule sets are listed in tabular form.

  7. Click the rule set whose settings you want to edit.

    The Rule Set Details page appears.

  8. Click Delete.

    Alternatively, click the Actions icon (Actions icon) associated with the path route set you want to delete and click Delete.

  9. Confirm the deletion when prompted.

To delete a rule set using the CLI

Use the command line interface (CLI) to delete a rule set from a Load Balancer resource.

Enter the following command:

oci lb rule-set delete --rule-set-name rule_set_name --load-balancer-id load_balancer_id [OPTIONS]

See the CLI online help for a list of options:

oci lb rule-set delete --help

See oci lb rule-set delete for a complete description of the command.

To delete a rule set using the API

Use the API to delete a rule set from a Load Balancer resource.

Run the DeleteRuleSets method to delete a rule set from a load balancer. See DeleteRuleSets for a complete description.