Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Unified Directory
11g Release 2 (11.1.2)

Part Number E22648-05
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

15 Configuring the Proxy Components

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."

15.1 Managing the Proxy Configuration With dsconfig

This section describes the procedures to manage a proxy configuration with the dsconfig command, and covers the following topics:

15.1.1 Configuring Communication With Remote LDAP Servers

This section describes how to configure communication between a proxy instance and one or more remote LDAP servers. The section covers the following topics:

15.1.1.1 Components of Communication with the Remote Server

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.

15.1.1.2 Configuring LDAP Server Extensions

This section describes how to configure the LDAP server extensions required to communicate with the remote LDAP server. The section covers the following topics:

15.1.1.2.1 To Display the Existing LDAP Server Extensions

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.

15.1.1.2.2 To Display LDAP Server Extension Properties

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."

15.1.1.2.3 To View Advanced LDAP Server Extension Properties

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."

15.1.1.2.4 To Create an LDAP Server Extension

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.

15.1.1.2.5 To Modify the Properties of an LDAP Server Extension

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."

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
15.1.1.2.7 LDAP Data Source Monitoring Connection Properties

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).

15.1.1.3 Configuring Proxy LDAP Workflow Elements

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:

15.1.1.3.1 To Display the Existing Proxy LDAP Workflow Elements

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.

15.1.1.3.2 To Display the Properties of a Proxy LDAP Workflow Element

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

remote-ldap-server-bind-dn and remote-ldap-server-bind-password

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.

15.1.1.3.3 To Create a Proxy LDAP Workflow Element

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."

15.1.1.3.4 To Modify the Properties of a Proxy LDAP Workflow Element

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

15.1.2 Configuring the Bind Mode

When an end user executes an authenticated operation, the proxy LDAP workflow element receives the following two distinct operations:

  1. A BIND operation that authenticates the user against the remote server.

  2. 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-client-identity

Use the client credentials to perform the silent bind.

use-specific-identity

Use the proxy credentials to perform the silent bind.


15.1.2.1 Configuring the Bind Mode Parameters to Optimize the Server

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:

15.1.2.1.1 Configuring the use-client-identity Bind Mode

When 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.

15.1.2.1.2 Configuring the use-specific-identity Bind Mode

When 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.

15.1.3 Configuring Load Balancing With 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.

15.1.3.1 To Configure Load Balancing

  1. Create a load balancing workflow element.

    See Section 15.1.3.2, "Creating a Load Balancing Workflow Element."

  2. Create a load balancing algorithm.

    See Section 15.1.3.3, "Creating a Load Balancing Algorithm.".

  3. Create one load balancing route for each load balancing workflow element.

    See Section 15.1.3.4, "Creating Load Balancing Routes."

15.1.3.2 Creating a Load Balancing Workflow Element

To configure load balancing, you must create a load balancing workflow element using the dsconfig create-workflow-element command. 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.

15.1.3.3 Creating a Load Balancing Algorithm

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.

15.1.3.4 Creating Load Balancing Routes

You should have one load balancing route per data source. Before you create a load balancing route, the load balancing workflow element and load balancing algorithm must already be created.

To create a load balancing route, use the dsconfig create-load-balancing-route command. For example:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  create-load-balancing-route \
  --element-name load-bal-we1 \
  --route-name load-bal-route1 \
  --type failover \
  --set workflow-element:proxy-we1 \
  --set add-priority:1 \
  --set bind-priority:2 \
  --set compare-priority:2 \
  --set delete-priority:1 \
  --set extended-priority:2 \
  --set modify-priority:1 \
  --set modifydn-priority:1 \
  --set search-priority:2 

In this example, load-bal-route1 is the name of the new load balancing route, load-bal-we1 is the name of the existing load balancing workflow element, and proxy-we1 is the name of the LDAP proxy workflow element. The type must be the same as the one defined by the load balancing algorithm associated, in this case failover.

The properties set (in this case priority) are related to the type of load balancing created. For more information about the properties of the routes, linked to the algorithm type see Section 15.1.3.5, "Modifying Load Balancing Properties."

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:

15.1.3.5.1 Setting the Priority in a Failover Algorithm

In a load balancing deployment that uses the failover algorithm, you can modify the proxy workflow element to change the route that is used, as well as the priority of the route for a given operation type.

In a failover algorithm, a priority of 1 is the highest priority and indicates the main route that will be used for a specific operation type. A route with priority 2 (or more) is the secondary route used in case of failure on the primary route. The priority is set for each operation type. This means that a route with a priority of 1 for Add operations, can have a priority of 2 for Bind and Search operations.

