22 Configuring Distribution Using the Proxy
Note:
In some cases, you can choose to configure distribution using dsconfig
or Oracle Unified Directory Services Manager (OUDSM).
-
For information about using the
dsconfig
command, see Managing the Server Configuration Using dsconfig. -
For information about using OUDSM, see Accessing Oracle Unified Directory Using OUDSM.
To forward client requests to remote LDAP servers using distribution, you must configure the following components 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.
Note:
To understand more about distribution, see Overview of Data Distribution Using the Proxy.
22.1 Configuring a Distribution Deployment Using the dsconfig
Command
You can configure distribution deployment using the dsconfig command and create a distribution workflow element, algorithm and partitions.
22.1.1 Configuring Distribution Using dsconfig Command
To configure distribution using the dsconfig
command, you must set up a distribution deployment.
For information about setting up a distribution deployment during setup, see "To Configure Simple Distribution" section in Installing 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 also use the -X
option to trust all certificates.
22.1.2 Creating a Distribution Workflow Element
To configure distribution, you must create a distribution workflow element using the dsconfig create-workflow-element
command.
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.
22.1.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 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
.
22.1.4 Creating Distribution Partitions
You can create a distribution partition using the dsconfig create-distribution-partition
.Before creating a distribution partition, distribution workflow element and distribution algorithm must already be created.
22.1.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 Creating 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 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.
22.1.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
.
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 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 Configuring a Distribution Deployment Using the dsconfig Command.
Note:
For a lexico distribution algorithm, the sort sequence that is used is ASCII.
22.1.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
.
22.1.4.4 About 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:
DN Pattern Quantifiers | Description |
---|---|
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 |
22.1.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.
22.1.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 Configuring Global Indexes 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
22.1.6 Configuring Criticality in Workflows Using dsconfig
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
22.1.7 Configuring Criticality in Workflow Elements Using dsconfig
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 back end 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
22.1.8 Deleting a Distribution Configuration
You can delete a distribution configuration by deleting the distribution workflow element.
To delete a complete distribution workflow (including 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.
22.2 Configuring a Distribution Deployment Using OUDSM
You can configure distribution by OUDSM when a proxy server is set up without configuring either load balancing or distribution. Criticality in workflow can be configured by using OUDSM.
The following topics describe how to configure distribution and criticality in workflow using OUDSM:
22.2.1 Configuring Distribution Using OUDSM
If you have set up a proxy server instance without configuring either load balancing or distribution, you can configure distribution by using OUDSM. Before you begin, it is useful to understand the components comprise a distribution deployment.
To configure distribution by using OUDSM:
When you have configured distribution, you can modify any aspect of the configuration on the OUDSM Configuration tab.
For more information, see Configuration 2: Simple Distribution.
22.2.2 Configuring Criticality in Workflows Using OUDSM
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 OUDSM. For information about configuring criticality using dsconfig
, Configuring Criticality in Workflows Using dsconfig.
To configure criticality in workflows using OUDSM: