5 Managing Origin-Server Pools

An origin server is a back-end server to which Oracle Traffic Director forwards requests that it receives from clients, and from which it receives responses to client requests. The origin servers could, for example, be Oracle WebLogic Server instances or Oracle iPlanet Web Server instances. A group of origin servers providing the same service or serving the same content is called an origin-server pool. You can define several such origin-server pools in a configuration, and then configure each virtual server in an Oracle Traffic Director instance to route client requests to a specific pool.

This chapter describes how to create and manage origin-server pools. It contains the following sections:

5.1 Creating an Origin-Server Pool

You can create an origin-server pool by using either Fusion Middleware Control or the WLST.

Note:

Before You Begin

Before you begin creating an origin-server pool, decide the following:

  • A unique name for the origin-server pool. Choose the name carefully; after creating an origin-server pool, you cannot change its name.

  • host:port combinations for the servers in the origin-server pool.

    Note:

    If the origin servers for which you want to create a pool are Oracle WebLogic Server managed servers in a cluster, it is sufficient to create the pool with any one of the managed servers as the origin server. You can then configure Oracle Traffic Director to discover the other managed servers in the pool dynamically. For more information, see Section 5.5, "Configuring an Oracle WebLogic Server Cluster as an Origin-Server Pool."

  • The communication protocol—HTTP/S or TCP—of the servers in the pool.

  • The address family that the servers in the origin-server pool use to listen for requests.

    The supported address families are:

Creating an Origin-Server Pool Using Fusion Middleware Control

To create an origin-server pool by using the Fusion Middleware Control, do the following:

  1. Log in to Fusion Middleware Control, as described in Section 1.7.2, "Displaying Fusion Middleware Control."

  2. Click the WebLogic Domain button at the upper left corner of the page.

  3. Select Administration > OTD Configurations.

    A list of the available configurations is displayed.

  4. Select the configuration for which you want to Origin-Server Pool.

  5. Click the Traffic Director Configuration In the Common Tasks pane.

  6. Select Administration > Server Pools.

    The Server Pools page is displayed. It shows a list of the server pools (HTTP/Sand TCP server pools) defined for the configuration.

  7. Select the Server Pool for which you want to configure.

  8. In the Common Tasks pane, click Create button.

    The Create Origin-Server Pool page is displayed.

    Figure 5-1 Create Origin-Server Pool

    Description of Figure 5-1 follows
    Description of ''Figure 5-1 Create Origin-Server Pool''

  9. Follow the on-screen prompts to complete creation of the origin-server pool by using the details—name, type, and so on—that you decided earlier.

    After the origin-server pool is defined, Click OK on the right top of the screen. The results screen of the New Origin-Server Pool displays a message confirming successful creation of the origin-server pool.

  10. The details of the origin-server pool that you just created are displayed on the Origin-Server Pools page.

    • In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Section 3.3, "Activate Configuration Changes."

Creating an Origin-Server Pool Using WLST

To create an origin-server pool, run the otd_createOriginServerPool command.

For example, the following command creates an origin-server pool origin-server-pool-1 containing origin server www.example.com:12345 in the configuration foo.

props = {}
props['configuration'] = 'foo'
props['origin-server-pool'] = 'origin-server-pool-1'
props['origin-server'] = 'www.example.com:12345'
otd_createOriginServerPool(props)

For more information about otd_createOriginServerPool, see WebLogic Scripting Tool Command Reference for Oracle Traffic Director.

Specifying an HTTP Forward Proxy Server

The otd_createOriginServerPool command takes proxy-server as an optional option which you can use to specify a HTTP forward proxy server to be associated with an origin server pool so that all member origin servers of the pool are communicated with via the configured HTTP forward proxy server. The type must be http or https.

For example:

props = {}
props['configuration'] = 'foo'
props['origin-server-pool'] = 'origin-server-pool-1'
props['origin-server'] = 'www.example.com:12345'
props['type'] = 'http'
props['proxy-server'] = 'proxy.example.com:12345'
otd_createOriginServerPool(props)

For more information about otd_createOriginServerPool, see WebLogic Scripting Tool Command Reference for Oracle Traffic Director.

5.2 Viewing a List of Origin-Server Pools

You can view a list of origin-server pools by using either Fusion Middleware Control or the WLST.

Note:

For information about invoking WLST, see Section 1.7.1, "Accessing WebLogic Scripting Tool."

