This chapter describes how to configure the server elements that are specific to a proxy instance. Note that many of these elements are configured automatically when you configure a load balancing or distribution topology while setting up a proxy instance.
This chapter covers the following topics:
For more information about the dsconfig
command, see Section 14.1, "Managing the Server Configuration With dsconfig
".
For more information about ODSM, see Chapter 18, "Accessing Oracle Unified Directory by Using Oracle Directory Services Manager."
dsconfig
This section describes the procedures to manage a proxy configuration with the dsconfig
command, and covers the following topics:
Section 15.1.1, "Configuring Communication With Remote LDAP Servers"
Section 15.1.7, "Configuring Global Indexes By Using the Command Line"
This section describes how to configure communication between a proxy instance and one or more remote LDAP servers. The section covers the following topics:
Section 15.1.1.1, "Components of Communication with the Remote Server"
Section 15.1.1.3, "Configuring Proxy LDAP Workflow Elements"
The following two elements are involved in communication between a proxy instance and a remote LDAP server:
LDAP Server Extension: This element manages the connectivity with the remote server by periodically checking the response from the remote peer and providing valid connections maintained by the connection pool.
Proxy LDAP Workflow Element: This element retrieves the connections from the LDAP server extension element and executes operations received from the user as defined in the configured mode.
This section describes how to configure the LDAP server extensions required to communicate with the remote LDAP server. The section covers the following topics:
Section 15.1.1.2.1, "To Display the Existing LDAP Server Extensions"
Section 15.1.1.2.2, "To Display LDAP Server Extension Properties"
Section 15.1.1.2.3, "To View Advanced LDAP Server Extension Properties"
Section 15.1.1.2.5, "To Modify the Properties of an LDAP Server Extension"
Section 15.1.1.2.6, "To Modify the Advanced Properties of an LDAP Server Extension"
Section 15.1.1.2.7, "LDAP Data Source Monitoring Connection Properties"
To display all the LDAP server extensions configured for a proxy instance, use the dsconfig list-extensions
command, as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ list-extensions
Extension : Type -----------:--------------------- gi-catalog : global-index-catalog proxy1 : ldap-server proxy2 : ldap-server
The extensions with type ldap-server
are the LDAP server extensions. You should have one LDAP server extension for each remote LDAP server.
To view the properties of a specific LDAP server extension, use the dsconfig get-extension-prop
command, as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
get-extension-prop --extension-name proxy1
Property : Value(s)
---------------------------:---------
enabled : true
remote-ldap-server-address : server1.example.com
remote-ldap-server-port : 1389
The following properties are displayed:
enabled
indicates if the LDAP server extension is enabled (true
) or not (false
)
remote-ldap-server-address
and remote-ldap-server-port
indicate the address and port of the remote LDAP server to which requests will be forwarded
monitoring-bind-dn
and monitoring-bind-password
These properties are displayed only if the --advanced
option is specified. They provide the credentials of the user that the extension will use to perform monitoring of the data source. If these properties have not been changed from the default, they are not displayed. Monitoring is then performed anonymously. To configure these properties, see Section 29.5, "Monitoring the Server With LDAP."
To view all the LDAP server extension properties, use the dsconfig --advanced get-extension-prop
command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
--advanced get-extension-prop --extension-name proxy1
Properties similar to the following are displayed.
Property Value(s) ---------------------------------------------------------------------- 1) enabled true 2) java-class com.sun.dps.server.workflowelement .proxyldap.LDAPServerExtension 3) monitoring-check-interval 30000 4) monitoring-connect-timeout 5000 5) monitoring-inactivity-timeout 120000 6) monitoring-ping-timeout 5000 7) pool-increment 5 8) pool-initial-size 10 9) pool-max-size 1000 10) pool-max-write 0 11) pool-release-connection-interval 300000 12) pool-use-max-write false 13) proxied-auth-use-v1 false 14) remote-ldap-server-address localhost 15) remote-ldap-server-connect-timeout 10000 16) remote-ldap-server-port 1389 17) remote-ldap-server-read-only false 18) remote-ldap-server-read-timeout 10000 19) remote-ldap-server-ssl-policy never 20) remote-ldap-server-ssl-port 636 21) saturation-precision 5 22) ssl-client-alias - 23) ssl-key-manager-provider - 24) ssl-trust-all false 25) ssl-trust-manager-provider -
Note:
Most of the advanced properties (except SSL properties) are set by default when the LDAP server extensions are created.
To modify these values, see Section 15.1.1.2.5, "To Modify the Properties of an LDAP Server Extension."
For information about the monitoring properties, see Section 15.1.1.2.7, "LDAP Data Source Monitoring Connection Properties." For information about the SSL (security) properties, see Chapter 21, "Configuring Security Between the Proxy and the Data Source."
To create a new LDAP server extension, use the dsconfig create-extension
command, as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
create-extension \
--extension-name DS-proxy5 \
--type ldap-server \
--set enabled:true \
--set remote-ldap-server-address:DS5-hostname
--set remote-ldap-server-port:1389
The extension type
must be ldap-server
. The name of the new extension is defined by extension-name
, in this example DS-proxy5
.
You must also specify the name of the remote LDAP server with which this extension is associated (remote-ldap-server-address
). You can specify either the hostname or the IP address of the remote LDAP server.
If you do not specify a remote-ldap-server-port
, the default LDAP port of 1389 is assumed.
To modify the LDAP server extension properties, use the set-extension-prop
subcommand. This subcommand enables you to do the following:
set whether the LDAP server extension is enabled (true
) or not (false
)
modify the remote LDAP directory server address and port (remote-ldap-server-address
and remote-ldap-server-port
)
set the credentials of the user that the extension will use to perform monitoring of the data source (monitoring-bind-dn
and monitoring-bind-password
). If left blank, the monitoring will be performed anonymously, which is the default.
For example, a typical operation would be to change the remote LDAP server used. To do so, you need to set the new remote LDAP server address and port, as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
set-extension-prop \
--extension-name DS-proxy5 \
--set remote-ldap-server-address:DS5-hostname \
--set remote-ldap-server-port:3388
To modify advanced LDAP server extension properties, see Section 15.1.1.2.6, "To Modify the Advanced Properties of an LDAP Server Extension."
You can configure the following advanced properties:
pool-increment
The increment by which the size of a connection pool is increased or decreased. If the remote-ldap-server-ssl-policy
property is set to user
, two pools of connections are created and the incremental change in size of each pool is set to pool-increment
.
The default value is 5 connections.
pool-initial-size
The initial size of a connection pool. This is the initial number of connections to be created when a pool is initialized. Note that pool-initial-size
is also minimum size of a pool.
The default value is 10 connections.
If the remote-ldap-server-ssl-policy
property is set to user
, two pools of connections are created and the initial size, and minimum size, of each pool is set to pool-initial-size
. Therefore there can initially be twice the total number of connections indicated in pool-initial-size
. For more information, see Section 21.2, "Modes of Secure Connection."
pool-max-size
The maximum size of a connection pool. This is the maximum number of connections that a pool can allocate. If the remote-ldap-server-ssl-policy
property is set to user
, two pools of connections are created and the maximum size of each pool is set to pool-max-size
.
The default value is 1000 connections.
pool-max-write
The maximum number of write connections that a connection pool can allocate at the same time. This is an integer. This parameter is taken into account only if the pool-use-max-write
parameter is set to true
.
The default value is 0 connections.
pool-release-connection-interval
The time after which a connection is considered by the proxy to be unused if no traffic has been sent on it. This reduces the size of the pool of connections, if the pool has been previously increased. If the number of unused connections is greater than pool-increment
, then the size of the pool is reduced by pool-increment
. This means that unused connections are closed and are removed from the pool.
The default value is 300000 milliseconds (30 seconds).
pool-use-max-write
If this boolean is set to true, the pool-max-write
parameter is taken into account, otherwise it is not. By default, pool-use-max-write
is set to false.
proxied-auth-use-v1
When using the proxy authorization control mode, the default version of the control is v2. To use an older version for compatibility reasons, set proxied-auth-use-v1
to true. By default, proxied-auth-use-v1
is set to false. For more information about controls, see Appendix B, "Supported Controls and Operations."
remote-ldap-server-read-timeout
The timeout for reads. If the timeout is reached before the remote LDAP server sends back a response, an error is returned by the proxy to the client. By default, this value is 10000 milliseconds (10 seconds).
saturation-precision
The saturation precision is used in calculating the saturation threshold. Since the saturation limit can vary as requests are sent and received, the saturation precision indicates how much change the saturation should get before the saturation is taken into account. By default the saturation can vary by 5% before it is taken into account.
The monitoring properties are described in Section 15.1.1.2.7, "LDAP Data Source Monitoring Connection Properties."
The SSL properties are security features. For information about these properties, see Chapter 21, "Configuring Security Between the Proxy and the Data Source."
To modify the advanced LDAP server extension properties, use the set-extension-prop --advanced
command.
Note:
These advanced properties are set by default and typically are not modified.
An example of an advanced property that you may want to change is the pool-max-size
. If you have a powerful remote LDAP server and you have configured the proxy so that it receives a maximum of requests, you can increase the pool-max-size
as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
set-extension-prop --advanced \
--extension-name DS-proxy5 \
--set pool-max-size:2000
Using the dsconfig --advanced
command for the LDAP server extension, you can view or change the following monitoring properties. All properties relate to proactive monitoring unless otherwise specified.
monitoring-check-interval
The monitoring check interval. This is the interval in milliseconds at which the proxy proactive monitoring checks the data source. The default value is 30000 milliseconds (30 seconds).
monitoring-connect-timeout
The maximum time in milliseconds after which the proactive monitoring facility will stop attempting to connect to the remote LDAP server. The default value is 5000 milliseconds (5 seconds). 0 means unlimited.
monitoring-inactivity-timeout
The time interval in milliseconds after which an idle connection is regularly checked to avoid connection closure by the remote server. The value of this parameter must be superior to the monitoring-check-interval
. The default value is 120000 milliseconds (120 seconds).
monitoring-ping-timeout
The maximum time in milliseconds the proactive monitoring attempts to ping the remote server. The default value is 5000 milliseconds (5 seconds).
remote-ldap-server-read-timeout
The maximum time in milliseconds during which the LDAP Server Extension waits for a response from the remote server before the connection is regarded as having failed. 0 means unlimited.
remote-ldap-server-connect-timeout
The maximum time in milliseconds during which monitoring attempts to connect to the remote server before the connection is regarded as having failed. 0 means unlimited. The default is 10000 milliseconds (10 seconds).
This section describes how to configure the LDAP proxy workflow elements required to communicate with the remote LDAP server. The section covers the following topics:
Section 15.1.1.3.1, "To Display the Existing Proxy LDAP Workflow Elements"
Section 15.1.1.3.2, "To Display the Properties of a Proxy LDAP Workflow Element"
Section 15.1.1.3.3, "To Create a Proxy LDAP Workflow Element"
Section 15.1.1.3.4, "To Modify the Properties of a Proxy LDAP Workflow Element"
To display all the workflow elements configured on a particular proxy server instance, use the dsconfig list-workflow-elements
command, as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ list-workflow-elements Workflow Element : Type : enabled -----------------:--------------------:-------- adminRoot : ldif-local-backend : true load-bal-we1 : load-balancing : true proxy-we1 : proxy-ldap : true proxy-we2 : proxy-ldap : true
The proxy workflow elements are the ones with the type proxy-ldap
.
To view the proxy workflow element properties, use the dsconfig get-workflow-element-prop
command, as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
get-workflow-element-prop --element-name proxy-we1
Property : Value(s) --------------------------------------:-------------------- client-cred-mode : use-client-identity enabled : true ldap-server-extension : proxy1 remote-ldap-server-bind-dn : - remote-ldap-server-bind-password : - use-proxy-auth : false
The following properties are displayed:
client-cred-mode
indicates how the proxy connects to the remote LDAP server. In this example, the status is use-client-identity
, which means that the proxy will connect to the remote LDAP server with the same credentials that the client used to connect to the proxy. This is the default mode.
For more information, see Chapter 21, "Configuring Security Between the Proxy and the Data Source."
enabled
indicates if the workflow is enabled (true
) or not (false
)
ldap-server-extension
the name of the LDAP server extension with which the workflow element is associated
the credentials of the user that the proxy uses to connect to the remote LDAP server when client-cred-mode
is use-specific-identity
or use-proxy-auth
.
You must have configured an LDAP server extension before you create a proxy LDAP workflow element.
To create a proxy LDAP workflow element, use the dsconfig create-workflow-element
command, as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
create-workflow-element \
--element-name proxy-we5 \
--type proxy-ldap \
--set enabled:true \
--set client-cred-mode:use-client-identity \
--set ldap-server-extension:DS-proxy5
The workflow element type must be proxy-ldap
. The name of the new proxy LDAP workflow element is defined by element-name
, in this example proxy-we5
.
The client credential mode (client-cred-mode) indicates how the proxy will connect to the remote LDAP server. In this example, the credential mode is use-client-identity
, which means that the proxy will connect to the remote LDAP server with the same credentials as those used by the client to connect to the proxy. This is the default mode.
Notes:
If you use Oracle Unified Directory remote LDAP servers and the client credential mode is set to use-proxy-auth
, the user as which you are connecting must exist on the remote LDAP server. If the user does not exist, requests will be rejected. If you cannot guarantee that the user exists on the remote LDAP server, rather set the client credential mode to use-specific-identity
.
If the user deployment performs an internal operations then you must define the root credentials. For example, if you are using RDN changing as described in Section 15.1.6, "Configuring RDN Changing With dsconfig
" then the root credentials are defined by the following properties:
remote-root-dn
remote-root-password
These are the credentials of the root user of the remote LDAP server when the server performs internal operations.
When managing passwords in a proxy LDAP workflow element (remote-ldap-server-bind-password
or remote-root-passord
), the following syntax are valid:
<password-value>
or file://<password-file>
For more information, see Chapter 21, "Configuring Security Between the Proxy and the Data Source."
To modify the proxy LDAP workflow element properties, use the set-workflow-element-prop
command.
You can modify the following properties:
Set whether the proxy LDAP workflow element is enabled (true
) or not (false
)
Set the client credential mode that is used (client-cred-mode
)
Associate an LDAP server extension, to indicate which remote LDAP server to use (ldap-server-extension
)
Set the credentials of the user that the proxy uses to connect to the remote LDAP server (remote-ldap-server-bind-dn
and remote-ldap-server-bind-password
). The following syntaxes are supported:
<password-value>
file://<password-file>
Passing a password in clear on the command line is supported but not recommended. It is recommended to use a password-file. You can delete the password-file once the command is executed.
For example, if you want to modify the LDAP server extension used by the workflow element in order to use a different remote LDAP server, do the following:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
set-workflow-element-prop --advanced \
--element-name proxy-we5 \
--set remote-ldap-server-bind-dn:uid=Specific\ User,dc=example,dc=com \
--remote-ldap-server-bind-password:file://pwd-file \
--set ldap-server-extension:DS-proxy3 \
--set client-cred-mode:use-specific-identity
When an end user executes an authenticated operation, the proxy LDAP workflow element receives the following two distinct operations:
A BIND operation that authenticates the user against the remote server.
An operation to execute.
When a bind operation is executed, the proxy LDAP workflow element retrieves a connection from the LDAP server extension, performs the BIND operation, then releases the connection.
When the actual operation arrives, the proxy LDAP workflow element again retrieves a connection from the LDAP server extension. If a connection is found that is still bound with the appropriate credentials, that connection is reused. If not, a new connection must be authenticated. This additional authentication operation is called a silent bind.
The set of credentials used to perform a silent bind is determined by the bind mode, which is a property of the LDAP workflow element. These credentials can be the client credentials or the proxy credentials. Table 15-1 lists the bind modes that are supported by Oracle Unified Directory.
Table 15-1 Supported Bind Modes by Oracle Unified Directory
Mode | Description |
---|---|
|
Use the client credentials to perform the silent bind. |
|
Use the proxy credentials to perform the silent bind. |
For each of the bind modes described in Table 15-1, you can configure additional parameters to tweak the behavior of the server. These parameters are described in the following sections:
Section 15.1.2.1.1, "Configuring the use-client-identity
Bind Mode"
Section 15.1.2.1.2, "Configuring the use-specific-identity
Bind Mode"
use-client-identity
Bind ModeWhen the bind mode is set to use-client-identity
, the server uses the client credentials to perform the silent bind, unless specific parameters prevent it from doing so. The parameters that prevent the server from using the client credentials are the following:
Using Include and Exclude Lists
You can configure the following lists:
Include List: Lists the suffixes that are handled by the remote server.
Exclude List: Lists the suffixes that are not handled by the remote server.
If the client bind DN is a descendant of one DN on the include list, and the client bind DN is not a descendant of any DN on the exclude list, the proxy server uses the client credentials to perform a silent bind. Otherwise the proxy server uses the proxy credentials to perform the silent bind. If both lists are empty, the proxy server always uses the client credentials.
The include and exclude lists are not mutually exclusive and can be used simultaneously. However, it is recommended that you define only one list. In addition, you cannot define the same suffixes in both the lists.
Using the never-bind
Parameter
The never-bind
parameter is applicable whenever the proxy needs to perform a bind with the client credentials. If this flag is set to true,
the proxy server reads the user entry from the remote data source, and validates the user password itself, instead of forwarding the bind to the remote server. Note that the credentials used to read the user entry are proxy credentials, defined in the following properties of the proxy LDAP workflow element: remote-ldap-server-bind-dn
and remote-ldap-server-bind-password
.
If the incoming bind operation contains controls that are critical, an error result is returned as controls dedicated to bind operations are incompatible with the never-bind
feature.
Note:
If the proxy uses its own credentials to read the user entry, the proxy authorization control can be added to operations, to indicate the identity of the client at the origin of the request. The value of the use-proxy-auth
property determines whether the control should be added.
use-specific-identity
Bind ModeWhen the bind mode is set to use-specific-identity
, the proxy server uses the proxy credentials to perform all silent binds. The proxy credentials are defined in the following properties of the proxy LDAP workflow element: remote-ldap-server-bind-dn
and remote-ldap-server-bind-password
.
In use-specific-identity
bind mode, you can set the following parameters:
Using the use-proxy-auth
Parameter
If the use-proxy-auth
flag is set to true
, the proxy server adds a proxy authorization control to all requests, except bind requests. The value of the proxy authorization identifier is the client bind DN.
Using the never-bind
Parameter
The never-bind
parameter is applicable whenever the proxy needs to perform a bind with the client credentials. When this flag is set to true,
the proxy server reads the user entry from the remote data source, and validates the user password itself, instead of forwarding the bind to the remote server. Note that the credentials used to read the user entry are proxy credentials, defined in the following properties of the proxy LDAP workflow element: remote-ldap-server-bind-dn
and remote-ldap-server-bind-password
.
dsconfig
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
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.
This section covers all the administration tasks related to load balancing. For information about setting up a load balancing deployment during installation, see "To Configure Simple Load Balancing" section in Oracle Fusion Middleware Installation Guide for Oracle Unified Directory. It contains the following topics:
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 15.1.3.2, "Creating a Load Balancing Workflow Element."
Create a load balancing algorithm.
See Section 15.1.3.3, "Creating a Load Balancing Algorithm.".
Create one load balancing route for each load balancing workflow element.
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
.
In order 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 15.1.3.2, "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, the 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 15.1.3.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.
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 15.1.3, "Configuring Load Balancing With dsconfig
."
The following sections describe the different settings possible in a load-balancing deployment:
Section 15.1.3.5.1, "Setting the Priority in a Failover Algorithm"
Section 15.1.3.5.3, "Setting the Saturation Precision for the Optimal or Saturation Algorithm"
Section 15.1.3.5.4, "Setting the Weight of a Proportional Algorithm"
Section 15.1.3.5.5, "Setting the Threshold for a Saturation Algorithm"
Section 15.1.3.5.6, "Setting the Saturation Threshold Alert"
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%.
The saturation threshold alert is used to set at which point a notification will be sent to the system administrator to indicate that the server has passed the saturation limit. Generally, the saturation threshold alert is set higher than the saturation limit, in order to indicate if the saturation continues to increase past the saturation threshold (which may indicate a problem). The alert should bet set with an acceptable buffer, as 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
You can set the saturation threshold alert to a value lower than the saturation threshold, in order to perform preventative actions (For example, If the main route is a set of load balanced servers, then you can 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 29.4, "Configuring Alerts and Account Status Notification Handlers."
When client connection affinity is defined, requests from a specified client connection are routed to the same server, bypassing the load balancing algorithm that has been set. 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 14.1.6.3, "Creating a Network Group Quality of Service Policy."
Example 15-1 Example of Client Connection Affinity Rejected
When client connection affinity is set, the load balancing algorithm is bypassed as long as the constraints of the weights that have been defined 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 (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.
dsconfig
To forward client requests to remote LDAP servers using distribution, the following components must be configured on the proxy server:
a distribution workflow element
a distribution algorithm
one or more distribution partitions (typically one per remote LDAP server)
A distribution workflow element can only have one distribution algorithm, that defines how data is distributed. A distribution algorithm can use several partitions.
The following examples describe how to configure distribution using the dsconfig
command. For information about setting up a distribution deployment during setup, see "To Configure Simple Distribution" section in Oracle Fusion Middleware Installation Guide for Oracle Unified Directory.
All the commands in the following procedures specify the proxy hostname (-h
), the proxy admin port (-p
), the bind DN (-D
), and the bind password file (-j
). The examples use the -X
option to trust all certificates.
This section contains the following topics:
Section 15.1.4.2, "Creating a Distribution Workflow Element"
Section 15.1.4.7, "Configuring Criticality in Workflow Elements"
Create a distribution workflow element.
See Section 15.1.4.2, "Creating a Distribution Workflow Element."
Create a distribution algorithm.
Create one partition for each chunk of partitioned data. A partition must be associated with one remote LDAP server, or with a set of replicated remote LDAP servers.
For a capacity-based distribution see Section 15.1.4.4.1, "Creating a capacity
Distribution Partition."
For a lexico or numeric distribution see Section 15.1.4.4.2, "Creating a lexico
or numeric
Distribution Partition."
If you are using DN pattern algorithm, see Section 15.1.4.4.3, "Creating a dnpattern
Distribution Partition."
To configure distribution, you must create a distribution 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 distrib-we \
--type distribution \
--set enabled:true \
--set base-dn:ou=people,dc=example,dc=com
To create a distribution workflow element, the type must be distribution
. The name of the workflow element is defined by element-name
, in this example distrib-we
.
Note:
When declaring the base-dn
using the create-workflow-element
subcommand as shown above, ensure that you specify the full tree structure.
To complete the distribution element of your configuration, create the distribution algorithm and the appropriate partitions.
To determine how the requests will be forwarded in a distribution deployment, you must configure the distribution algorithm. The algorithm set determines how the data is partitioned and to which partition a request is sent. The possible distribution types are: numeric
, lexico
, or dnpattern
.
To create the distribution algorithm, you must have a distribution workflow element. See Section 15.1.4.2, "Creating a Distribution Workflow Element."
Create a distribution algorithm using the dsconfig create-distribution-algorithm
command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
create-distribution-algorithm \
--element-name distrib-we \
--type numeric \
--set distribution-attribute:uid
The name of the workflow element is defined by element-name
, in this example distrib-we
. The distribution algorithm type must be set as capacity
, numeric
, lexico
, or dnpattern
. The properties set depend on the algorithm type. In this example, distribution-attribute
must be set, as the algorithm type is numeric
.
You can create the following types of distribution partitions:
Section 15.1.4.4.1, "Creating a capacity
Distribution Partition"
Section 15.1.4.4.2, "Creating a lexico
or numeric
Distribution Partition"
Section 15.1.4.4.3, "Creating a dnpattern
Distribution Partition"
capacity
Distribution PartitionTo create a capacity
distribution partition, the distribution workflow element and distribution algorithm must already be created. You must create one distribution partition per data set.
To create a distribution partition, use the dsconfig create-distribution-partition
command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ create-distribution-partition \ --element-name distrib-we \ --partition-name distrib-partition1 \ --type capacity \ --set partition-id:1 \ --set workflow-element: proxy-we1 \ --set max-entries:1000
Note:
You must create a global index catalog and have the DNs indexed to use the capacity-based algorithm. To create global index catalogs, see Section 15.1.7.1.1, "To Create a Global Index Catalog Containing Global Indexes."
A distribution partition is identified by both a partition name, in this example, distrib-partition1
and a partition id. The partition id must be an simple integer, as it will be used for the global index catalog reference. The type must be the same as the one defined by the distribution algorithm associated, in this case capacity
.
To create a distribution partition, you must also indicate the name of the existing distribution workflow element (element-name
) that manages the partition (here distrib-we
), and the name of the next element in the work flow (workflow-element
), such as an LDAP workflow element (in this example proxy-we1
). The proxy workflow element indicates the path used to reach the data on the remote LDAP server. For more information on the proxy, see Section 15.1.1, "Configuring Communication With Remote LDAP Servers."
When creating a capacity
distribution partition, you must indicate the maximum number of entries the partition can hold, for example 1000.
lexico
or numeric
Distribution PartitionLexico and numeric distribution are very similar, so you set the same properties when you create a distribution partition for lexico or numeric distribution. You must create one distribution partition per data set.
To create lexico
or numeric
distribution partitions, the distribution workflow element and distribution algorithm must already be created.
To create a distribution partition, use the dsconfig create-distribution-partition
command. For example for a numeric distribution, you might create a partition as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ create-distribution-partition \ --element-name distrib-we \ --partition-name distrib-partition1 \ --type numeric \ --set partition-id:1 \ --set workflow-element: proxy-we1 \ --set lower-bound:1000 \ --set upper-bound:2000
A distribution partition is identified by both a partition name, in this example, distrib-partition1
and a partition id. The partition id must be an simple integer, as it will be used for the global index catalog reference. The type must be the same as the one defined by the distribution algorithm associated, in this case numeric
.
In order to create a distribution partition, you must also indicate the name of the existing distribution workflow (here distrib-we
), and the name of the associated workflow element, such as an LDAP workflow element (in this example proxy-we1
). The proxy workflow element indicates the path used to reach the data on the remote LDAP server. For more information on the proxy, see Section 15.1.1, "Configuring Communication With Remote LDAP Servers."
When creating a lexico
or numeric
distribution partition, you must indicate the lower and upper boundaries of the partition. The proxy checks to ensure that there is no overlap in the boundaries of any two partitions. This means that you cannot set partition 1 with boundaries 1000-3000 and partition 2 with boundaries 2000-4000.
The upper boundary is exclusive, which means that in the example above, the partitioned data only includes values between 1000 up to 1999. If you want the upper boundary or lower boundary to be unlimited, use the keyword unlimited
.
The properties set (in this example boundaries) are related to the type of distribution created. For more information about the properties of the partitions, linked to the algorithm type see Section 15.1.4, "Configuring Distribution With dsconfig
."
Note that for a lexico distribution algorithm, the sort sequence that is used is ASCII.
dnpattern
Distribution PartitionBefore you create a dnpattern
distribution partition, the distribution workflow element and distribution algorithm must already be created.
To create a dnpattern
distribution partition, use the dsconfig create-distribution-partition
command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ create-distribution-partition \ --element-name distrib-we \ --partition-name distrib-partition5 \ --type dnpattern \ --set partition-id:5 \ --set workflow-element: proxy-we1 \ --set dn-pattern:uid=[0-9]*[01].*
A distribution partition is identified by both a partition name, in this example, distrib-partition5
and a partition ID. The partition ID is used for the global index catalog reference, and be an simple integer. To create a distribution partition, you must also indicate the name of the existing distribution workflow (here distrib-we
), and the name of the associated workflow element, such as an LDAP proxy (in this example proxy-we1
). The type must be the same as the one defined by the distribution algorithm associated, in this case dnpattern
.
In a distribution scenario that uses a dnpattern
algorithm, requests are sent to a partition when the request RDNs below the distribution base DN match the DN string pattern. For example, if the distribution base DN is ou=people,dc=example,dc=com
and the request base DN is uid=1,ou=people,dc=example,dc=com
, the check against the string pattern is done on the RDN uid=1
.
Similarly, if the distribution base DN is ou=people,dc=example,dc=com
and the request base DN is uid=1,ou=region1,ou=people,dc=example,dc=com
, the check against the string pattern is done on the RDNs uid=1,ou=region1
.
The DN string pattern must comply with the DN syntax and with a subset of the Java Pattern class.
DN Pattern String | Description |
---|---|
. |
any character |
\\ |
backslash |
\t |
TAB character |
[abc] |
a, b, or c |
[^abc] |
any character except a, b, or c |
[a-zA-Z] |
a through z, or A through Z, inclusive (range) |
[a-d[m-p]] |
a through d, or m through p (union) |
[a-z&&[def]] |
d, e, or f (intersection) |
[a-z&&[^bc]] |
a through z, except for b and c (subtraction) |
[A-Z&&[^M-P]] |
a through z, and not m through p (subtraction) |
The following quantifiers can be used:
X? |
X, once or not at all |
X* |
X, zero or more times |
X+ |
X, one or more times |
X{n} |
X, exactly n times |
X{n,} |
X, at least n times |
X{n,m} |
X, at least n times but no more than m times |
negative-match
The distribution property called negative-match
allows you to specify the opposite of the DN pattern that should be matched. That is, you specify a DN pattern to be ignored; any value that does not match the specified DN pattern will be distributed. By default, the negative-match
property is set to false
.
Create a dnpattern
distribution partition using negative-match
as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ create-distribution-partition \ --element-name distrib-we \ --partition-name distrib-partition5 \ --type dnpattern \ --set partition-id:5 \ --set workflow-element: proxy-we1 \ --set dn-pattern:uid=[123]*[0-9].* \ --set negative-match:true
In the example above, since negative-match
has been set to true
, any requests for uid
that does not start with 1, 2, or 3, with n characters following will be forwarded to the partition.
You can modify a DN so that the new entry remains in the same partition as the original entry. By default, the proxy does not allow you to modify the DN to a value that is outside the range of the current partition.
If you want to allow modifyDN
requests to change the DN to a value that is outside the boundaries of the partition in which the entry is located, set the force-modify-dn
flag to true
.
Assume, for example, that you have two partitions: Partition 1 with uid
boundaries from 0-999 and Partition 2 with uid
boundaries from 1000-1999. If the force-modify-dn
flag is set to true
and you modify the uid
of an entry from 1
to 1001
, the change will be allowed, but the entry with uid
1001
will remain in Partition 1. It is not moved to Partition 2.
If you then search for uid=1001
, the server will return an error, indicating that no such entry is found. To locate the entry, you must use a global index catalog. This ensures that modified entries are always found. To configure a global index catalog, see Section 15.1.7, "Configuring Global Indexes By Using the Command Line."
To force a modify DN operation, set the force-modify-dn
flag to true
, as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
--advanced set-workflow-element-prop --element-name distrib-we \
--set force-modify-dn:true
The criticality configuration determines the server behavior when a search operation fails. Criticality applies only to search requests. All other requests are processed normally by the server.
You can configure criticality by setting the criticality flag at the workflow level. When a search request is executed on a workflow, then it is executed on several workflows if there are subordinate workflows. The criticality setting of a workflow can be one of the following:
true
This is the default setting and indicates that the workflow is considered as critical. If a workflow fails to return a result the processing is stopped regardless of whether the execution of the operation was successful on any other workflow.
false
This setting indicates that the workflow is non-critical. A criticality setting of false
tells the server that the failure to perform an operation in the workflow is not critical to the overall result. If the non-critical workflow fails to return a result the server simply omits the results (as if the workflow did not return any data), returns a SUCCESS result code to the client, and does not indicate any error.
Partial
This setting indicates that the workflow is partially critical. This implies that the application can notify its own users that partial results were obtained. If a partially-critical partition fails to return a result because, for example, it is fully saturated or disabled, the server returns an Admin Limit Exceeded
error. While this is not the expected error, the intention of this setting is to cause client application logic to indicate that not all results are shown.
To set the criticality of a workflow, use the dsconfig set-workflow-prop
command. For example, the following command sets the criticality of a workflow named workflow-1
to true:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ set-workflow-prop --workflow-name workflow-1 \ --set criticality:true
In a distribution deployment, the criticality configuration determines the server behavior when a search operation fails, due to a host error. Criticality applies only to search requests. All other requests are processed normally by the server.
Criticality is configured for each distribution partition in a distribution workflow element. The criticality setting of a distribution partition can be one of the following:
true
This is the default setting and indicates that the partition is considered as critical. If a partition fails to return a result because, for example, it is fully saturated or disabled, the server returns an UNAVAILABLE error to the client regardless of whether data was found in any other partition.
false
This setting indicates that the partition is non-critical. A criticality setting of false
tells the server that the failure to perform an operation in the partition is not critical to the overall result. If the non-critical partition fails to return a result because, for example, it is fully saturated or disabled, the server simply omits the results (as if the partition did not return any data), returns a SUCCESS result code to the client, and does not indicate any error.
Partial
This setting indicates that the partition is partially critical. This implies that the application can notify its own users that partial results were obtained. If a partially-critical partition fails to return a result because, for example, it is fully saturated or disabled, the server returns an Admin Limit Exceeded
error. While this is not the expected error, the intention of this setting is to cause client application logic to indicate that not all results are shown.
For all types of workflow element, other than a distribution workflow element, criticality is implicit and is handled as follows:
Load Balancing: All routes are considered as non critical, because if a route is not functional then it is not taken into consideration by the load balancer while determining the selected route.
LDAP Proxy Workflow Element: An LDAP server is always considered as critical.
Local Backend Workflow Element: A local backend server is always considered as critical.
To set the criticality of a distribution partition, use the dsconfig set-distribution-partition-prop
command. For example, the following command sets the criticality of a partition named distrib-partition-1
to true:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ set-distribution-partition-prop --element-name distrib-we \ --partition-name distrib-partition-1 --set criticality:true
To delete a complete distribution workflow (workflow element, algorithm, and partitions), you need only delete the distribution workflow element. When you delete a distribution workflow element, the associated distribution algorithm and partitions are silently deleted.
dsconfig
To configure DN renaming, create a DN renaming workflow element, using the dsconfig create-workflow-element
command.
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ create-workflow-element \ --type dn-renaming \ --element-name RenameorgDN \ --set client-base-dn:ou=myorg,dc=example,dc=com \ --set next-workflow-element:load-bal-we1 \ --set source-base-dn:ou=people,dc=example,dc=com \ --set enabled:true
--set client-base-dn
indicates the client base DN, which is the workflow entry point
--set source-base-dn
indicates the base DN which the entries should have after transformation, which is the workflow exit point.
--set next-workflow-element
indicates the workflow element that will follow the DN renaming workflow element in the proxy architecture. This can be any type of workflow element.
Once you have configured DN renaming, you can modify the following DN renaming properties:
client base DN
source base DN
next workflow element
black list attributes
white list attributes
To view the current DN renaming properties, use the dsconfig get-workflow-element-prop
command.
To modify a DN renaming property, use the dsconfig set-workflow-element-prop
command.
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ set-workflow-element-prop \ --element-name RenameorgDN \ --set source-base-dn:ou=admin,dc=example,dc=com
In the preceding example, only the source-base-dn
is modified. There is no need to specify the old source base DN. Only the new one is required.
To create a black list of DN attributes that should not be renamed, use the dsconfig set-workflow-element-prop
command.
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ set-workflow-element-prop --element-name RenameorgDN \ --set black-list-attributes:manager
The attribute must have a DN type.
dsconfig
To rename RDN, create a RDN Changing workflow element, using the dsconfig create-workflow-element
command.
dsconfig create-workflow-element \ --set client-rdn:cn \ --set enabled:true \ --set next-workflow-element:localproxy \ --set source-rdn:uid \ --type rdn-changing \ --element-name myrdnchangingwfe \ --hostname localhost \ --port "4444" \ --trustAll \ --bindDN cn=directory\ manager \ --bindPasswordFile pwd-file \ --no-prompt
--set client-rdn
indicates the client base RDN, which is the workflow entry point.
--set source-rdn
indicates the base RDN which the entries should have after transformation, which is the workflow exit point.
--set next-workflow-element:localproxy
indicates the workflow element that will follow the RDN changing workflow element in the proxy architecture. This can be any type of workflow element.
Note:
You must create the Proxy LDAP workflow element with the parameters
remote-root-dn
remote-root-password
The RDN Changing workflow element uses these credentials to perform internal searches on the remote server.
--element-name myrdnchangingwfe
indicates the name of the RDN Changing workflow element you are creating.
This configuration replaces uid=user.1,ou=people,dc=example,dc=com with cn=User CN,ou=people,dc=example,dc=com
.
Once you have configured RDN renaming, you can modify the following RDN renaming properties:
client RDN
source RDN
next workflow element
objectclass
dn attributes
replace-value
To view the current RDN renaming properties, use the dsconfig get-workflow-element-prop
command.
To modify a RDN renaming property, use the dsconfig set-workflow-element-prop
command.
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ set-workflow-element-prop \ --element-name myrdnchangingwfe \ --set source-rdn:uid
In the preceding example, only the source-rdn
is modified. There is no need to specify the old source-rdn. Only the new one is required.
Global indexes map entries to a specific distribution partition to speed up search and modify operations in distributed topologies. A global index maps entries based on a unique attribute, such as a phone number. Lists of global indexes are contained in a global index catalog. A proxy instance can contain one or more global index catalogs.
Note:
To configure and manage global indexes and global index catalogs, you must enable specific controls on the remote servers, particularly the LDAP Pre-Read Control and the CSN Control. For more information, see Appendix B, "Supported Controls and Operations."
This section contains the following topics:
gicadm
Global index catalogs are stored in a Berkeley database under INSTANCE_DIR/OUD/catalogs
. To ensure high availability of a distributed topology, replication of global index catalogs is recommended. For more information, see Replication of Global Index Catalogs.
The gicadm
command is located in the server instance directory:
for Unix: INSTANCE_DIR/OUD/bin/gicadm
for Windows: INSTANCE_DIR\OUD\bat\gicadm.bat
For more information, see Appendix A, "gicadm."
The procedures in this section assume that the proxy is deployed in a distribution architecture and presume that you are using the default proxy administration port (4444). This section contains the following topics:
Section 15.1.7.1.1, "To Create a Global Index Catalog Containing Global Indexes"
Section 15.1.7.1.2, "To View Global Index Catalog Properties"
Section 15.1.7.1.3, "Modifying the Properties of a Global Index Catalog"
Section 15.1.7.1.4, "To Modify the Properties of a Global Index Catalog"
Section 15.1.7.1.5, "To Modify Multi-Valued Global Index Catalog Properties"
Section 15.1.7.1.6, "To Reset Global Index Catalog Properties To the Default Values"
Section 15.1.7.1.8, "To Import Content into a Global Index Catalog"
Section 15.1.7.1.9, "To Export Contents of a Global Index Catalog to a Directory"
Section 15.1.7.1.10, "To Associate a Global Index Catalog With a Distribution Element"
Section 15.1.7.1.11, "To Disassociate a Global Index Catalog From a Distribution Element"
Section 15.1.7.1.12, "To Add a Global Index to a Global Index Catalog"
Section 15.1.7.1.13, "To Remove a Global Index From a Global Index Catalog"
To create global indexes, you must first create global index catalogs, as described in the following procedure. This procedure describes how to create global index catalogs, create and add global indexes, and add data to the global indexes. You can add the data to your global indexes later, if you prefer.
Before you begin, the proxy must be deployed for distribution.
Use the gicadm
command to create a global index catalog:
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ create-catalog --catalogName sampleCatalog
The catalog name must be unique.
Create and add at least one global index to the global index catalog.
The following command creates a global index of telephoneNumber
attribute values and adds that global index to the global index catalog that was created in the previous step.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ add-index --catalogName sampleCatalog --attributeName telephoneNumber
You can use the add-index
subcommand later to add additional global indexes to the global index catalog.
Associate the global index catalog to a distribution.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ associate --catalogName sampleCatalog \ --distributionWorkflowElement myDistributionName
For information about workflow elements, see Section 14.1.8, "Configuring Workflow Elements With dsconfig
." For information about distribution, see Section 15.1.4, "Configuring Distribution With dsconfig
."
Use the split-ldif
command to generate multiple files from one LDIF file.
The split-ldif
command separates the content of one LDIF file into several LDIF files based on the distribution algorithm configured with your proxy. It can also generate files that contain data to load in a global index. You should use split-ldif
during global index initialization if the remote LDAP servers will contain data that needs to be indexed when you start your Directory service. If you plan to start without data in your directory, you can skip this step.
For information on the split-ldif
command, including examples on how to use the command to populate a global index with one or several indexed attributes, see Appendix A, "split-ldif."
Use the gicadm import
command to import data into the global index.
For more information, see Section 15.1.7.1.8, "To Import Content into a Global Index Catalog."
Global index catalog properties are related to global index catalog replication. For a list of the global index catalog properties and an explanation of their use, see Section 15.1.7.1.3, "Modifying the Properties of a Global Index Catalog."
To view all the properties of a global index catalog, use the gicadm
command with the get-catalog-prop
subcommand.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ get-catalog-prop --catalogName sampleCatalog --property all
The output will be similar to the following.
Property : Value(s) -------------------:------------------------------- replication-server : localhost:3390, localhost:4390 server-id : 4247 window-size : 100 heartbeat-interval : 1000 group-id : 1
To view the value for a specific global index catalog property, specify the property.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ get-catalog-prop --catalogName sampleCatalog --property heartbeat-interval
Global index properties are related to the replication of global index catalogs. The following global index catalog properties are available:
replication-server
: This lists the servers in the replication topology, in the format host:port
. This property should not be modified with the set-catalog-prop
command, but with enable-replication
.
server-id
: Specifies a unique identifier for the global index within the global index catalog replication domain. Each instance within the same global index catalog replication domain must have a different server ID. An instance which is a member of multiple global index catalog replication domains may use the same server ID for each of its global index catalog replication domain configurations.
Syntax: 1 <= INTEGER <= 65535 or text. This property should not be modified.
window-size
: Specifies the window size that the instance will use when communicating with replication servers. Default value is 100.
Syntax: 0 <= INTEGER or text.
heartbeat-interval
: Specifies the heartbeat interval that the instance will use when communicating with replication servers. The instance expects a regular heartbeat from the replication server within the specified interval. If a heartbeat is not received within this interval, the instance closes its connection and connects to another replication server.
Syntax: 100 ms <= DURATION (ms)
group-id
: The id associated with a specific replicated domain. This value defines the group id of the replicated domain. The replication system will preferably connect and send updates to replicate to a replication server with the same group id as itself.
Syntax: 1 <= INTEGER <= 127
Note:
This property should not be modified.
For a list of the global index catalog properties, see Section 15.1.7.1.3, "Modifying the Properties of a Global Index Catalog."
Use the gicadm
command with the set-catalog-prop
subcommand.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
set-catalog-prop --catalogName sampleCatalog --set property:value
For example, one of the properties that can be modified is the heartbeat interval. In this case, use:
--set heartbeat-interval:500
For multi-valued global index or global index catalog properties, you can add or remove a value using the --add
or --remove
options.
For global index catalog, only the property replication-server
can be multi-valued. For multi-valued global index properties, use the set-index-prop
subcommand instead
To add a value, use the gicadm
command with the set-catalog-prop
subcommand.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
set-catalog-prop --catalogName sampleCatalog --add replication-server:hostname
To remove a value from a multi-valued property, use the gicadm
command with the set-catalog-prop
subcommand.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
set-catalog-prop --catalogName sampleCatalog \
--remove replication-server:hostname
If you have modified any of the global index catalog properties and want to reset them to the default values, use the following procedure.
Use the gicadm
command with the set-catalog-prop
subcommand.
For example, to reset the heartbeat interval:
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
set-catalog-prop --catalogName sampleCatalog --reset heartbeat-interval
To view the properties of a global index, use the gicadm
command with the get-index-prop
subcommand.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ get-index-prop --catalogName sampleCatalog --attributeName telephoneNumber \ --property all
The properties should be similar to the following:
Property Names : Property Values ---------------------------------------------:--------------------------------- global-index-deleted-entry-retention-timeout : 500 db-cleaner-min-utilization : 50 db-log-file-max : 10000000 db-checkpointer-bytes-interval : 20000000 db-checkpointer-wakeup-interval : 30 db-num-lock-tables : - db-num-cleaner-threads : - db-txn-no-sync : false db-txn-write-no-sync : true je-property : - db-directory : catalogs db-directory-permissions : 700 global-index-catalogs-shared-cache : global-index-catalogs-shared-cac global-index-attribute : telephoneNumber
Note:
Generally, these values should not be modified.
You can import the contents of a specific file into one or multiple global indexes in a global index catalog. You must specify the name of the catalog into which the content of the file is to be imported. You can filter the content of the file to data related to a particular index by optionally providing the attributeName
parameter.
The data file to be imported can be created by executing the split-ldif
command or from executing the gicadm export
command, for example.
To import the contents of a file into a global index catalog, use the gicadm
command with the import
subcommand. For example:
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ import --file /usr/local/import-file --catalogName sampleCatalog
If the proxy server stops while a gicadm import
task is being executed, the global index catalog workflow element is disabled. In this case, re-enable the global index catalog workflow element by using dsconfig
, as follows, where sampleCatalog is the name of the global index catalog:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ set-workflow-element-prop --element-name sampleCatalog set enabled:true
To export the contents of a global index catalog to a directory, use the gicadm
command with the export
subcommand.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
export --exportDirectory directory-path --catalogName sampleCatalog
To associate a global index catalog with a distribution element, use the gicadm
command with the associate
subcommand.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
associate --catalogName sampleCatalog --distributionWorkflowElement element-name
When the global index catalog is associated with a distribution workflow element, the global index catalog will be listed in the properties of the distribution. To confirm which global index catalog is associated to a distribution, use the dsconfig get-workflow-element-prop
command. For information on workflow elements, see Section 14.1.8, "Configuring Workflow Elements With dsconfig
."
To disassociate a global index catalog from a distribution topology, you must know the distribution workflow element with which the global index catalog is associated. To confirm the name of the distribution workflow element that is using the global index catalog, view the properties of the distribution topology by using the dsconfig --get-workflow-element-prop
command.
To disassociate a global index catalog from a distribution workflow element, use the gicadm
command with the disassociate
subcommand.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
disassociate --distributionWorkflowElement element-Name
To add a new global index to an existing global index catalog, for example to map a new attribute, use the following procedure. This procedure creates and adds the global index to the global index catalog. It is not possible to create a global index without adding it to a global index catalog.
Before you begin, you must already have configured a global index catalog.
Use the gicadm
command with the add-index
subcommand.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ add-index --catalogName sampleCatalog --attributeName telephoneNumber
Use the gicadm
command with the remove-index
subcommand.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ remove-index --catalogName sampleCatalog --attributeName telephoneNumber
To ensure high availability, global index catalogs should be replicated. A standard hardware load balancer can be used and replication of global index catalogs can be configured in a deployment as shown by the graphic in Section 3.8, "Multiple Replicated Proxies."
This section contains the following topics:
Section 15.1.7.2.1, "To Create a Replicated Topology and Enable Global Index Catalog Replication"
Section 15.1.7.2.2, "To Enable Global Index Catalog Replication"
Section 15.1.7.2.3, "To Initialize Global Index Catalog Replication"
Section 15.1.7.2.4, "To Disable Global Index Catalog Replication"
Section 15.1.7.2.5, "To View the Status of a Replicated Global Index Catalog Configuration"
Section 15.1.7.2.7, "Lifecycle Examples for Replicated Global Index Catalogs"
Follow the steps below in order to create a replicated topology with three proxy instances, and enable global index catalog replication, as illustrated in Figure 15-1.
Figure 15-1 Replicated Global Index Catalogs
Install at least two proxy instances in your server topology.
These instances should be on separate physical machines, for redundancy.
Configure a global index catalog for each instance of the proxy in your topology and add one or more global indexes.
For more information on configuring a global index catalog using the gicadm
command, see Section 15.1.7.1.1, "To Create a Global Index Catalog Containing Global Indexes."
Enable global index catalog replication.
The proxy instance whose global index catalog is to be replicated across the topology is referred to, for the purposes of CLI syntax, as the local instance, while the other proxy instance declared in the command is referred to as the remote instance. For more information on running the gicadm enable-replication
command, see Section 15.1.7.2.2, "To Enable Global Index Catalog Replication."
Repeat this step for each proxy that is part of your replicated topology.
Choose a proxy instance on which to initialize replication. Consider which proxy instance has the most up to date global index catalog content.
Otherwise, you can import the LDIF file to each proxy that is part of the topology. See Section 15.1.7.1.8, "To Import Content into a Global Index Catalog."
On the proxy instance chosen in the previous step, run the gicadm initialize-replication --all
command. For more information, see Section 15.1.7.2.3, "To Initialize Global Index Catalog Replication."
Note:
When using a global index catalog with replicated remote LDAP servers, only one remote LDAP server must handle write operations if such operations can concurrently modify the same value and if that value is indexed. For this, you could set the weights in your load balancing workflow element to direct all write traffic to the same server. For more information, see Section 15.1.3.5, "Modifying Load Balancing Properties."
This command configures replication but does not initialize replication. The command is executed on the local host, declared by the -h
option, using the administration port of the local host. The remote host is declared by the --remoteHost
option, and must be a fully qualified host name or IP address. The command creates a global index catalog replication administrator with a bind ID of adminUID.
If you created global index catalogs during installation, the global index administrator is already created, with the same password as the directory manager. For more information on installing a distribution deployment with global index, see "To Configure Simple Distribution" section in Oracle Fusion Middleware Installation Guide for Oracle Unified Directory.
To enable replication of global index catalogs, use the gicadm enable-replication
command.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ enable-replication --catalogName sampleCatalog --adminUID adminUID --localReplicationPort 8989 --remoteReplicationPort 8989 \ --remoteAdminPort 4444 --remoteHost host
This command updates the proxy configuration to replicate the content of the global index catalog called sampleCatalog on the local host. If one of the proxy instances in the topology already replicates the global index catalog, this command updates the configuration of all other proxy instances in the topology. It is therefore sufficient to execute the gicadm enable-replication
once for the first two proxy instances in the topology, and once for each new proxy instance that is added to extend the topology.
The proxy instance on which you execute the command must be the instance whose replication port is declared by the --localReplicationPort
option. It is this local instance whose global index catalog is replicated across the topology later by the gicadm initialize-replication
command. The --remoteReplicationPort
option will replicate the content of the global index catalog called sampleCatalog from the local instance on to the remote instance. The --remoteAdminPort
is the administration port of the remote proxy instance.
You can declare the password for the local proxy instance in a file, by using the --adminPasswordFile
suboption.
You can optionally declare a DN for binding to the remote server by using the --remoteBindDN
suboption and the password for the remote proxy instance in a file, by using the --remoteBindPasswordFile
suboption. If you do not declare these, the global administrator that is declared by --adminUID
will be used to bind.
You can also optionally require the communication through the replication port of the local server to be secure, using the --localSecureReplication
suboption, and the communication through the replication port of the remote server to be secure, using the --remoteSecureReplication
suboption.
This command initializes the content of the global index catalog called sampleCatalog from the proxy instance on the server declared by the -h
option to all instances that are part of the topology. The port specified is the administration port, and not the replication port.
To initialize the replication of a global index catalog to all proxy instances that are part of the replication topology, use the gicadm initialize-replication
--all
as follows:
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ initialize-replication --catalogName sampleCatalog \ --adminUID adminUID --all
Check that replication is complete by using the gicadm status-replication
command.
If replication is complete, the status for all proxy instances in the topology is given as running replicated
.
Replication must be complete before restarting any proxy instances in the topology, for example after applying a patch.
For information about using the gicadm status-replication
command, see Section 15.1.7.2.5, "To View the Status of a Replicated Global Index Catalog Configuration."
To disable replication of global index catalogs, use the gicadm disable-replication
command.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ disable-replication --catalogName sampleCatalog --adminUID adminUID
The gicadm disable-replication
command must be executed for each proxy instance in the topology on which you want to disable replication.
To display basic configuration information about a replicated global index catalog, use the gicadm status-replication
command.
$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ status-replication --catalogName sampleCatalog --adminUID adminUID
If you do not declare a catalog name, status information for all replicated global index catalogs is displayed.
Replication logs are stored in the replication repair logs. Changes are recorded in the change logs. For information on accessing these logs, see Section 29.5.4, "Accessing Logs."
When replicating global index catalogs, provision disk space for change logs. By default, these logs store changes for a 24 hour period. Approximately 100Mb is required for 300,000 write operations. With the default value of 24 hours, the log must be configured based on the expected size of the service during that period. A hint is to provision approximately 150Gb for 5 000 modifications per second over 24 hours. For information how to configure logs, see Section 29.3, "Configuring Logs."
This section describes several typical lifecycle examples in which events take place in a replication topology. The basic replication topology used in all of these examples is the one created in Section 15.1.7.2.1, "To Create a Replicated Topology and Enable Global Index Catalog Replication."
Example 15-2 To Restart a Global Index Catalog in a Replicated Topology
In the example illustrated by Figure 15-2, three proxy instances are running with a replicated global index catalog. If proxy instance 3 goes down or is stopped, for whatever reason, follow these steps to ensure that the three instances of the proxy are replicated.
Issue the start-ds
command on proxy instance 3.
You can check to see if replication is complete by executing the gicadm status-replication
command, as described in Section 15.1.7.2.5, "To View the Status of a Replicated Global Index Catalog Configuration."
Figure 15-2 Restarting a Global Index Catalog
Example 15-3 Adding a Global Index to a Replicated Global Index Catalog Topology
In the example illustrated by Figure 15-3, three proxy instances are running with a replicated global index catalog. If you want to add an additional attribute, for example, mail
, to the replicated global index catalog, follow these steps.
First, run the command gicadm add-index mail
on each of the three proxy instances.
Export the directory data under the distribution route from one of the remote LDAP servers to an LDIF file named file1 by using export-ldif
.
Run split-ldif
to generate GIC content in the specified directory.
On proxy instance 1, execute the command gicadm import --importDirectory directory-name
.
On proxy instance 1, execute the gicadm initialize-replication --all
command. This command pushes the changes from proxy 1 to all the other proxies in the topology, and adds the new global index.
Figure 15-3 Adding a Global Index to a Replicated Global Index Catalog Topology
Example 15-4 Overwriting the Contents of Replicated Global Index Catalogs
In the example illustrated by Figure 15-4, three proxy instances are running with a replicated global index catalog. To overwrite the content of the global index catalogs on proxy instances 2 and 3 with the content of the global index catalog on instance 1, follow these steps.
On proxy instance 1, execute the gicadm initialize-replication --all
command. This replaces the content of the global index catalog on proxy instance 2 and 3 with the content of the global index catalog on proxy instance 1.
Figure 15-4 Overwriting the Contents of Replicated Global Index Catalogs
Example 15-5 Adding a Proxy to a Replicated Topology
In the example illustrated by Figure 15-5, three proxy instances are running with a replicated global index catalog. To add a fourth proxy instance with a replicated global index catalog, follow these steps on the new proxy instance.
On the new proxy instance 4, execute the gicadm create-catalog
command.
Run the commandsgicadm add-index cn
, gicadm add-index sn
, and gicadm add-index mail
.
Execute the gicadm associate
command.
Run the following command:
gicadm enable-replication --localReplicationPort replication port of instance 4 --remoteHost name or IP address of host running instance 1
This command configures replication between instance 1 and instance 4.
Run the initialize replication --from proxy 1
command.
Figure 15-5 Adding a Proxy to a Replicated Topology
If you are using the proxy server with an Oracle Unified Directory directory server as the LDAP data source, the connections between the proxy and directory servers must be bound using the directory server's administrator ID. Otherwise, some configuration is required on the directory server to allow the global index catalog to function correctly.
Provided that global ACIs for controls have not been modified, use the ldapmodify
command to apply the following changes to the directory server:
dn: cn=Access Control Handler,cn=config changetype: modify add: ds-cfg-global-aci ds-cfg-global-aci: (targetcontrol="2.16.840.1.113730.3.4.2 || 2.16.840.1.113730.3.4.17 | | 2.16.840.1.113730.3.4.19 || 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 | | 2.16.840.1.113730.3.4.16 || 1.3.6.1.1.13.1 || 1.3.6.1.4.1.42.2.27.9.5.9") (version 3.0; acl "Anonymous control access"; allow(read) userdn="ldap:///anyone";) ds-cfg-global-aci: (targetattr="createTimestamp||creatorsName||modifiersName| |modifyTimestamp||entryDN||entryUUID||subschemaSubentry||aclRights||aclRightsInfo") (version 3.0; acl "User-Visible Operational Attributes"; allow (read,search,compare) userdn="ldap:///anyone";)
If you are deleting the ACI from an Oracle Unified Directory 11g R1 directory instance, then you need to delete the following ACI:
dn: cn=Access Control Handler,cn=config changetype: modify delete: ds-cfg-global-aci ds-cfg-global-aci: (targetcontrol="2.16.840.1.113730.3.4.2 || 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 || 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 || 2.16.840.1.113730.3.4.16") (version 3.0; acl "Anonymous control access"; allow(read) userdn="ldap:///anyone";) ds-cfg-global-aci: (targetattr="createTimestamp||creatorsName||modifiersName||modifyTimestamp||entryDN||entryUUID||subschemaSubentry")(version 3.0; acl "User-Visible Operational Attributes"; allow (read,search,compare) userdn="ldap:///anyone";)
If you are deleting the ACI from an Oracle Unified Directory 11g R2 directory instance, then you need to delete the following ACI:
dn: cn=Access Control Handler,cn=config changetype: modify delete: ds-cfg-global-aci ds-cfg-global-aci: (targetcontrol="2.16.840.1.113730.3.4.2 || 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 || 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 || 2.16.840.1.113730.3.4.16 || 2.16.840.1.113894.1.8.31") (version 3.0; acl "Anonymous control access"; allow(read) userdn="ldap:///anyone";)
Note that the OIDs provided above are correct for an unmodified configuration of Oracle Unified Directory. If the default OIDs have been changed, modify the command include the correct OIDs.
The following controls are required for global index catalogs:
The Pre-Read Control, with OID = 1.3.6.1.1.13.1
The CSN Control, with OID = 1.3.6.1.4.1.42.2.27.9.5.9
Retrieving the contents of a multi-valued attribute sometimes result in a large number of returned values. Microsoft Active Directory server limits the maximum number of attribute values that can be retrieved in a single query.
Microsoft Active Directory provides a range retrieval mechanism that allows you to retrieve all the values of a multi-valued attribute. This mechanism permits a client-specified subset of the values to be retrieved in a search request. By performing multiple search requests, each retrieving a distinct subset, the complete set of values for the attribute can be retrieved.
Oracle Unified Directory handles Active Directory range retrieval by providing support for Microsoft Active Directory paging. The main purpose of Microsoft Active Directory paging is to detect if a range option is present among the options of the returned attributes and to retrieve the complete range of attribute values from the Microsoft Active Directory server. This complete set of attribute values is returned, so that the client application does not have to deal with the range option.
Microsoft Active Directory paging is implemented as a workflow element that is relevant only if the leaf of the workflow element chain is connected to an Active Directory server. You can configure the following properties of an Active Directory Paging workflow element:
The next workflow element in the chain as this workflow element is not a leaf workflow element
An optional list of attributes that can reduce the processing of scanning attributes to detect the range option
To configure support for Microsoft Active Directory paging, create and enable an Active Directory paging workflow element that points to an LDAP proxy workflow element.
The following example creates an Active Directory paging workflow element named ad-paging-we1
that points to the LDAP proxy workflow, proxy-we1
.
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ create-workflow-element --element-name ad-paging-we1 --type ad-paging \ --set next-workflow-element:proxy-we1 --set enabled:true
To improve efficiency, you can configure the Active Directory paging workflow element to scan only specific attributes by setting the multi-valued handled-attributes
property of the workflow element. You can add as many values for this property as required.
By default all attributes are scanned. This can have a direct impact on performance. To reduce the performance impact, list only the attributes that need to be scanned as values of the handled-attributes
property.
The following example modifies the workflow element created in the previous example to scan only for the memberOf
attribute:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \ set-workflow-element-prop --element-name ad-paging-we1 \ --set handled-attributes:memberOf
This section describes the elements of the proxy server configuration that can be managed with Oracle Directory Services Manager, and covers the following topics:
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 that make up a load balancing deployment. For more information, see Section 3.2, "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 18.2, "Connecting to the Server From Oracle Directory Services Manager."
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 backend LDAP servers across which client requests will be balanced.
ODSM attempts to connect to these backend 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 backend 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 backend LDAP server.
For information about the load balancing algorithms, see Section 11.1, "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.
If you have set up a proxy server instance without configuring either load balancing or distribution, you can configure distribution by using ODSM. Before you begin, it is useful to understand the components that make up a distribution deployment. For more information, see Section 3.3, "Configuration 2: Simple Distribution."
To configure distribution by using ODSM, perform the following steps:
Connect to the proxy server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."
Select the Home tab.
Under the Configuration item, select Set Up Distributor.
On the Distribution: Data Partitioning screen, complete the following information:
Select the Number of Partitions.
Select the Distribution Algorithm. For more information about the available distribution algorithms, see Section 11.2, "Data Distribution Using the Proxy."
Enter the Naming Context, or suffix, that will be handled in this distribution deployment.
Select the Network Group in which the distributor will be configured.
Enter the capacity, DN Pattern, or boundaries for each partition, depending on the distribution algorithm that you have selected.
When you have entered all of the partition details, click Next to continue.
On the Distribution: Server Partitions, for each partition, click Add to enter the connection details of each backend LDAP server that will hold the partitioned data.
ODSM attempts to connect to these backend 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 of the required servers, click Next to continue.
On the Distribution: Global Index screen, specify the global index details. For more information about global indexes, see Section 11.3, "Global Index Catalog."
When you have configured the global index, click Next to continue.
On the Distribution: Summary screen, review the distribution configuration and click Finish to complete the configuration.
When you have configured distribution, you can modify any aspect of the configuration on the ODSM Configuration tab.
A new parameter known as the criticality flag is added to configure workflows. By default, the criticality flag is set True.
The following sections describe how to configure criticality in workflows using ODSM. For information about configuring criticality using dsconfig, Section 15.1.4.6, "Configuring Criticality in Workflows."
To configure criticality in workflows using ODSM, perform the following steps:
Connect to the proxy server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."
Select the Configuration tab.
Select the Core Configuration view.
Under Workflows element, select the required workflow for which you want to set the criticality flag.
Select the criticality value (True, False,
or Partial
) that you want to set for the workflow. For instance, click True to set the criticality for the selected workflow element.
ODSM allows you to create, modify, and delete Transformations workflow elements for Oracle Unified Directory Proxy Servers. For more information about transformation workflow element, see Section 14.2.4, "Configuring Workflow Elements With ODSM."
The following sections describe how to configure transformation using ODSM. For information about configuring transformation using dsconfig, Section 11.6.3.2, "Example of Configuring Transformation Using CLI."
This section contains the following topics:
If you are connected to an Oracle Unified Directory Proxy Server, then ODSM allows you to create five different types of transformations. For more information about the types of transformations supported, see Section 11.6.2.1, "Transformation Types."
Note:
If you are connected to an Oracle Unified Directory server instance, then the option to create a new Transformation is not available because transformation functionality is supported by proxy servers only.
To create a transformation using ODSM, follow these steps:
Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."
Select the Configuration tab.
Select the Core Configuration view.
From the Create menu, select Transformation.
From the Transformation submenu, select the desired transformation type.
In this example, consider the following properties for an Outbound Attribute Addition transformation type.
Note:
The properties that appear while creating a transformation vary depending on the type of transformation you create. For more information about each transformation type and the associated properties, see Section 11.6.2.1, "Transformation Types."
In the Name field, type the name for the transformation.
In the Conditions region, enter the following information:
Note:
Conditions are optional. However, at runtime conditions specified here at the transformation level are used in conjunction with those specified at the transformation workflow element level in the transformation workflow element where the transformation is used. For more information about transformation workflow element, see Section 14.2.4, "Configuring Workflow Elements With ODSM."
In the Entry Matching Filter field, type a valid LDAP filter.
In the Entry Parent Suffixes box, click Add to specify the DN that must be an ascendant.
To select an entry, click Select.
In the Entry Picker window, select Tree View to navigate the directory tree and locate the entry, or Search View to search for the entry.
From the Excluded Operations list, select the operations that you want to exclude.
In the Transformation Definition region, enter the following information:
In the Client Attribute field, type the name of the client virtual attribute.
To select a client attribute entry, click Select.
In the Attribute Picker window, select locate the desired entry, or Click Search to search for the entry.
In the Value Definitions box, click Add to specify the value definitions of the client virtual attribute.
Click Define to enter an appropriate value definition. For more information about specifying value definitions, see Section 15.2.4.4, "Selecting Values from Value Definition Screen."
From the Conflict Behavior list, select the desired conflict behavior policy.
Click Virtual in Source to Yes.
Click Create.
This section describes how to modify the properties for a transformation. In this example, modify the properties for an Outbound Attribute Addition transformation type created in Section 15.2.4.1, "Create Transformations."
To modify a transformation, perform the following steps:
Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."
Select the Configuration tab.
Select the Core Configuration view.
Expand the Transformations element.
Click the desired transformation.
Transformation configuration details appear for modification in the right pane.
Modify the required information.
Click Apply.
To delete a transformation, perform the following steps:
Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."
Select the Configuration tab.
Select the Core Configuration view.
Expand the Transformations element.
Select the desired transformation to delete.
The Delete configuration window appears seeking confirmation before deleting.
Click OK.
The Value Definition Builder subscreen allows you to define a value for an attribute that is being added, mapped, or deleted by a transformation.
You can specify the following values:
Constant value: It is used to enter a constant value.
Value of another attribute: It is used to create a new attribute from an existing attribute in the entry that is being processed or to filter a value taken from another attribute.
Value of expression: It is used to create an attribute value or to filter an attribute value by manipulating the value of one or more existing attributes.
Figure 15-8 shows the Value Definition screen.