For example, if the route load-bal-route1 was initially set as the main route with a priority of 1 for Add operations, but you now want to make it the backup route, you can set the priority to 2 using the following command.

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-load-balancing-route-prop \
  --element-name load-bal-we1 \
  --route-name load-bal-route1
  --set add-priority: 2

Note:

If two routes have the same priority for a given operation type, the choice of the active route which treats the request is random.

15.1.3.5.2 Setting the switch-back Flag

After failover in a load balancing deployment, the backup route continues to handle all incoming requests, even after the priority server that had failed becomes available. Switch-back or failback to the primary route does not automatically occur unless the switch-back flag has been set to true. By default, the switch-back flag is set to false.

The switch-back flag is an advanced property. To set the switch-back flag to true, do the following:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  --advanced set-load-balancing-algorithm-prop \
  --element-name load-bal-we1 \
  --set switch-back:true
15.1.3.5.3 Setting the Saturation Precision for the Optimal or Saturation Algorithm

In a load balancing deployment that uses the optimal or the saturation algorithm, you can set the saturation precision level. The saturation precision is the delta between two saturation levels, and is used to determine the route with the lowest saturation level. By default, the saturation precision level is set to 5.

If you find that the saturation precision level is too low, and that the routes are changing too frequently, you can modify the saturation precision level as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  --advanced set-extension-prop \
  --extension-name proxy1 \
  --set saturation-precision:10
15.1.3.5.4 Setting the Weight of a Proportional Algorithm

Once you have created a load balancing deployment using the proportional algorithm, you can modify the proxy workflow element to change the route used, as well as the weight of a route. The weight can be different for each operation type. The value of the weight should be 0 or more, were 0 indicates that the route will not be used for the specified operation.

Using the interactive mode of dsconfig, you can see that the following properties can be modified:

>>>> Configure the properties of the Proportional Load Balancing Route

        Property          Value(s)
        ---------------------------
    1)  add-weight        1
    2)  bind-weight       1
    3)  compare-weight    1
    4)  delete-weight     1
    5)  extended-weight   1
    6)  modify-weight     1
    7)  modifydn-weight   1
    8)  search-weight     1
    9)  workflow-element  proxy-we1

For example, if you initially set all your routes to a weight of 1 on all operations, then all the servers will handle an equal ratio of operations. However, if you want a remote LDAP server to handle more search requests than the other servers in the deployment, then you can set its search-weight to a higher value, such as 5. To do so, use the following command:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-load-balancing-route-prop \
  --element-name load-bal-we1 \
  --route-name load-bal-route1 \
  --set search-weight:5

Note:

To modify the weight for all operations, you must modify the weight for each operation individually.

To modify load-bal-route1 to handle twice as many operations as the other route, you would set the weight of all operations to 2 (assuming the weight on the other route is set to 1). In other words, run the command as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-load-balancing-route-prop \
  --element-name load-bal-we1 \
  --route-name load-bal-route1 \
  --set add-weight:2 \
  --set bind-weight:2 \
  --set compare-weight:2 \
  --set delete-weight:2 \
  --set extended-weight:2 \
  --set modify-weight:2 \
  --set modifydn-weight:2 \
  --set search-weight:2 

If the weight is set to 0 for any operations, the route will not perform the specified operation. For example, if add-weight is set to 0, then load-bal-route1 will not forward any add requests to the associated remote LDAP server. If all configured routes indicate a weight of 0 for a specific operation, that operation will not be supported.

15.1.3.5.5 Setting the Threshold for a Saturation Algorithm

Once you have created a load balancing deployment using the saturation algorithm, you can modify the proxy workflow element used, the priority of the route, the saturation threshold, and the saturation threshold alert.

With a saturation algorithm, requests are distributed based on two criteria: the priority of the server and the saturation threshold of the server. The saturation threshold is the limit at which the server is considered "maximized" and service may become degraded. In a load balancing deployment with saturation algorithm, requests are sent to the server with the highest priority (1) until the server reaches the saturation threshold indicated.

For example, if you indicate load-bal-route1 as the server with the highest priority, with a threshold of 80%, all requests will be sent to load-bal-route1 until its saturation threshold goes over 80%. Once it exceeds 80%, then requests are routed to the next server in the priority list.