Viewing a List of Origin-Server Pools Using Fusion Middleware Control

To view a list of origin-server pools by using the Fusion Middleware Control, do the following:

  1. Log in to Fusion Middleware Control, as described in Section 1.7.2, "Displaying Fusion Middleware Control."

  2. Click the WebLogic Domain button at the upper left corner of the page.

  3. Select Administration > OTD Configurations.

    A list of the available configurations is displayed.

  4. Select the configuration for which you want to view Origin-Server Pools.

  5. Click the Traffic Director Configuration In the Common Tasks pane.

  6. Select Administration > Server Pools.

    The Server Pools page is displayed.

  7. It shows a list of the origin-server pools defined for that configuration.

You can view the properties of an origin-server pool in detail by clicking on its name.

Viewing a List of Origin-Server Pools Using WLST

To view a list of origin-server pools, run the otd_listOriginServerPools command, as shown in the following example:

props = {}
props['configuration'] = 'foo'
otd_listOriginServerPools(props)

You can view the general properties and health-check settings of an origin-server pool by running the otd_getOriginServerPoolProperties and otd_getHealthCheckProperties commands respectively.

For more information about the WLST commands mentioned in this section, see WebLogic Scripting Tool Command Reference for Oracle Traffic Director.

5.3 Modifying an Origin-Server Pool

You can change the properties of an origin-server pool by using either Fusion Middleware Control or the WLST.

Note:

Changing the Properties of an Origin-Server Pool Using Fusion Middleware Control

To change the properties of an origin-server pool by using the Fusion Middleware Control, do the following:

  1. Log in to Fusion Middleware Control, as described in Section 1.7.2, "Displaying Fusion Middleware Control."

  2. Click the WebLogic Domain button at the upper left corner of the page.

  3. Select Administration > OTD Configurations.

    A list of the available configurations is displayed.

  4. Select the configuration for which you want to modify Origin-Server Pools.

  5. Click the Traffic Director Configuration In the Common Tasks pane.

  6. Select Administration > Server Pools.

    The Server Pools page is displayed.

  7. It shows a list of the origin-server pools that are defined for that configuration.

  8. Click the name of the origin-server pool that you want to modify.
    Click the Edit button in the common task pane

    The Origin Server Pool Settings page is displayed. On this page, you can do the following:

    • Change the network protocol—IPv4, IPv6, or SDP—for the servers in the pool.

    • Set a proxy server via the Connect to Origin Servers via Proxy Server section. This setting specifies a HTTP forward proxy server to be associated with an origin server pool so that all member origin servers of the pool are communicated with via the configured HTTP forward proxy server.

    • Change the load-balancing method that Oracle Traffic Director should use to distribute client requests to the pool.

      • Least connection count (default): When processing a request, Oracle Traffic Director assesses the number of connections that are currently active for each origin server, and forwards the request to the origin server with the least number of active connections.

        The least connection count method works on the premise that origin servers that are faster have fewer active connections, and so can take on more load. To further adjust the load distribution based on the capacities of the origin servers, you can assign relative weights to the origin servers.

        Note:

        WebSocket connections affect the least connection count load balancing algorithm because WebSocket connections are potentially long lasting and will be counted as active connections until they are closed.

      • Least response time: Though least connection count works well on most workloads, there could be situations when the response time of origin servers in a given pool for the same amount of load could differ. For example:

        - When origin servers of a given pool are deployed on machines that differ in hardware specification.

        - When some origin server nodes are used for other services.

        - When network connectivity for different nodes is not uniform or some network interfaces are more loaded than others.

        Least response time is useful in such scenarios because it is a dynamic weighted least connection algorithm and it calculates weights based on the response time. These weights are continuously adjusted based on how the origin servers respond. Least response time helps you avoid manual tuning of weights in the least connection algorithm.

      • Round robin: Oracle Traffic Director forwards requests sequentially to the available origin servers—the first request to the first origin server in the pool, the second request to the next origin server, and so on. After it sends a request to the last origin server in the pool, it starts again with the first origin server.

        Though the round-robin method is simple, predictable, and low on processing overhead, it ignores differences in the origin servers' capabilities. So, over time, requests can accumulate at origin servers that are significantly slow. To overcome this problem, you can use a weighted round-robin method, by assigning relative weights to the origin servers.

      • IP Hash: All the incoming requests from the same client IP address should go to the same content origination server. This load balancing policy is especially useful in the context of TCP Load Balancing, Oracle Traffic Director suggests customers to make use of this load balancing policy.

      For more information about assigning weights to origin servers, see Section 6.3, "Modifying an Origin Server."

    • Configure health-check settings. For more information, see Section 5.7, "Configuring Health-Check Settings for Origin-Server Pools."

    • Specify whether Oracle Traffic Director should dynamically discover Oracle WebLogic Server managed servers in a cluster. For more information, see Section 5.5, "Configuring an Oracle WebLogic Server Cluster as an Origin-Server Pool."

    Note:

    You can add, modify, and remove origin servers in the pool, by selecting Origin Servers in the navigation pane. For more information, see Chapter 6, "Managing Origin Servers."

  9. Specify the parameters that you want to change.

    On-screen help and prompts are provided for all of the parameters.

    When you change the value in a field or tab out of a text field that you changed, the Save button near the upper right corner of the page is enabled.

    At any time, you can discard the changes by clicking the Cancel button.

  10. After making the required changes, click OK.

    • A message, confirming that the updated configuration was saved, is displayed in the Console Messages pane.

    • In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Section 3.3, "Activate Configuration Changes."

