21 Configuring Load Balancing Using the Proxy
dsconfig
or Oracle Unified Directory Services Manager (OUDSM).The following topics describe how to perform administration tasks:
Note:
-
To understand more about load balancing, see Overview of Load Balancing Using the Proxy.
-
You can configure load balancing using
dsconfig
or Oracle Unified Directory Services Manager (OUDSM).For more information about using either option, see Managing the Server Configuration Using dsconfigor Accessing Oracle Unified Directory Using OUDSM, respectively.
-
For information about setting up a load balancing deployment during installation, see "To Configure Simple Load Balancing" section in Installing Oracle Unified Directory.
21.1 Configuring Load Balancing Using the dsconfig
Command
The dsconfig
command is used to configure load balancing, to create a workflow element, and to create an algorithm and routes.
The following topics describe how to configure load balancing using dsconfig
command:
21.1.1 Configuring Load Balancing using the dsconfig Command
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. You can configure load balancing using the dsconfig
command.
To 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
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 Creating a Load Balancing Workflow Element.
- Create a load balancing algorithm. See Creating a Load Balancing Algorithm.
- Create one load balancing route for each load balancing workflow element. See Creating Load Balancing Routes.
21.1.2 Creating a Load Balancing Workflow Element
To configure load balancing, you must create a load balancing workflow element using the dsconfig create-workflow-element
command.
Follow the below given example to create a workflow element:
$ 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
.
21.1.3 Creating a Load Balancing Algorithm
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 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
.
21.1.4 Creating Load Balancing Routes
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 Modifying Load Balancing Properties.
21.1.5 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.
The following sections describe the different settings possible in a load-balancing deployment:
21.1.5.1 Modifying Load Balancing Properties
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 Configuring Load Balancing Using the dsconfig Command.
21.1.5.2 Setting the Priority in a Failover 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.
21.1.5.3 Setting the switch-back
Flag
After 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
21.1.5.4 Setting the Saturation Precision for the Optimal or Saturation Algorithm
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
21.1.5.5 Setting the Weight of a Proportional Algorithm
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.
21.1.5.6 Setting the Threshold for a Saturation Algorithm
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%.
21.1.5.7 Setting the Saturation Threshold Alert
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 Configuring Alerts and Account Status Notification Handlers.
21.1.5.8 Setting Client Connection Affinity
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 Creating a Network Group Quality of Service Policy.
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.
21.1.5.9 Deleting Load Balancing Elements
This section introduces you to the concept of deleting load balancing elements.
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.
21.2 Configuring Load Balancing Using OUDSM
If you have set up a proxy server instance without configuring either load balancing or distribution, you can configure load balancing by using OUDSM.
Before you begin, it is useful to understand the components comprise a load balancing deployment. For more information, see Configuration 1: Simple Load Balancing.
To configure load balancing by using OUDSM:
When you have configured load balancing, you can modify any aspect of the configuration on the OUDSM Configuration tab.