>>>> Configure the properties of the Saturation Load Balancing Route

        Property          Value(s)
        ---------------------------
    1)  alert-threshold   85
    2)  priority          1
    3)  threshold         80
    4)  workflow-element  proxy-we1

To modify the saturation threshold, use the following command:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-load-balancing-route-prop \
  --element-name load-bal-we1 \
  --route-name load-bal-route1 \
  --set threshold:90

In this example, the saturation threshold has been set to 90%.

15.1.3.5.6 Setting the Saturation Threshold Alert

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."

15.1.3.5.7 Setting Client Connection Affinity

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.

15.1.3.5.8 Deleting Load Balancing Elements

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.

15.1.4 Configuring Distribution With 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:

15.1.4.1 To Configure Distribution

  1. Create a distribution workflow element.

    See Section 15.1.4.2, "Creating a Distribution Workflow Element."

  2. Create a distribution algorithm.

    See Section 15.1.4.3, "Creating a Distribution Algorithm."

  3. 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.

15.1.4.2 Creating a Distribution Workflow Element

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.

15.1.4.3 Creating a Distribution Algorithm

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.

15.1.4.4 Creating Distribution Partitions

You can create the following types of distribution partitions:

15.1.4.4.1 Creating a capacity Distribution Partition

To 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.

15.1.4.4.2 Creating a lexico or numeric Distribution Partition

Lexico 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.

15.1.4.4.3 Creating a dnpattern Distribution Partition

Before 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.

15.1.4.4.4 DN Pattern String Syntax

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


15.1.4.4.5 Using DN Pattern 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.

15.1.4.5 Managing Modify DN Requests

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

15.1.4.6 Configuring Criticality in Workflows

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

15.1.4.7 Configuring Criticality in Workflow Elements

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

15.1.4.8 Deleting a Distribution Configuration

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.

15.1.5 Configuring DN Renaming With 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.

15.1.5.1 Modifying a DN Renaming Configuration

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

  1. To view the current DN renaming properties, use the dsconfig get-workflow-element-prop command.

  2. 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.

15.1.6 Configuring RDN Changing With 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.

15.1.6.1 Modifying a RDN Renaming Configuration

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

  1. To view the current RDN renaming properties, use the dsconfig get-workflow-element-prop command.

  2. 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.

15.1.7 Configuring Global Indexes By Using the Command Line

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:

15.1.7.1 Configuring Global Index Catalogs by Using 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:

15.1.7.1.1 To Create a Global Index Catalog Containing Global Indexes

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.

  1. 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.

  2. 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.

  3. 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."

  4. 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."

  5. 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."

15.1.7.1.2 To View Global Index Catalog Properties

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
15.1.7.1.3 Modifying the Properties of a Global Index Catalog

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.

15.1.7.1.4 To Modify the Properties of a Global Index Catalog

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
15.1.7.1.5 To Modify Multi-Valued Global Index Catalog Properties

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

  1. 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
    
  2. 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
    
15.1.7.1.6 To Reset Global Index Catalog Properties To the Default Values

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
15.1.7.1.7 To View Global Index Properties

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.

15.1.7.1.8 To Import Content into a Global Index Catalog

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
15.1.7.1.9 To Export Contents of a Global Index Catalog to a Directory

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
15.1.7.1.10 To Associate a Global Index Catalog With a Distribution Element

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."

15.1.7.1.11 To Disassociate a Global Index Catalog From a Distribution Element

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
15.1.7.1.12 To Add a Global Index to a Global Index Catalog

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
15.1.7.1.13 To Remove a Global Index From a Global Index Catalog

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

15.1.7.2 Replication of Global Index Catalogs

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:

15.1.7.2.1 To Create a Replicated Topology and Enable Global Index Catalog Replication

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

Description of Figure 15-1 follows
Description of "Figure 15-1 Replicated Global Index Catalogs"

  1. Install at least two proxy instances in your server topology.

    These instances should be on separate physical machines, for redundancy.

  2. 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."

  3. 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.

  4. 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."

  5. 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."

15.1.7.2.2 To Enable Global Index Catalog Replication

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.

15.1.7.2.3 To Initialize Global Index Catalog Replication

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.

  1. 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
    
  2. 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."

15.1.7.2.4 To Disable Global Index Catalog Replication

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.

15.1.7.2.5 To View the Status of a Replicated Global Index Catalog Configuration

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.

15.1.7.2.6 Logging of Replication Activities

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."

15.1.7.2.7 Lifecycle Examples for Replicated Global Index Catalogs

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.

  1. Issue the start-ds command on proxy instance 3.

  2. 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

Description of Figure 15-2 follows
Description of "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.

  1. First, run the command gicadm add-index mail on each of the three proxy instances.

  2. 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.

  3. Run split-ldif to generate GIC content in the specified directory.

  4. On proxy instance 1, execute the command gicadm import --importDirectory directory-name.

  5. 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

Description of Figure 15-3 follows
Description of "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.

  1. 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

Description of Figure 15-4 follows
Description of "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.

  1. On the new proxy instance 4, execute the gicadm create-catalog command.

  2. Run the commandsgicadm add-index cn, gicadm add-index sn, and gicadm add-index mail.

  3. Execute the gicadm associate command.

  4. 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.

  5. Run the initialize replication --from proxy 1 command.

Figure 15-5 Adding a Proxy to a Replicated Topology

Description of Figure 15-5 follows
Description of "Figure 15-5 Adding a Proxy to a Replicated Topology"

15.1.7.3 Configuring Controls Required by the Global Index Catalog with Oracle Unified Directory

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

15.1.8 Configuring Microsoft Active Directory Paging

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

15.1.8.1 Configuring Active Directory Paging Workflow Elements

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

15.1.8.2 Scanning Specific Attributes Returned by an Active Directory

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

15.2 Managing the Proxy Configuration With ODSM

This section describes the elements of the proxy server configuration that can be managed with Oracle Directory Services Manager, and covers the following topics:

15.2.1 Configuring Load Balancing With ODSM

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:

  1. Connect to the proxy server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Home tab.

  3. Under the Configuration item, select Set up Load Balancer.

  4. 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.

  5. When you have added all the backend LDAP servers, click Next to continue.

  6. 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."

  7. When you have specified the load balancing options, click Next to continue.

  8. 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.

  9. When you have added all of the required naming contexts, click Next to continue.

  10. 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.

15.2.2 Configuring Distribution With ODSM

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:

  1. Connect to the proxy server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Home tab.

  3. Under the Configuration item, select Set Up Distributor.

  4. 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.

  5. When you have entered all of the partition details, click Next to continue.

  6. 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.

  7. When you have added all of the required servers, click Next to continue.

  8. On the Distribution: Global Index screen, specify the global index details. For more information about global indexes, see Section 11.3, "Global Index Catalog."

  9. When you have configured the global index, click Next to continue.

  10. 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.

15.2.3 Configuring Criticality in Workflows With ODSM

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:

  1. Connect to the proxy server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Configuration tab.

  3. Select the Core Configuration view.

  4. Under Workflows element, select the required workflow for which you want to set the criticality flag.

  5. 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.

    Figure 15-6 Criticality Flag

    Description of Figure 15-6 follows
    Description of "Figure 15-6 Criticality Flag"

15.2.4 Configuring Transformations With ODSM

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:

15.2.4.1 Create Transformations

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:

  1. Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Configuration tab.

  3. Select the Core Configuration view.

  4. From the Create menu, select Transformation.

  5. From the Transformation submenu, select the desired transformation type.

    Figure 15-7 Transformation Types

    Description of Figure 15-7 follows
    Description of "Figure 15-7 Transformation Types"

    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."

  6. In the Name field, type the name for the transformation.

  7. 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."

    1. In the Entry Matching Filter field, type a valid LDAP filter.

    2. 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.

    3. From the Excluded Operations list, select the operations that you want to exclude.

  8. In the Transformation Definition region, enter the following information:

    1. 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.

    2. 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."

  9. From the Conflict Behavior list, select the desired conflict behavior policy.

  10. Click Virtual in Source to Yes.

  11. Click Create.

15.2.4.2 Modifying Transformations

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:

  1. Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Configuration tab.

  3. Select the Core Configuration view.

  4. Expand the Transformations element.

  5. Click the desired transformation.

    Transformation configuration details appear for modification in the right pane.

  6. Modify the required information.

  7. Click Apply.

15.2.4.3 Deleting Transformations

To delete a transformation, perform the following steps:

  1. Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Configuration tab.

  3. Select the Core Configuration view.

  4. Expand the Transformations element.

  5. Select the desired transformation to delete.

    The Delete configuration window appears seeking confirmation before deleting.

  6. Click OK.

15.2.4.4 Selecting Values from Value Definition Screen

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.

Figure 15-8 Value Definition Screen

Description of Figure 15-8 follows
Description of "Figure 15-8 Value Definition Screen"