Changing the Properties of an Origin-Server Pool Using WLST

  • To change the network protocol and load-balancing method for an origin-server pool, run the otd_setOriginServerPoolProperties command.

    For example, the following command changes the load-balancing method for the origin-server pool origin-server-pool-1 in the configuration foo to the least connection count method.

    props = {}
props['configuration'] = 'foo'
props['origin-server-pool'] = 'origin-server-pool-1'
props['load-distribution'] = 'least-connection-count'
otd_setOriginServerPoolProperties(props)

  • To change the health-check parameters for an origin-server pool, run the otd_setHealthCheckProperties command.

    For example, the following command changes the size of the response body for servers in the origin-server pool origin-server-pool-1 of the configuration foo to 4096 bytes.

    props = {}
props['configuration'] = 'foo'
props['origin-server-pool'] = 'origin-server-pool-1'
props['response-body-match-size'] = '4096'
otd_setHealthCheckProperties(props)

For a list of the properties that you can set or change by using the otd_setOriginServerPoolProperties and otd_setHealthCheckProperties commands, see WebLogic Scripting Tool Command Reference for Oracle Traffic Director.

5.4 Deleting an Origin-Server Pool

You can delete an origin-server pool by using either Fusion Middleware Control or the WLST.

Note:

Deleting an Origin-Server Pool Using Fusion Middleware Control

To delete an origin-server pool by using the Fusion Middleware Control, do the following:

  1. Log in to Fusion Middleware Control, as described in Section 1.7.2, "Displaying Fusion Middleware Control."

  2. Click the WebLogic Domain button at the upper left corner of the page.

  3. Select Administration > OTD Configurations.

    A list of the available configurations is displayed.

  4. Select the configuration for which you want to delete Origin-Server Pools.

  5. Click the Traffic Director Configuration In the Common Tasks pane.

  6. Select Administration > Server Pools.

    The Server Pools page is displayed.

  7. It shows a list of the origin-server pools that are defined for that configuration.

  8. Select the pool which you want to delete from the list available.

  9. Click the Delete button in the common task pane.

    • If the origin-server pool is associated with one or more routes in virtual servers, a message is displayed indicating that you cannot delete the pool.

    • If the origin-server pool is not associated with any virtual server, a prompt to confirm the deletion is displayed.

  10. Click Yes.

    The origin-server pool is deleted.

Deleting an Origin-Server Pool Using WLST

To delete an origin-server pool, run the otd_deleteOriginServerPool command, as shown in the following example:

props = {}
props['configuration'] = 'foo'
props['origin-server-pool'] = 'origin-server-pool-1'
otd_deleteOriginServerPool(props)

For more information about otd_deleteOriginServerPool, see the WebLogic Scripting Tool Command Reference for Oracle Traffic Director.

5.5 Configuring an Oracle WebLogic Server Cluster as an Origin-Server Pool

Note:

Oracle Traffic Director has built-in support for some common functionality offered by the WebLogic Server plug-in. Hence Oracle Traffic Director does not require any other plug-in to inter-operate with WebLogic Server.

