22 Configuring Distribution Using the Proxy

You can choose to configure distribution using the proxy dsconfig or Oracle Unified Directory Services Manager (OUDSM).

• Configuring a Distribution Deployment Using the dsconfig Command

• Configuring a Distribution Deployment Using OUDSM

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.

• Configuring Distribution Using dsconfig Command

• Creating a Distribution Workflow Element

• Creating a Distribution Algorithm

• Creating Distribution Partitions

• Managing Modify DN Requests

• Configuring Criticality in Workflows Using dsconfig

• Configuring Criticality in Workflow Elements Using dsconfig

• Deleting a Distribution Configuration

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.

1. Create a distribution workflow element.

   See Creating a Distribution Workflow Element.

2. Create a distribution algorithm.

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

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

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.

• Creating a capacity Distribution Partition

• Creating a lexico or numeric Distribution Partition

• Creating a dnpattern Distribution Partition

• About DN Pattern String Syntax

• Using DN Pattern negative-match

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:

• Configuring Distribution Using OUDSM

• Configuring Criticality in Workflows 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:

1. Connect to the proxy server from OUDSM, as described in Connecting to the Server Using OUDSM.
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 Overview of 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 back-end LDAP server that will hold the partitioned data.

   OUDSM attempts to connect to these back-end 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 Understanding the 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 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:

1. Connect to the proxy server from OUDSM, as described in Connecting to the Server Using OUDSM.
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 22-1 Criticality Flag

   
   Description of "Figure 22-1 Criticality Flag"