| Skip Navigation Links | |
| Exit Print View | |
|
Oracle Fusion Middleware Administration Guide for Oracle Unified Directory 11g Release 1 (11.1.1) |
| Skip Navigation Links | |
| Exit Print View | |
|
|
Oracle Fusion Middleware Administration Guide for Oracle Unified Directory 11g Release 1 (11.1.1) |
1. Starting and Stopping the Server
2. Configuring the Server Instance
3. Configuring the Proxy Components
Managing the Proxy Configuration With dsconfig
Listing LDAP Server Extensions
Listing Proxy Workflow Elements
Viewing LDAP Proxy Element Properties
Viewing LDAP Server Extension Properties
Viewing Advanced LDAP Server Extension Properties
Viewing Proxy Workflow Element Properties
Creating an LDAP Server Extension
Creating a Proxy LDAP Workflow Element
Modifying Proxy LDAP Workflow Element Properties
Modifying LDAP Server Extension Properties
Modifying LDAP Server Extension Advanced Properties
LDAP Data Source Monitoring Connection Properties
Configuring Load Balancing With dsconfig
Creating a Load Balancing Workflow Element
Creating a Load Balancing Algorithm
Creating Load Balancing Routes
Modifying Load Balancing Properties
Setting the Priority in Failover Algorithm
Setting the Saturation Precision for the Optimal or Saturation Algorithm
Setting the Weight of a Proportional Algorithm
Setting the Threshold for a Saturation Algorithm
Setting the Saturation Threshold Alert
Setting Client Connection Affinity
Deleting Load Balancing Elements
Configuring Distribution With dsconfig
Creating a Distribution Workflow Element
Creating a Distribution Algorithm
Creating Distribution Partitions
Creating a capacity Distribution Partition
Creating a lexico or numeric Distribution Partition
Creating a dnpattern Distribution Partition
Using DN Pattern negative-match
Configuring Global Indexes By Using the Command Line
Configuring Global Index Catalogs by Using gicadm
Modifying the Properties of a Global Index Catalog
Replication of Global Index Catalogs
Logging of Replication Activities
Lifecycle Examples for Replicated Global Index Catalogs
Configuring Controls Required by the Global Index Catalog with Oracle Unified Directory
Managing the Proxy Configuration With ODSM
4. Configuring Security Between Clients and Servers
5. Configuring Security Between the Proxy and the Data Source
6. Managing Oracle Unified Directory With Oracle Directory Services Manager
10. Managing Users and Groups With dsconfig
11. Managing Password Policies
In order to connect to a remote LDAP directory server, the Oracle Unified Directory proxy needs to have the following two elements configured:
LDAP server extension
LDAP proxy workflow element
This topic covers all the administration tasks possible for a proxy LDAP workflow element and LDAP server extension once a Oracle Unified Directory proxy is installed.
The following examples describe how to configure the LDAP server extensions using the dsconfig command.
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 (-w). The following examples use the -X option to trust all certificates.
You can list the following LDAP proxy elements:
LDAP server extensions. See Listing LDAP Server Extensions.
LDAP proxy workflow element. See Listing Proxy Workflow Elements.
To display all the LDAP server extensions associated to your deployment, use the dsconfig list-extensions command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ list-extensions
The extensions will be listed, along with the extension type.
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 configured with Oracle Unified Directory proxy.
To display all the proxy workflow elements associated to your deployment, use the dsconfig list-workflow-elements command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ list-workflow-elements
The proxy workflow elements are the ones with the type proxy-ldap.
You can view the properties of the following LDAP proxy elements:
LDAP server extensions. See Viewing LDAP Server Extension Properties.
LDAP proxy workflow elements. See Viewing Proxy Workflow Element Properties.
To view the LDAP server extensions properties, use the dsconfig get-extension-prop command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ get-extension-prop \ --extension-name proxy1
Properties similar to the following are displayed.
Property Value(s)
------------------------------------
1) enabled true
2) monitoring-bind-dn -
3) monitoring-bind-password -
4) remote-ldap-server-address DS-proxy1
5) remote-ldap-server-port 3389
By viewing the LDAP server extension properties, you can gather the following information:
indicates if the LDAP server extension is enabled (true) or not (false)
indicate the address and port of the remote LDAP server that the LDAP server extension will forward requests to
are the credentials of the user that the extension will use to perform monitoring of the data source. If blank, the monitoring will be performed anonymously, which is the default
To configure these properties, see Monitoring the Server With LDAP.
To view all the LDAP server extensions properties, use the dsconfig --advanced get-extension-prop command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -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-base-dn ""
4) monitoring-bind-dn -
5) monitoring-bind-password -
6) monitoring-check-interval 30000
7) monitoring-connect-timeout 5000
8) monitoring-inactivity-timeout 120000
9) monitoring-search-filter (|(objectClass=*)(objectClass=ldap
SubEntry))
10) monitoring-search-timeout 5000
11) pool-increment 5
12) pool-initial-size 10
13) pool-max-size 25
14) pool-max-write 0
15) pool-release-connection-interval 300000
16) pool-use-max-write false
17) proxied-auth-use-v1 false
18) remote-ldap-server-address DS-proxy1
19) remote-ldap-server-connect-timeout 10000
20) remote-ldap-server-port 3389
21) remote-ldap-server-read-only false
22) remote-ldap-server-read-timeout 10000
23) remote-ldap-server-ssl-policy never
24) remote-ldap-server-ssl-port 636
25) saturation-precision 5
26) ssl-client-alias -
27) ssl-key-manager-provider -
28) ssl-trust-all false
29) 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 Modifying LDAP Server Extension Properties.
For information about the monitoring properties, see LDAP Data Source Monitoring Connection Properties. For information about the SSL (security) properties, see Chapter 5, Configuring Security Between the Proxy and the Data Source.
To view the proxy workflow element properties, use the dsconfig get-workflow-element-prop command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ get-workflow-element-prop \ --element-name proxy-we1
Properties similar to the following are displayed.
Property Value(s)
----------------------------------------------------------
1) client-cred-mode use-client-identity
2) enabled true
3) ldap-server-extension proxy1
4) remote-ldap-server-bind-dn -
5) remote-ldap-server-bind-password-file -
6) workflow-element-id proxy-we1
With the proxy workflow element properties you can see the following information:
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 5, Configuring Security Between the Proxy and the Data Source.
indicates if the LDAP server extension is enabled (true) or not (false)
the name of the LDAP server extension that the workflow element is associated to
are the credentials of the user that Oracle Unified Directory proxy uses to connect to the remote LDAP server when client-cred-mode is use-specific-identity or use-proxy-auth. When using --advanced, you can also see remote-ldap-server-bind-password.
Note - To view the remote-ldap-server-bind-password you must use dsconfig get-workflow-element-prop --advanced command.
To add an LDAP proxy you must create:
first an LDAP server extension for each remote LDAP server used in the deployment. See Creating an LDAP Server Extension.
secondly, a proxy LDAP workflow element, associated to an LDAP server extension. See Creating a Proxy LDAP Workflow Element.
To create an LDAP server extension, use the dsconfig create-extension command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ create-extension \ --extension-name DS-proxy5 \ --type ldap-server \ --set enabled:true \ --set remote-ldap-server-address:DS5-hostname
To create an LDAP server extension, the 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 that this extension is associated to, in the option --set remote-ldap-server-address. You can specify either the hostname or the IP address of the remote LDAP server.
If you do not specify the port, as in the example above, the port 389 will be used by default. If you want to use a different port, then specify -–set remote-ldap-server-port with the correct port address.
You must have an existing LDAP server extension before creating a proxy LDAP workflow element.
To create a proxy LDAP workflow element, use the dsconfig create-workflow-element command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -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
To create a proxy LDAP workflow element, the type must be proxy-ldap. The name of the new proxy LDAP workflow element is defined by element-name, in this example proxy-we5.
You must also set the client credential mode. The client credential mode indicates how the proxy will connect 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.
Note - 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 users exists on the remote LDAP server, rather set the client credential mode to use-specific-identity.
For more information, see Chapter 5, Configuring Security Between the Proxy and the Data Source.
You can modify the following elements:
The proxy LDAP workflow element properties. See Modifying Proxy LDAP Workflow Element Properties.
The LDAP server extension properties. See Modifying LDAP Server Extension Properties.
For information about advanced LDAP server extension properties, see Modifying LDAP Server Extension Advanced Properties.
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 Oracle Unified Directory proxy uses to connect to the remote LDAP server (remote-ldap-server-bind-dn, remote-ldap-server-bind-password, and/or remote-ldap-server-bind-password-file)
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" -w password -X -n \ set-workflow-element-prop --advanced \ --element-name proxy-we5 \ --set remote-ldap-server-bind-dn:uid=Specific\ User,dc=example,dc=com \ --set remote-ldap-server-bind-password:password \ --set ldap-server-extension:DS-proxy3 \ --set client-cred-mode:use-specific-identity
To modify the LDAP server extension properties, use the set-extension-prop command.
You will be able to:
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" -w password -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 Modifying LDAP Server Extension Advanced Properties.
You can configure the following advanced properties:
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.
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 details, see Modes of Secure Connection.
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.
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.
The time after which a connection is considered by the Oracle Unified Directory 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 300 000 milliseconds (5 minutes).
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.
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 Supported LDAP Controls in Oracle Fusion Middleware Architecture Reference for Oracle Unified Directory.
The timeout for reads. If the timeout is reached before the remote LDAP server sends back a response, an error is returned by Oracle Unified Directory proxy to the client. By default, this value is 10 000 milliseconds.
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 the buffer before the saturation is taken into account. In other words, by default the saturation can vary by 5% before it is taken into account.
The monitoring properties are described in LDAP Data Source Monitoring Connection Properties.
The SSL properties are security features. For information on these properties, see Chapter 5, 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 your Oracle Unified Directory proxy so that it receives a maximum of requests, then you can increase the pool-max-size as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ set-extension-prop --advanced \ --extension-name DS-proxy5 \ --set pool-max-size:500
Using the dsconfig --advanced command for the LDAP server extension, you can view or change the following monitoring properties.
Note - All properties relate to proactive monitoring unless otherwise specified.
The search base DN used by the monitoring functionality of the proxy to perform searches on remote LDAP servers. The default value is "".
The bind DN of the user who wants to manage monitoring of the remote LDAP server. By default this value is undefined, which provides for anonymous access.
The password of the user who wants to manage monitoring of the remote LDAP server.
The monitoring check interval. This is the interval at which the proxy proactive monitoring checks the data source. The default value is 30000 milliseconds.
The maximum time after which the proactive monitoring facility will stop attempting to connect to the remote LDAP server. The default value is 5000 milliseconds. 0 means unlimited.
The time interval 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.
The search filter that the proactive monitoring facility uses to perform searches on the remote LDAP server. The default value is (|(objectClass=*)(objectClass=ldapSubEntry))
The maximum time during which the proactive monitoring facility attempts to retrieve the entry in a search operation. The default value is 5000 milliseconds.
The maximum time 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. This is a reactive monitoring property.
The maximum time during which monitoring attempts to connect to the remote server before the connection is regarded as having failed. 0 means unlimited. The default is 10 000 milliseconds. This is a reactive monitoring property.
In order to forward the client requests to the remote LDAP server using load balancing feature of the Oracle Unified Directory proxy, 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 topic 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 in Oracle Fusion Middleware Installation Guide for Oracle Unified Directory.
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 (-w), and use the -X option to trust all certificates.
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" -w password -X -n \ create-workflow-element \ --element-name load-bal-we1 \ --type load-balancing \ --set enabled:true
To create a load balancing workflow element, the type must be load-balancing. The name of the workflow element is defined by element-name, in this example load-bal-we1.
In order to determine how the requests will be forwarded in a load balancing deployment, you must configure the load balancing algorithm. The load balancing algorithm set determines how client requests will be dispatched across the pool of remote LDAP servers. The possible load balancing types are: failover, optimal, proportional, or saturation.
To create the load balancing algorithm, you must have a load balancing workflow element. See 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" -w password -X -n \ create-load-balancing-algorithm \ --element-name load-bal-we1 \ --type failover
To create a load balancing algorithm, the you must indicate the type as proportional, optimal, failover, or saturation. The name of the workflow element is defined by element-name, in this example load-bal-we1.
You should have one load balancing route per data source used in your deployment.
To create the load balancing routes, 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" -w password -X -n \ create-load-balancing-route \ --element-name load-bal-we1 \ --route-name load-bal-route1 \ --type failover \ --set workflow-element:proxy-we1 \ --set add-priority:1 \ --set bind-priority:2 \ --set compare-priority:2 \ --set delete-priority:1 \ --set extended-priority:2 \ --set modify-priority:1 \ --set modifydn-priority:1 \ --set search-priority:2
In this example, load-bal-route1 is the name of the new load balancing route, load-bal-we1 is the name of the existing load balancing workflow element, and proxy-we1 is the name of the LDAP proxy workflow element. The type must be the same as the one defined by the load balancing algorithm associated, in this case failover.
The properties set (in this case priority) are related to the type of load balancing created. For more information about the properties of the routes, linked to the algorithm type see Modifying Load Balancing Properties.
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:
|
* saturation precision is a property of the LDAP server extension.
To modify load balancing route properties, use the dsconfig set-load-balancing-route-prop command.
New routes can be added on a running algorithm, or routes can be deleted or have their priorities modified without the need to restart the server.
Note - You cannot modify the load balancing algorithm type.
To change a failover load balancing deployment to a proportional one, for example, you must create a new load balancing deployment. See Configuring Load Balancing With dsconfig.
Once you have created a load balancing deployment using the failover algorithm, you can modify the proxy workflow element to change the route 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, while the route with priority 2 (or more) is the secondary route used in case of failure on the primary route. The priority must be set for each operation type. This means that the route that has a priority of 1 for Add operations, could 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 set to 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 line.
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -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 not deterministic.
After failover in a load balancing deployment, the route with the backup route continues to handle all incoming requests, even once the priority server which had failed becomes available again. Switch-back 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" -w password -X -n \ --advanced set-load-balancing-algorithm-prop \ --element-name load-bal-we1 \ --set switch-back:true
When you set load balancing to use the optimal or the saturation algorithm, you can set the saturation precision level. The saturation precision is the delta between two saturation levels which 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" -w password -X -n \ --advanced set-extension-prop \ --extension-name proxy1 \ --set saturation-precision:10
Once you have created a load balancing deployment using the proportional algorithm, you can modify the proxy workflow element to change the route used, as well as the weight of a route. The weight can be different for each operation type. The value of the weight should be 0 or more, were 0 indicates that the route will not be used for the specified operation.
Using the interactive mode of dsconfig, you can see that the following properties can be modified:
>>>> Configure the properties of the Proportional Load Balancing Route
Property Value(s)
---------------------------
1) add-weight 1
2) bind-weight 1
3) compare-weight 1
4) delete-weight 1
5) extended-weight 1
6) modify-weight 1
7) modifydn-weight 1
8) search-weight 1
9) workflow-element proxy-we1
For example, if you initially set all your routes to a weight of 1 on all operations, then all the servers will handle an equal ratio of operations. However, if you want a remote LDAP server to handle more search requests than the other servers in the deployment, then you can set its search-weight to a higher value, such as 5. To do so, use the following command:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ set-load-balancing-route-prop \ --element-name load-bal-we1 \ --route-name load-bal-route1 \ --set search-weight:5
Note - If you want to modify the weight for all the operations, you will have to modify the weight for each operation.
If you want to modify load-bal-route1 to handle twice the operations as your other route, then you would need to 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" -w password -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 you set the weight to 0 for any of the operations, then the route will not perform the specified operation. For example, if you set add-weight to 0, as follows, then load-bal-route1 will not forward any add requests to the associated remote LDAP server. Moreover, if all the routes indicate a weight of 0 for a specific operation, then that operation will not be supported.
Once you have created a load balancing deployment using the saturation algorithm, you can modify the proxy workflow element used, the priority of the route, the saturation threshold, and the saturation threshold alert.
With a saturation algorithm, requests are distributed based on two criteria: the priority of the server and the saturation threshold of the server. The saturation threshold is the limit at which the server is considered “maximized” and service may become degraded. In a load balancing deployment with saturation algorithm, requests are sent to the server with the highest priority (1) until the server reaches the saturation threshold indicated.
For example, if you indicate load-bal-route1 as the server with the highest priority, with a threshold of 80%, all requests will be sent to load-bal-route1 until its saturation threshold goes over 80%. Once it exceeds 80%, then requests are routed to the next server in the priority list.
>>>> Configure the properties of the Saturation Load Balancing Route
Property Value(s)
---------------------------
1) alert-threshold 85
2) priority 1
3) threshold 80
4) workflow-element proxy-we1
To modify the saturation threshold, use the following command:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ set-load-balancing-route-prop \ --element-name load-bal-we1 \ --route-name load-bal-route1 \ --set threshold:90
In this example, the saturation threshold has been set to 90%.
The saturation threshold alert is used to set at which point a notification will be sent to the system administrator to indicate that the server has passed the saturation limit. Generally, the saturation threshold alert is set higher than the saturation limit, in order to indicate if the saturation continues to increase past the saturation threshold (which may indicate a problem). The alert should bet set with an acceptable buffer, as there may be a short delay in which saturation continues to increase slightly before requests are forwarded to another route.
To modify the saturation threshold, use the following command:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -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. This may imply receiving notifications even in cases where the saturation threshold is not reached. That is, a saturation threshold alert is sent, but the saturation limit drops and does not reach the saturation threshold. However, the requests will only be sent to the next priority route when the saturation threshold is reached.
For more information on setting the notification message, see Configuring Alerts and Account Status Notification Handlers.
When client connection affinity is defined, requests from a specified client connection are distributed 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 Creating a Network Group Quality of Service Policy.
Example 3-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.
If you want to delete a complete load balancing workflow (workflow element, algorithm, and routes), then you only need to delete the load balancing workflow element. When you delete a load balancing workflow element, the associated load balancing algorithm and routes are silently deleted.
In order to forward the client requests to the remote LDAP server using the distribution feature of the Oracle Unified Directory proxy, you need:
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, which defines how data is distributed. On the other hand, one distribution algorithm can use many partitions.
This topic covers all the administration tasks possible for a distribution workflow element, distribution algorithm, and distribution partitions once a Oracle Unified Directory proxy with distribution is setup. For information on setting up a deployment with distribution using the vdp-setup GUI, see To Configure Simple Distribution in Oracle Fusion Middleware Installation Guide for Oracle Unified Directory.
The following examples describe how to configure distribution using the dsconfig command.
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 (-w). The following examples use the -X option to trust all certificates.
For a capacity-based distribution see Creating a capacity Distribution Partition.
For a lexico or numeric distribution see Creating a lexico or numeric Distribution Partition.
If you are using DN pattern algorithm, see Creating a dnpattern Distribution Partition.
To configure distribution, you must create a distribution workflow element using the dsconfig create-workflow-element command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ create-workflow-element \ --element-name distrib-we \ --type distribution \ --set enabled:true \ --set base-dn:ou=people,dc=example,dc=com
To create a distribution workflow element, the type must be distribution. The name of the workflow element is defined by element-name, in this example distrib-we.
Note - When declaring the base-dn using the create-workflow-element subcommand as shown above, ensure that you specify the full tree structure.
To complete the distribution element of your configuration, create the distribution algorithm and the appropriate partitions.
To determine how the requests will be forwarded in a distribution deployment, you must configure the distribution algorithm. The algorithm set determines how the data is partitioned and to which partition a request is sent. The possible distribution types are: numeric, lexico, or dnpattern.
To create the distribution algorithm, you must have a distribution workflow element. See 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" -w password -X -n \ create-distribution-algorithm \ --element-name distrib-we \ --type numeric \ --set distribution-attribute:uid
The name of the workflow element is defined by element-name, in this example distrib-we. The distribution algorithm type must be set as capacity, numeric, lexico, or dnpattern. The properties set depend on the algorithm type. In this example, distribution-attribute must be set, as the algorithm type is numeric.
You can create the following types of distribution partitions:
capacity. See Creating a capacity Distribution Partition
lexico or numeric. See Creating a lexico or numeric Distribution Partition
dnpattern. See Creating a dnpattern 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" -w password -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 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 Configuring an LDAP Proxy.
When creating a capacity distribution partition, you must indicate the maximum number of entries the partition can hold, for example 1000.
Lexico and numeric distribution are very similar, and as such, to create a distribution partition for lexico or numeric distribution, you must set the same properties. 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" -w password -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 Configuring an LDAP Proxy.
When creating a lexico or numeric distribution partition, you must indicate the lower and upper boundaries of the partition. Oracle Unified Directory 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.
Note - 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 Configuring Distribution With dsconfig.
To create the dnpattern distribution partitions, 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" -w password -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 must be an simple integer, as it will be used for the global index catalog reference. To create a distribution partition, you must also indicate the name of the existing distribution workflow (here distrib-we), and the name of the associated workflow element, such as an LDAP proxy (in this example proxy-we1). The type must be the same as the one defined by the distribution algorithm associated, in this case dnpattern.
In a distribution scenario that uses a dnpattern algorithm, requests are sent to a partition when the request RDNs below the distribution base DN match the DN string pattern. For example, if the distribution base DN is ou=people,dc=example,dc=com and the request base DN is uid=1,ou=people,dc=example,dc=com, the check against the string pattern is done on the RDN uid=1.
Similarly, if the distribution base DN is ou=people,dc=example,dc=com and the request base DN is uid=1,ou=region1,ou=people,dc=example,dc=com, the check against the string pattern is done on the RDNs uid=1,ou=region1.
The DN string pattern must comply with the DN syntax and with a subset of the Java Pattern class.
|
The following quantifiers can be used:
|
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" -w password -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 with uid not starting with 1, 2, or 3, with n characters following will be forwarded to the partition.
Modifying a DN where the new entry remains in the same partition as the original entry is supported. However, by default, Oracle Unified Directory proxy does not allow users 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 originally, then you must set the force-modify-dn flag to true.
For example, assuming you have set the force-modify-dn flag to true and you have two partitions: Partition 1 with uid boundaries from 0–999 and Partition 2 with uid boundaries from 1000–1999. If you want to modify an entry with the uid 1 to 1001, the change will be allowed, but the entry with the uid 1001 will remain in Partition 1. It is not moved to Partition 2.
If you then search for uid=1001, you will get an error indicating that no such entry is found. To be able to find the entry, you should use a global index catalog. This will ensure that the entries that are modified are always found. To configure a global index catalog, see Configuring Global Indexes By Using the Command Line.
To set force-modify-dn flag to true, use the command as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ --advanced set-workflow-element-prop \ --element-name distrib-we \ --set force-modify-dn:true \
If you want to delete a complete distribution workflow (workflow element, algorithm, and partitions), then you only need to delete the workflow element. When you delete a distribution workflow element, the associated distribution algorithm and partitions are silently deleted.
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. An Oracle Unified Directory 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 Supported LDAP Controls in Oracle Fusion Middleware Architecture Reference for Oracle Unified Directory.
Global index catalogs are stored in a Berkely 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 gicadm in Oracle Fusion Middleware Command-Line Usage Guide for Oracle Unified Directory.
The procedures in this section assume that the Oracle Unified Directory proxy is deployed in a distribution architecture and presume that you are using the default Oracle Unified Directory proxy administration port (4444).
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.
Oracle Unified Directory proxy must be deployed for distribution.
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ create-catalog --catalogName sampleCatalog
The catalog name must be unique.
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 -D "cn=Directory Manager" -p 4444 -w password -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.
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ associate --catalogName sampleCatalog \ --distributionWorkflowElement myDistributionName
For information about workflow elements, see Configuring Workflow Elements With dsconfig. For information about distribution, see Configuring Distribution With dsconfig.
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 split-ldif in Oracle Fusion Middleware Command-Line Usage Guide for Oracle Unified Directory.
For more information see To Import Content into a Global Index Catalog.
Global index catalog properties are related to global index catalog replication. For a list of the global index catalog properties and an explanation of their use, see Modifying the Properties of a Global Index Catalog.
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -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
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ get-catalog-prop --catalogName sampleCatalog \ --property heartbeat-interval
Global index properties are related to the replication of global index catalogs. The following global index catalog properties are available:
replication-server: This lists the servers in the replication topology, in the format host:port.
Note - This property should not be modified with set-catalog-prop. This property is modified using 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.
Note - This property should not be modified.
window-size: Specifies the window size that the instance will use when communicating with replication servers. Default value is 100.
Syntax: 0 <= INTEGER or text.
heartbeat-interval: Specifies the heartbeat interval that the instance will use when communicating with replication servers. The instance expects a regular heartbeat from the replication server within the specified interval. If a heartbeat is not received within this interval, the instance closes its connection and connects to another replication server.
Syntax: 100 ms <= DURATION (ms)
group-id: The id associated with a specific replicated domain. This value defines the group id of the replicated domain. The replication system will preferably connect and send updates to replicate to a replication server with the same group id as itself.
Syntax: 1 <= INTEGER <= 127
Note - This property should not be modified.
For a list of the global index catalog properties, see Modifying the Properties of a Global Index Catalog.
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ set-catalog-prop --catalogName sampleCatalog \ --set property:value
For example, one of the properties that can be modified is the heartbeat interval. In this case, use:
--set heartbeat-interval:500
For multi-valued global index or global index catalog properties, you can add or remove a value using the --add or --remove options.
For global index catalog, only the property replication-server can be multi-valued.
Note - For multi-valued global index properties, use the set-index-prop subcommand instead.
$ gicadm -h localhost -D "cn=Directory Manager" -p replicationPort -w password -X \ set-catalog-prop --catalogName sampleCatalog \ --add replication-server:hostname
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ set-catalog-prop --catalogName sampleCatalog \ --remove replication-server:value \
If you have modified any of the global index catalog properties and want to reset them to the default values, use the following procedure.
For example, to reset the heartbeat interval:
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ set-catalog-prop --catalogName nyCatalog \ --reset heartbeat-interval
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -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-cache global-index-attribute : telephoneNumber
Note - Typically these values should not be modified.
You can import the contents of a specific file into one or multiple global indexes in a global index catalog. You must specify the name of the catalog into which the content of the file is to be imported. You can filter the content of the file to data related to a particular index by optionally providing the attributeName parameter.
The data file to be imported can be created by executing the split-ldif command or from executing the gicadm export command, for example.
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ import --file file --catalogName sampleCatalog
The path to the file from which the contents of the catalog are imported is declared by file. The global index catalog is declared by its name.
Note - If the Oracle Unified Directory proxy stops while a gicadm import task is being executed, the global index catalog back end is set to enabled=false. In this case, re-enable the global index back end using the following command, where sampleCatalog is the name of the global index catalog:
$ dsconfig -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ set-backend-prop --backend-name sampleCatalog \ set enabled:true
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ export --exportDirectory directory-path --catalogName sampleCatalog
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ associate --catalogName sampleCatalog \ --distributionWorkflowElement myDistributionName
Once the global index catalog is associated to 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 Configuring Workflow Elements With dsconfig.
To disassociate a global index catalog from a distribution topology, you must know the distribution workflow element with which the global index catalog is associated. To confirm the name of the distribution workflow element that is using the global index catalog, view the properties of the distribution topology by using the dsconfig --get-workflow-element-prop command.
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ disassociate --distributionWorkflowElement myDistributionName
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.
You must already have a global index catalog.
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ add-index --catalogName sampleCatalog --attributeName telephoncNumber
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ remove-index --catalogName sampleCatalog --attributeName telephoneNumber
To ensure high availability, global index catalogs should be replicated. A standard hardware load balancer can be used and replication of global index catalogs can be configured in a deployment as shown by the graphic in Multiple Replicated Proxies in Oracle Fusion Middleware Deployment Planning Guide for Oracle Unified Directory.
Follow the steps below in order to create a replicated topology with three proxy instances, and enable global index catalog replication, as illustrated below.
For redundancy, it is recommended that these instances be on separate physical machines.
For more information on configuring a global index catalog using the gicadm command, see To Create a Global Index Catalog Containing Global Indexes.
The Oracle Unified Directory 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 instance of the Oracle Unified Directory proxy declared in the command is referred to as the remote instance. For more information on running the gicadm enable-replication command, see To Enable Global Index Catalog Replication.
Repeat this step for each proxy that is part of your replicated topology.
Otherwise, you can import the LDIF file to each proxy that is part of the topology. See To Import Content into a Global Index Catalog.
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 Modifying Load Balancing Properties.
This command configures replication without actually initializing replication. This 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 --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 and a bind password of bindPassword.
If you created global index catalogs using vdp-setup 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 in Oracle Fusion Middleware Installation Guide for Oracle Unified Directory.
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ enable-replication \ --catalogName sampleCatalog --adminUID adminUID --localReplicationPort 8989 \ --remoteReplicationPort 8989 --remoteAdminPort 4444 --remoteHost host
This command updates the configuration of Oracle Unified Directory proxy to replicate the content of the global index catalog called sampleCatalog on the local host. If one of the instances of Oracle Unified Directory proxy in the topology already replicates the global index catalog, this command updates the configuration of all other instances of Oracle Unified Directory proxy in the topology. It is therefore sufficient to execute the gicadm enable-replication once for the first two instances of Oracle Unified Directory proxy in the topology, and once for each new instance of Oracle Unified Directory proxy added to extend the topology.
The Oracle Unified Directory 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 instance of Oracle Unified Directory proxy.
You can optionally declare the password for the local instance of Oracle Unified Directory proxy in a file, using the --adminPasswordFile suboption.
You can optionally declare the password for the remote instance of Oracle Unified Directory proxy in a file, using the --remoteBindPasswordFile suboption.
You can optionally declare a DN and associated password for binding to the remote server, using the --remoteBindDN and --remoteBindPassword suboptions. If you do not declare these, the global administrator declared by --adminUID will be used to bind.
You can also optionally require the communication through the replication port of the local server to be secure, using the --localSecureReplication suboption, and the communication through the replication port of the remote server to be secure, using the --remoteSecureReplication suboption.
This command initializes the content of the global index catalog called sampleCatalog from the instance of Oracle Unified Directory proxy 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.
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ initialize-replication --catalogName sampleCatalog \ --adminUID adminUID --all
If replication is complete, the status for all instances of Oracle Unified Directory proxy 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 To View the Status of a Replicated Global Index Catalog Configuration.
$ gicadm -h localhost -D "cn=Directory Manager" -p 4444 -w password -X \ disable-replication --catalogName name --adminUID adminUID
The gicadm disable-replication command must be executed for each instance of Oracle Unified Directory proxy in the topology on which you want to disable replication.
$ gicadm -h hostname -p 4444 -w password -X \ status-replication --catalogName name --adminUID adminUID
If you do not declare a catalog name, status information for all replicated global index catalogs is displayed.
Replication logs are stored in the replication repair logs. Changes are recorded in the change logs. For information on accessing these logs, see 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 Configuring Logs With the Log Publisher.
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 To Create a Replicated Topology and Enable Global Index Catalog Replication.
Example 3-2 To Restart a Global Index Catalog in a Replicated Topology
In the example illustrated by Figure 3-1, three instances of Oracle Unified Directory proxy are running with a replicated global index catalog. If proxy instance 3 goes down or is stopped, for whatever reason, follow these steps to ensure that the three instances of the proxy are replicated.
Issue the start-ds command on proxy instance 3.
You can check to see if replication is complete by executing the gicadm status-replication command, as described in To View the Status of a Replicated Global Index Catalog Configuration.
Figure 3-1 Restarting a Global Index Catalog
Example 3-3 Adding a Global Index to a Replicated Global Index Catalog Topology
In the example illustrated by Figure 3-2, three instances of Oracle Unified Directory proxy are running with a replicated global index catalog. If you want to add an additional attribute, for example, mail, to the replicated global index catalog, follow these steps.
First, run the command gicadm add-index mail on each of the three proxy instances.
Export the directory data under the distribution route from one of the remote LDAP servers to an LDIF file named file1 by using export-ldif.
Run split-ldif to generate GIC content in the specified directory.
On proxy instance 1, execute the command gicadm import --importDirectory directory-name.
On proxy instance 1, execute the gicadm initialize-replication --all command. This command pushes the changes from proxy 1 to all the other proxies in the topology, and adds the new global index.
Figure 3-2 Adding a Global Index to a Replicated Global Index Catalog Topology
Example 3-4 Overwriting the Contents of Replicated Global Index Catalogs
In the example illustrated by Figure 3-3, three instances of Oracle Unified Directory proxy are running with a replicated global index catalog. To overwrite the content of the global index catalogs on proxy instances 2 and 3 with the content of the global index catalog on instance 1, follow these steps.
On proxy instance 1, execute the gicadm initialize-replication --all command. This replaces the content of the global index catalog on proxy instance 2 and 3 with the content of the global index catalog on proxy instance 1.
Figure 3-3 Overwriting the Contents of Replicated Global Index Catalogs
Example 3-5 Adding a Proxy to a Replicated Topology
In the example illustrated by Figure 3-4, three instances of Oracle Unified Directory proxy are running with a replicated global index catalog. To add a fourth instance of Oracle Unified Directory proxy with a replicated global index catalog, follow these steps on the new proxy instance.
On the new proxy instance 4, execute the gicadm create-catalog command.
Run the commandsgicadm add-index cn, gicadm add-index sn, and gicadm add-index mail.
Execute the gicadm associate command.
Run the following command:
gicadm enable-replication --localReplicationPort replication port of instance 4 --remoteHost name or IP address of host running instance 1
This command configures replication between instance 1 and instance 4.
Run the initialize replication --from proxy 1 command.
Figure 3-4 Adding a Proxy to a Replicated Topology
If you are using Oracle Unified Directory proxy with Oracle Unified Directory as an 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";)
-
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";)
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
|