If you want to create an origin-server pool that represents a cluster of Oracle WebLogic Server managed servers, you need not specify each managed server in the cluster as an origin server. It is sufficient to specify any one of the managed servers as the sole origin server in the pool. You can configure Oracle Traffic Director to discover the presence of other Oracle WebLogic Server instances in the cluster dynamically, and distribute client requests to the managed server that is configured as an origin server and to the dynamically discovered managed servers in the same cluster.

So when dynamic discovery is enabled, if any of the managed servers in the cluster is stopped, added, or removed, you need not update the definition of the origin-server pool. However, for detecting changes in the Oracle WebLogic Server cluster, Oracle Traffic Director sends health-check requests at a specified interval, which causes some overhead.

5.5.1 How Dynamic Discovery Works

When dynamic discovery is enabled for an origin-server pool, Oracle Traffic Director discovers the remaining Oracle WebLogic Server managed servers in the cluster, by doing the following:

  1. When an Oracle Traffic Director instance starts, it checks whether the origin servers specified in the pool are Oracle WebLogic Server managed servers and whether the servers belong to a cluster, by sending an HTTP health-check request to each configured origin server.

    The origin server's response indicates whether the server is an Oracle WebLogic Server managed server. If the origin server is an Oracle WebLogic Server managed server that belongs to a cluster, the response also includes a list of the managed servers in the cluster.

  2. Oracle Traffic Director uses the information in the response from the origin server to update the configuration with the discovered managed servers.

    The dynamically discovered origin servers inherit all of the properties—weight, maximum connections, and so on—that are specified for the configured origin server.

  3. Subsequently, at each health-check interval (default: 30 seconds) configured for the origin-server pool, Oracle Traffic Director attempts to detect changes in the cluster, by sending dynamic-discovery health-check requests to the Oracle WebLogic Server instances that are configured as origin servers in the pool.

    If the response indicates a change—removal or addition of a managed server—in the cluster since the previous health check, Oracle Traffic Director updates the configuration with the new set of dynamically discovered origin servers.

Note:

  • Dynamically discovered origin servers are not stored permanently in the origin-server pool definition of the instance's configuration. So when you restart an Oracle Traffic Director instance, the process of dynamic discovery starts afresh.

  • The HTTP request type that Oracle Traffic Director sends for dynamic discovery is the health-check request type that is currently configured for the origin-server pool—OPTIONS (default) or GET. For more information, see Section 5.7, "Configuring Health-Check Settings for Origin-Server Pools."

5.5.2 Enabling Dynamic Discovery

When you create an origin-server pool, dynamic discovery of Oracle WebLogic Server managed servers in a cluster is not enabled by default. You can enable dynamic discovery by using either Fusion Middleware Control or the WLST.

Note:

Enabling Dynamic Discovery Using Fusion Middleware Control

To enable dynamic discovery of WebLogic Server managed servers in a cluster by using the Fusion Middleware Control, do the following:

  1. Log in to Fusion Middleware Control, as described in Section 1.7.2, "Displaying Fusion Middleware Control."

  2. Click the WebLogic Domain button at the upper left corner of the page.

  3. Select Administration > OTD Configurations.

    A list of the available configurations is displayed.

  4. Select the configuration for which you want to enable dynamic discovery.

  5. Click the Traffic Director Configuration In the Common Tasks pane.

  6. Select Administration > Server Pools.

    The Server Pools page is displayed.

  7. It shows a list of the origin-server pools that are defined for that configuration.

  8. Select the pool which you want to enable dynamic discovery from the list available.

  9. Go to the Advanced Settings section of the page.

  10. Under the Health Check subsection, make sure that the Protocol is HTTP, select the Dynamic Discovery check box.

  11. Click OK button on the top right corner of the window.

    Note:

    If the current health-check protocol is TCP, an error message is displayed indicating that the protocol must be changed to HTTP in order to enable dynamic discovery.

    A message is displayed in the Console Message pane confirming that the updated health-check settings were saved.

Enabling Dynamic Discovery Using WLST

To enable dynamic discovery of Oracle WebLogic Server managed servers in a cluster, run the otd_setHealthCheckProperties command.

For example, the following command enables dynamic discovery of managed servers in the Oracle WebLogic Server cluster that the origin-server-pool-1 origin-server pool represents.

