This chapter describes how to perform administration tasks that are related to load balancing using the proxy. dsconfig or Oracle Directory Services Manager (ODSM).
Note:
To understand more about load balancing, see Section 12.2, "Understanding Load Balancing Using the Proxy."
You can configure load balancing using dsconfig or Oracle Directory Services Manager (ODSM).
For more information about using either option, see Section 17.1, "Managing the Server Configuration Using dsconfig"or Section 16, "Accessing Oracle Unified Directory Using ODSM," respectively.
For information about setting up a load balancing deployment during installation, see "To Configure Simple Load Balancing" section in Installing Oracle Unified Directory.
This chapter contains the following sections.
dsconfig CommandTo forward client requests to remote LDAP servers using load balancing, you need the following elements:
A load balancing workflow element
A load balancing algorithm
A load balancing route, for each remote LDAP server
A load balancing workflow element can only have one load balancing algorithm. However, the same load balancing algorithm is used by all the load balancing routes in the deployment.
The following examples describe how to configure load balancing using the dsconfig command. All of the examples specify the proxy hostname (-h), the proxy admin port (-p), the bind DN (-D), and the bind password file (-j), and use the -X option to trust all certificates.
Create a load balancing workflow element. See Section 21.1.1, "Creating a Load Balancing Workflow Element."
Create a load balancing algorithm. See Section 21.1.2, "Creating a Load Balancing Algorithm."
Create one load balancing route for each load balancing workflow element. See Section 21.1.3, "Creating Load Balancing Routes."
To configure load balancing, you must create a load balancing workflow element using the dsconfig create-workflow-element command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
create-workflow-element \
--element-name load-bal-we1 \
--type load-balancing \
--set enabled:true
To create a load balancing workflow element, the type must be load-balancing. The name of the workflow element is defined by element-name, in this example load-bal-we1.
To determine how the requests will be forwarded in a load balancing deployment, you must configure the load balancing algorithm. The load balancing algorithm set determines how client requests will be dispatched across the pool of remote LDAP servers. The possible load balancing types are: failover, optimal, proportional, or saturation.
To create the load balancing algorithm, you must have a load balancing workflow element. See Section 21.1.1, "Creating a Load Balancing Workflow Element."
Create a load balancing algorithm using the dsconfig create-load-balancing-algorithm command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ create-load-balancing-algorithm \ --element-name load-bal-we1 \ --type failover
To create a load balancing algorithm, you must indicate the type as proportional, optimal, failover, or saturation. The name of the workflow element is defined by element-name, in this example load-bal-we1.
You should have one load balancing route per data source. Before you create a load balancing route, the load balancing workflow element and load balancing algorithm must already be created.
To create a load balancing route, use the dsconfig create-load-balancing-route command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ create-load-balancing-route \ --element-name load-bal-we1 \ --route-name load-bal-route1 \ --type failover \ --set workflow-element:proxy-we1 \ --set add-priority:1 \ --set bind-priority:2 \ --set compare-priority:2 \ --set delete-priority:1 \ --set extended-priority:2 \ --set modify-priority:1 \ --set modifydn-priority:1 \ --set search-priority:2
In this example, load-bal-route1 is the name of the new load balancing route, load-bal-we1 is the name of the existing load balancing workflow element, and proxy-we1 is the name of the LDAP proxy workflow element. The type must be the same as the one defined by the load balancing algorithm associated, in this case failover.
The properties set (in this case priority) are related to the type of load balancing created. For more information about the properties of the routes, linked to the algorithm type see Section 21.1.4, "Modifying Load Balancing Properties."
After a load balancing deployment has been set up, you can modify certain properties, such as the priority, weight, and saturation threshold. Most of these properties are changed at the load balancing route level.
You can modify the following load balancing properties, depending on the load balancing algorithm:
| Failover | Optimal | Proportional | Saturation | Search Filter |
|---|---|---|---|---|
| add-priority | alert-threshold | add-weight | alert-threshold | priority |
| bind-priority | saturation-precision* | bind-weight | priority | allowed-attributes |
| compare-priority | workflow-element | compare-weight | threshold | prohibited-attributes |
| delete-priority | delete-weight | saturation-precision* | workflow-element | |
| extended-priority | extended-weight | workflow-element | ||
| modify-priority | modify-weight | |||
| modifydn-priority | modifydn-weight | |||
| search-priority | search-weight | |||
| workflow-element | workflow-element | |||
| switch-back flag |
* saturation precision is a property of the LDAP server extension.
To modify load balancing route properties, use the dsconfig set-load-balancing-route-prop command.
New routes can be added on a running algorithm, or routes can be deleted or have their priorities modified without the need to restart the server.
Note:
You cannot modify the load balancing algorithm type.To change a failover load balancing deployment to a proportional one, for example, you must create a new load balancing deployment. See Section 21.1, "Configuring Load Balancing Using the dsconfig Command."
The following sections describe the different settings possible in a load-balancing deployment:
Section 21.1.4.1, "Setting the Priority in a Failover Algorithm"
Section 21.1.4.3, "Setting the Saturation Precision for the Optimal or Saturation Algorithm"
Section 21.1.4.4, "Setting the Weight of a Proportional Algorithm"
Section 21.1.4.5, "Setting the Threshold for a Saturation Algorithm"
In a load balancing deployment that uses the failover algorithm, you can modify the proxy workflow element to change the route that is used, as well as the priority of the route for a given operation type.
In a failover algorithm, a priority of 1 is the highest priority and indicates the main route that will be used for a specific operation type. A route with priority 2 (or more) is the secondary route used in case of failure on the primary route. The priority is set for each operation type. This means that a route with a priority of 1 for Add operations, can have a priority of 2 for Bind and Search operations.
For example, if the route load-bal-route1 was initially set as the main route with a priority of 1 for Add operations, but you now want to make it the backup route, you can set the priority to 2 using the following command.
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ set-load-balancing-route-prop \ --element-name load-bal-we1 \ --route-name load-bal-route1 --set add-priority: 2
Note:
If two routes have the same priority for a given operation type, the choice of the active route which treats the request is random.switch-back FlagAfter failover in a load balancing deployment, the backup route continues to handle all incoming requests, even after the priority server that had failed becomes available. Switch-back or failback to the primary route does not automatically occur unless the switch-back flag has been set to true. By default, the switch-back flag is set to false.
The switch-back flag is an advanced property. To set the switch-back flag to true, do the following:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
--advanced set-load-balancing-algorithm-prop \
--element-name load-bal-we1 \
--set switch-back:true
In a load balancing deployment that uses the optimal or the saturation algorithm, you can set the saturation precision level. The saturation precision is the delta between two saturation levels, and is used to determine the route with the lowest saturation level. By default, the saturation precision level is set to 5.
If you find that the saturation precision level is too low, and that the routes are changing too frequently, you can modify the saturation precision level as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
--advanced set-extension-prop \
--extension-name proxy1 \
--set saturation-precision:10
Once you have created a load balancing deployment using the proportional algorithm, you can modify the proxy workflow element to change the route used, as well as the weight of a route. The weight can be different for each operation type. The value of the weight should be 0 or more, were 0 indicates that the route will not be used for the specified operation.
Using the interactive mode of dsconfig, you can see that the following properties can be modified:
>>>> Configure the properties of the Proportional Load Balancing Route
Property Value(s)
---------------------------
1) add-weight 1
2) bind-weight 1
3) compare-weight 1
4) delete-weight 1
5) extended-weight 1
6) modify-weight 1
7) modifydn-weight 1
8) search-weight 1
9) workflow-element proxy-we1
For example, if you initially set all your routes to a weight of 1 on all operations, then all the servers will handle an equal ratio of operations. However, if you want a remote LDAP server to handle more search requests than the other servers in the deployment, then you can set its search-weight to a higher value, such as 5. To do so, use the following command:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ set-load-balancing-route-prop \ --element-name load-bal-we1 \ --route-name load-bal-route1 \ --set search-weight:5
Note:
To modify the weight for all operations, you must modify the weight for each operation individually.To modify load-bal-route1 to handle twice as many operations as the other route, you would set the weight of all operations to 2 (assuming the weight on the other route is set to 1). In other words, run the command as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ set-load-balancing-route-prop \ --element-name load-bal-we1 \ --route-name load-bal-route1 \ --set add-weight:2 \ --set bind-weight:2 \ --set compare-weight:2 \ --set delete-weight:2 \ --set extended-weight:2 \ --set modify-weight:2 \ --set modifydn-weight:2 \ --set search-weight:2
If the weight is set to 0 for any operations, the route will not perform the specified operation. For example, if add-weight is set to 0, then load-bal-route1 will not forward any add requests to the associated remote LDAP server. If all configured routes indicate a weight of 0 for a specific operation, that operation will not be supported.
Once you have created a load balancing deployment using the saturation algorithm, you can modify the proxy workflow element used, the priority of the route, the saturation threshold, and the saturation threshold alert.
With a saturation algorithm, requests are distributed based on two criteria: the priority of the server and the saturation threshold of the server. The saturation threshold is the limit at which the server is considered "maximized" and service may become degraded. In a load balancing deployment with saturation algorithm, requests are sent to the server with the highest priority (1) until the server reaches the saturation threshold indicated.
For example, if you indicate load-bal-route1 as the server with the highest priority, with a threshold of 80%, all requests will be sent to load-bal-route1 until its saturation threshold goes over 80%. Once it exceeds 80%, then requests are routed to the next server in the priority list.
>>>> Configure the properties of the Saturation Load Balancing Route
Property Value(s)
---------------------------
1) alert-threshold 85
2) priority 1
3) threshold 80
4) workflow-element proxy-we1
To modify the saturation threshold, use the following command:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ set-load-balancing-route-prop \ --element-name load-bal-we1 \ --route-name load-bal-route1 \ --set threshold:90
In this example, the saturation threshold has been set to 90%.
You can use the saturation threshold alert to specify at which point the system administrator will receive a notification indicating that the server has passed the saturation limit. Generally, the saturation threshold alert is set higher than the saturation limit to indicate if the saturation continues to increase past the saturation threshold (which may indicate a problem). You should set the alert with an acceptable buffer, because there may be a short delay in which saturation continues to increase slightly before requests are forwarded to another route.
To modify the saturation threshold, use the following command:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ set-load-balancing-route-prop \ --element-name load-bal-we1 \ --route-name load-bal-route1 \ --set alert-threshold:85
To perform preventative actions, you can set the saturation threshold alert to a value that is lower than the saturation threshold. (For example, if the main route is a set of load balanced servers, then you could add one or more servers to that set of servers as a preventive action.) This may imply receiving notifications even in cases where the saturation threshold is not reached. That is, a saturation threshold alert is sent, but the saturation limit drops and does not reach the saturation threshold. However, the requests will only be sent to the next priority route when the saturation threshold is reached.
For more information on setting the notification message, see Section 35.4, "Configuring Alerts and Account Status Notification Handlers."
When you define a client connection affinity, requests from a specified client connection are routed to the same server, bypassing the specified load balancing algorithm. Client connection affinity is set at the network group level.
To set client connection affinity, use the dsconfig create-network-group-qos-policy command. For more information, see Section 17.1.6.3, "Creating a Network Group Quality of Service Policy."
Example 21-1 Example of Client Connection Affinity Rejected
When you set the client connection affinity, the load balancing algorithm is bypassed if the defined weight constraints are respected.
For example, assume that the following routes are set with the following weights:
LB-route1: add=10, search= 0
LB-route2: add=0, search=10
It is clear that LB-route1 receives all the add requests, and LB-route2 receives all the search requests.
Assume that the load balancing deployment in this example is set with a client connection affinity of all-requests-after-first-write-request. If the load balancing deployment receives the following string of requests: Add, Search, Add, typically, the client connection affinity would send the Search request to the same route (LB-route1) as the first Add request. However, in this case, since Search requests are not allowed on LB-route1, the load balancing algorithm is not bypassed by the client affinity.
To delete a complete load balancing workflow (including workflow element, algorithm, and routes), you need only delete the load balancing workflow element. When you delete a load balancing workflow element, the associated load balancing algorithm and routes are silently deleted.
If you have set up a proxy server instance without configuring either load balancing or distribution, you can configure load balancing by using ODSM. Before you begin, it is useful to understand the components comprise a load balancing deployment. For more information, see Section 3.2.1, "Configuration 1: Simple Load Balancing."
To configure load balancing by using ODSM, perform the following steps:
Connect to the proxy server from ODSM, as described in Section 16.2, "Connecting to the Server Using ODSM."
Select the Home tab.
Under the Configuration item, select Set up Load Balancer.
On the Load Balancing: Backend Servers screen, complete the following information:
In the Load Balancing Name field, provide a name for this load balancing workflow element.
Click Add to provide the connection details of at least two replicated back end LDAP servers across which client requests will be balanced.
ODSM attempts to connect to these back end LDAP servers, to verify that they are accessible. If the connection attempt is unsuccessful, you are prompted to use the server details anyway, or to verify the connection details.
When you have added all the back end LDAP servers, click Next to continue.
On the Load Balancing: Options screen, complete the following information:
Select the Load Balancing Algorithm.
Depending on the load balancing algorithm you have selected, specify the relative weight or priority for each back end LDAP server.
For information about the load balancing algorithms, see Section 12.2, "Understanding Load Balancing Using the Proxy."
When you have specified the load balancing options, click Next to continue.
On the Load Balancing: Naming Contexts screen, click Add to specify at least one naming context, or suffix, that will be handled by this proxy instance.
When you have added all of the required naming contexts, click Next to continue.
On the Load Balancing Setup: Summary screen, review the load balancing configuration and click Finish to complete the configuration.
When you have configured load balancing, you can modify any aspect of the configuration on the ODSM Configuration tab.