props = {}
props['configuration'] = 'foo'
props['origin-server-pool'] = 'origin-server-pool-1'
props['dynamic-server-discovery'] = '4096'
otd_setHealthCheckProperties(props)

Note:

If the current health-check protocol is TCP, an error message is displayed indicating that the protocol must be changed to HTTP in order to enable dynamic discovery.

For more information about otd_setHealthCheckProperties, see WebLogic Scripting Tool Command Reference for Oracle Traffic Director.

5.6 Configuring a Custom Maintenance Page

It configures Oracle Traffic Director to serve a custom response code, and HTML page, when back-end servers maintenance required. Providing this type of message is better than having a gateway time-out, or creating other resources to host static content.

When maintenance is enabled for an origin server pool, then:

  • All the requests to Oracle Traffic Director, are aborted with a 503 response code, if both response-code and response-file are not configured.

  • All the requests to Oracle Traffic Director, are aborted with response-code value as the response code, if only response-code is specified.

  • All the requests to Oracle Traffic Director, are not aborted, but are responded to with a response-file content and response-code value as the response code, if both are specified.

  • Health-check is disabled on its origin servers.

When maintenance is not enabled for an origin server pool but no origin servers are configured or enabled, then:

  • All the requests to Oracle Traffic Director, are aborted with a 503 response code.

  • Health-check is disabled on its origin servers.

Monitoring of Statistics for Origin Server Pool in Maintenance

If the origin-server pool is in a maintenance state, there will be no statistics for the origin server pool and the origin servers. Statistics will be available only for active origin server pools and active origin servers.

Enabling or Disabling Maintenance for an Origin-Server Pool Using WLST

To enable maintenance for an origin-server pool, run the otd_enableOriginServerPoolMaintenance command.

For example, the following command enables maintenance for the origin-server-pool-1 origin-server pool, and specifies a response-code of 503. This command takes response-code and response-file as optional properties. A response-code of 200 is not allowed without a response-file.

props = {}
props['configuration'] = 'foo'
props['origin-server-pool'] = 'origin-server-pool-1'
props['response-code'] = '503'
otd_enableOriginServerPoolMaintenance(props)

To disable maintenance, use the otd_disableOriginServerPoolMaintenance command:

props = {}
props['configuration'] = 'foo'
props['origin-server-pool'] = 'origin-server-pool-1'
otd_disableOriginServerPoolMaintenance(props)

To return the enabled, response-file and response-code properties for the origin-server pool, use the otd_getOriginServerPoolMaintenanceProperties command:

props = {}
props['configuration'] = 'foo'
props['origin-server-pool'] = 'origin-server-pool-1'
otd_getOriginServerPoolMaintenanceProperties(props)

For information about otd_enableOriginServerPoolMaintenance, otd_disableOriginServerPoolMaintenance, and otd_getOriginServerPoolMaintenanceProperties, see WebLogic Scripting Tool Command Reference for Oracle Traffic Director.

5.7 Configuring Health-Check Settings for Origin-Server Pools

To ensure that requests are distributed to only those origin servers that are available and can receive requests, Oracle Traffic Director monitors the availability and health of origin servers by sending health-check requests to all of the origin servers in a pool.

You can configure health-check parameters for an origin-server pool by using either Fusion Middleware Control or the WLST.

Note:

For information about invoking WLST, see Section 1.7.1, "Accessing WebLogic Scripting Tool."

When Does Oracle Traffic Director Send Health-Check Requests?

When an Oracle Traffic Director instance starts, it performs an initial health check for all the origin servers in all of the configured origin-server pools.

If the initial health check indicates that an origin server is healthy, Oracle Traffic Director sends further health-check requests to an origin server only in the following situations:

If a health check—either initial or subsequent—indicates that an origin server is not available, Oracle Traffic Director repeats the health check at the specified health-check interval.

Configurable Health-Check Settings

Table 5-1 lists the health-check settings that you can configure for each origin-server pool in a configuration.

Table 5-1 Health-Check Parameters

Parameter Default Value

The type of connection—HTTP, TCP, or COMMAND—that Oracle Traffic Director should attempt with the origin server to determine its health.

  • TCP connection: Oracle Traffic Director attempts to open a TCP connection to each origin server.

  • HTTP request: Oracle Traffic Director sends an HTTP GET or OPTIONS request to each origin server in the pool, and checks the response to determine the availability and health of the origin server.

    Note: If you want to enable dynamic discovery of Oracle WebLogic Server managed servers in a cluster, then the health-check connection type must be set to HTTP.

  • COMMAND: Oracle Traffic Director uses an external executable created by the customer to monitor the health of specific origin servers. This mechanism is useful when you want to have a protocol-level health check monitor for the origin servers, which provide different services.

HTTP

The frequency at which health-check requests should be sent.

30 seconds

The duration after which a health-check request should be timed out if no response is received from the origin server.

5 seconds

The number of times that Oracle Traffic Director should attempt to connect to an origin server in the pool, before marking it as unavailable.

5

The HTTP request method—GET or OPTIONS—that should be sent.

OPTIONS

The URI that should be sent for HTTP requests.

/

The HTTP response codes that Oracle Traffic Director can accept as indicators of a healthy origin server.

By default, Oracle Traffic Director accepts response codes from 1xx to 4xx as indicators of a healthy origin server.

  

For HTTP GET health-check requests, a regular expression for the response body that Oracle Traffic Director can accept as the indicator of a healthy origin server

  

For HTTP GET health-check requests, the maximum number of bytes in the response body that Oracle Traffic Director should consider when comparing the response body with the specified acceptable response body.

2048

When Is an Origin Server Considered Available and Healthy?

If the configured health-check connection type is TCP, an origin server is considered available if the connection is successfully established, indicating that the server is actively listening on its service port.

If the configured health-check connection type is HTTP, an origin server is considered available and health when all of the following conditions are fulfilled:

  • There is no error while sending the HTTP request.

  • The response is received before timeout period is reached.

  • The status code in the response matches any of the acceptable response codes, if specified.

    By default, Oracle Traffic Director accepts response codes from 1xx to 4xx as indicators of a healthy origin server.

  • The response body matches the acceptable response body, if specified.

Configuring Health-Check Settings for Origin Servers Using Fusion Middleware Control

To view and change health-check settings origin servers in a pool by using the Fusion Middleware Control, do the following:

  1. Log in to Fusion Middleware Control, as described in Section 1.7.2, "Displaying Fusion Middleware Control."

  2. Click the Configurations button that is situated at the upper left corner of the page.

    A list of the available configurations is displayed.

  3. Select the configuration for which you want to view or change origin-server health-check settings.

  4. In the navigation pane, expand Origin-Server Pools, and select the origin-server pool for which you want to view or change health-check settings.

    The Origin-Server Pools page is displayed. It shows a list of the origin-server pools that are defined for the configuration.

  5. Click the name of the origin-server pool that you want to modify.

    The Server Pool Settings page is displayed.

  6. Go to the Advanced Settings section of the page.

  7. Specify the parameters that you want to change.

    On-screen help and prompts are provided for all of the parameters.

    When you change the value in a field or tab out of a text field that you changed, the Save button near the upper right corner of the page is enabled.

    At any time, you can discard the changes by clicking the Reset button.

  8. After making the required changes, click Save.

Configuring Health-Check Settings for Origin Servers Using WLST

  • To view the current health-check settings for an origin-server pool in a configuration, run the otd_getHealthCheckProperties command, as shown in the following example:

    props = {}
props['configuration'] = 'foo'
props['origin-server-pool'] = 'origin-server-pool-1'
otd_getHealthCheckProperties(props)

protocol=HTTP
interval=30
timeout=5
failover-threshold=3
request-method=OPTIONS
request-uri=/
response-body-match-size=2048
dynamic-server-discovery=false

  • To change the health-check settings for an origin-server pool in a configuration, run the otd_setHealthCheckProperties command.

    For example, the following command changes the health-check interval to 60 seconds and the health-check timeout period to 10 seconds for the origin-server pool origin-server-pool-1 in the configuration foo.

    props = {}
props['configuration'] = 'foo'
props['origin-server-pool'] = 'origin-server-pool-1'
props['interval'] = '60'
props['timeout'] = '10'
otd_setHealthCheckProperties(props)

For more information about the commands mentioned in this section, see WebLogic Scripting Tool Command Reference for Oracle Traffic Director.

5.7.1 Using an External Health-Check Executable to Check the Health of a Server

Oracle Traffic Director supports a generic health check hook-up mechanism, so that you can write your own health check programs/scripts to monitor the health of specific origin servers. An external executable is especially useful for a protocol-level health check monitor for the origin servers.

If you configure Oracle Traffic Director to use an external executable to check the health of a server, Oracle Traffic Director periodically invokes the executable and passes certain parameters to it as arguments and environment variables. If the executable successfully returns a status code 0 before a timeout, Oracle Traffic Director sets the server's status to online. If the executable returns a value other than zero or a timeout occurs before the execution ends, Oracle Traffic Director immediately sets the server status to offline without retrying, and terminates the execution in the timeout case. There are different reasons why the executable could return a non-zero status code, including a core dump, signal termination, or the logic of external executable itself. Oracle Traffic Director marks the server offline whenever the return status is non-zero.

Also, Oracle Traffic Director captures the standard output and standard error from the executable and logs the messages into the event log (server log).

The external executable handles the actual health check jobs, including establishing connection to the origin server, sending/receiving request/response, dealing with SSL (if applicable), retry logic (if required), and so on. The executable is expected to exit with a status 0 after it finishes the health check operation and wants to set the server status to online. If the executable wants to have some messages logged in the event log, it should print those messages to standard output.

5.7.1.1 Configuring Health-Check Settings to Use an External Executable

To configure the health-check settings to use an external executable for an origin-server pool in a configuration, run the otd_setHealthCheckProperties command.

For example, the following command sets the health-check method to command, and specifies a path of /path/myhcscript for the external health-check executable. The interval, and timeout properties are also specified.

props = {}
props['configuration'] = 'foo'
props['origin-server-pool'] = 'origin-server-pool-1'
props['protocol'] = 'command'
props['interval'] = '60'
props['timeout'] = '10'
props['command'] = '/path/myhcscript'
otd_setHealthCheckProperties(props)

Note:

In case of an HTTP type of origin server pool, the COMMAND health check protocol is not considered if:

  • the origin server type is UNDETECTED or,

  • the origin server type is WLS and dynamic discovery is set.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the activate command.

5.7.1.2 Parameters to the External Health Check Executable

Oracle Traffic Director passes parameters to the external health check executable in two ways. In particular, Oracle Traffic Director passes the origin server host, origin server port, and timeout value via arguments, and passes all the existing environment variables as well as ORACLE_HOME, INSTANCE_HOME, INSTANCE_NAME, DOMAIN_HOME, and OTD_LOG_LEVEL as environment variables. The argument parameters are passed in the format of command line options, as shown in the following example command:

/path/myhcscript -h server1.myserver.com -p 389 -t 10

Where, -h, -p, and -t stand for host, port, and timeout respectively.

Table 5-2 Argument Parameters

Option Meaning

-h

Origin server host.

-p

Origin server port.

-t

Health-check timeout.

You can pass other parameters to the external executable by specifying additional option arguments in the parameter command:

/path/myhcscript --secure -d /dbpath

Correspondingly, Oracle Traffic Director passes those additional arguments to the external executable:

/path/myhcscript --secure -d /dbpath -h server1.myserver.com -p 389 -t 10

Oracle Traffic Director does not automatically pass the origin server port type (for example, LDAP over SSL) to the executable. If the type information is needed in the executable, you can specify the type information in the command string as an additional argument (as shown in the example above) or have the type hard-coded or obtained from other resource (for example, its own configuration file or environment variable) in their health check program/script.

Furthermore, it is recommended that the external executable takes the timeout value into account and tries to complete execution and return status before timeout. If timeout occurs but execution is not complete, Oracle Traffic Director terminates the process and set the server status to offline.

5.7.1.3 Logging

Oracle Traffic Director passes the configured logging level to the external program via the environment variable OTD_LOG_LEVEL, and the value of the environment variable is an integer. In the external executable, you can customize the amount of logging messages based on the logging level. The following table defines the mapping between the Oracle Traffic Director logging levels and the argument values.

Table 5-3 Mapping Oracle Traffic Director Logging Levels and Argument Values

Value Oracle Traffic Director Logging Level

0

NOTIFICATION:1 or higher

1

TRACE:1

2

TRACE:16

3

TRACE:32

Oracle Traffic Director logs contents in both standard output and the standard error of the external executable in a single log entry in the server log. If the exit status of the command health check script is 0, the messages are logged at TRACE:1 level. Otherwise, standard output is logged at NOTIFICATION:1 level and the standard error is logged at WARNING:1 level.