14 Configuring the Server Instance

The easiest way to access the server configuration is by using the dsconfig command or, for certain aspects of the configuration, by using Oracle Directory Services Manager.

This chapter covers the following topics:

• Section 14.1, "Managing the Server Configuration With dsconfig"

• Section 14.2, "Managing the Server Configuration With Oracle Directory Services Manager"

• Section 14.3, "Managing Administration Traffic to the Server"

• Section 14.4, "Configuring Commands As Tasks"

• Section 14.5, "Deploying and Configuring the DSML Gateway"

14.1 Managing the Server Configuration With dsconfig

The topics in this section are intended for administrators or users who want to configure and manage a deployed Oracle Unified Directory instance. These topics provide an overview of the dsconfig command-line utility and its use in server configuration.

You can use the dsconfig command to configure both the Oracle Unified Directory directory server and the proxy server. For a list of the supported sub-commands for the directory server or proxy instance, and for specific information about this command, see Appendix A, "dsconfig."

You can also use dsconfig to configure a number of proxy-specific components. This section contains the following topics:

• Section 14.1.1, "Overview of the dsconfig Command"

• Section 14.1.2, "Using dsconfig in Interactive Mode"

• Section 14.1.3, "Getting Help With dsconfig"

• Section 14.1.4, "Configuring a Server Instance With dsconfig"

• Section 14.1.5, "Configuring Connection Handlers With dsconfig"

• Section 14.1.6, "Configuring Network Groups With dsconfig"

• Section 14.1.7, "Configuring Workflows With dsconfig"

• Section 14.1.8, "Configuring Workflow Elements With dsconfig"

• Section 14.1.9, "Configuring Plug-Ins With dsconfig"

• Section 14.1.10, "Configuring Suffixes with dsconfig."

14.1.1 Overview of the dsconfig Command

The dsconfig command provides a simple mechanism for accessing the server configuration. dsconfig presents the configuration as a set of components, each of which can be managed through one or more sub-commands.

dsconfig can also be used interactively. In interactive mode, dsconfig functions much like a wizard, walking you through the server configuration. For more information, see Section 14.1.2, "Using dsconfig in Interactive Mode."

dsconfig can only be used to configure a running server instance. Offline configuration is not supported by dsconfig.

Like the other administration commands, dsconfig uses the administration connector to access the server. For more information, see Section 14.3, "Managing Administration Traffic to the Server." All of the examples in this section assume that the administration connector is listening on the default port (4444) and that the command is accessing the server running on the local host. If this is not the case, the --port and --hostname options must be specified.

This section contains the following topics:

• Section 14.1.1.1, "dsconfig and Certificate Checking"

• Section 14.1.1.2, "dsconfig Sub-Commands"

• Section 14.1.1.3, "dsconfig Advanced Properties"

14.1.1.1 dsconfig and Certificate Checking

dsconfig accesses the server over a secured connection with certificate authentication. If you run dsconfig in interactive mode, you are prompted as to how you want to trust the certificate.

If you run dsconfig in non-interactive mode (that is, with the -n option), specification of the trust store parameters depends on whether you run the command locally or remotely.

• Running dsconfig locally. (The command is launched on the server that you are administering.) If you do not specify the trust store parameters, the server uses the local instance trust store by default. Unless you specify otherwise, the local instance trust is INSTANCE_DIR/OUD/config/admin-truststore.

• Running dsconfig remotely. (The command is launched on a different server to the one you are administering.) You must specify the trust store parameters or the -X (--trustAll) option. The easiest way to specify the trust store parameters is to run the command once in interactive mode and to save the certificate that is presented by the server in your trust store.

  $ dsconfig
  
  >>>> >>>> Specify Oracle Unified Directory LDAP connection parameters
  
  Directory server hostname or IP address [host1.example.com]:
  Directory server administration port number [4444]:
  Administrator user bind DN [cn=Directory Manager]:
  Password for user 'cn=Directory Manager':
  
  How do you want to trust the server certificate?
  
      1)  Automatically trust
      2)  Use a truststore
      3)  Manually validate
  
  Enter choice [3]: 3
  
  Administrator user bind DN [cn=Directory Manager]:
  
  Password for user 'cn=Directory Manager':
  
  Server Certificate:
  
  User DN  : CN=host1.example.com, O=Administration Connector Self-Signed Certificate
  Validity : From 'Wed Apr 29 11:13:21 MEST 2009'
               To 'Fri Apr 29 11:13:21 MEST 2011'
  Issuer   : CN=host1.example.com, O=Administration Connector Self-Signed Certificate
  
  Do you trust this server certificate?
  
      1)  No
      2)  Yes, for this session only
      3)  Yes, also add it to a truststore
      4)  View certificate details
  
  Enter choice [2]: 3
  
  Truststore path: /local/instances/certificates/jctruststore
  
  Password for keystore '/local/instances/certificates/jctruststore':
  
  ...
  

  When you have saved the certificate in the trust store, you can specify those trust store parameters in non-interactive mode.

  $ dsconfig -h localhost -p 4444 list-connection-handlers -n \
  --trustStorePath /local/instances/certificates/jctruststore \
  --trustStorePasswordFile /local/instances/certificates/jctruststore.pin -j pwd-file
  Connection Handler       : Type : enabled : listen-port : use-ssl
  -------------------------:------:---------:-------------:--------
  JMX Connection Handler   : jmx  : false   : 1689        : false
  LDAP Connection Handler  : ldap : true    : 1389        : false
  LDAPS Connection Handler : ldap : false   : 636         : true
  LDIF Connection Handler  : ldif : false   : -  
  

14.1.1.2 dsconfig Sub-Commands

dsconfig provides an intuitive list of sub-commands to manage various elements of the configuration.

You can use these sub-commands to add, delete, list, view, and modify different components:

Subcommand	Function
dsconfig create-component options	Creates a new component
dsconfig delete-component options	Deletes an existing component
dsconfig get-component-prop options	Displays the properties of a component
dsconfig list-components options	Lists the existing defined components
dsconfig set-component-prop options	Modifies the properties of a component

For example, the following five sub-commands are used to manage connection handlers:

Subcommand	Function
dsconfig create-connection-handler options	Creates connection handlers
dsconfig delete-connection-handler options	Deletes connection handlers
dsconfig get-connection-handler-prop options	Displays the properties of a connection handler
dsconfig list-connection-handlers options	Lists the existing defined connection handlers
dsconfig set-connection-handler-prop options	Modifies the properties of a connection handler

Not all types of components can be created and deleted. For example, a directory server has only a single global configuration. For this reason, the global configuration is managed with only two sub-commands:

Subcommand	Function
dsconfig get-global-configuration-prop options	Displays the global configuration properties
dsconfig set-global-configuration-prop options	Modifies the global configuration properties

The configurable properties of all components can be queried and modified to change the behavior of the component. For example, an LDAP connection has properties that determine its IP listener address, its port, and its SSL configuration.

14.1.1.3 dsconfig Advanced Properties

There are a number of component properties that are considered advanced properties. The advanced properties are not displayed by default, and have default values that apply in most cases. If you want to modify the values or the advanced properties, use --advanced before the subcommand. For example:

$ dsconfig --advanced get-extension-prop

14.1.2 Using dsconfig in Interactive Mode

Unless you specify all configuration parameters and the -n (--no-prompt) option, dsconfig runs in interactive mode. Interactive mode functions like a wizard, walking you through the server configuration. Interactive mode is a good approach to start using dsconfig.

When you run dsconfig in interactive mode, you can specify that you want the equivalent command (including all your selections) to be displayed, or to be written to a file. The following example shows how to use the --displayCommand option to display the equivalent non-interactive command when configuring the trust manager. Note that the equivalent command is displayed at the point at which the command has been applied and validated by the directory server.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file --displayCommand
...
The TrustStore Manager Provider was modified successfully

The equivalent non-interactive command-line is:
dsconfig --hostname "localhost" --port "4444" --bindDN "cn=directory
manager" --bindPasswordFile pwd-file --trustAll
set-trust-manager-provider-prop --provider-name "PKCS12" --set
"enabled:true"

To copy the equivalent command to a file, use the --commandFilePath option, as shown in the following example:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file --commandFilePath /tmp/filename

14.1.3 Getting Help With dsconfig

The dsconfig command has extensive online help that is accessed using the --help option. This section provides an overview, and contains the following topics:

• Section 14.1.3.1, "Global Usage"

• Section 14.1.3.2, "Finding the Correct Subcommand"

• Section 14.1.3.3, "Getting Help for an Individual Subcommand"

• Section 14.1.3.4, "Displaying a Summary of a Component's Properties"

• Section 14.1.3.5, "Displaying Detailed Help on a Property"

14.1.3.1 Global Usage

Use the following command to display dsconfig's global usage:

$ dsconfig --help

14.1.3.2 Finding the Correct Subcommand

The global usage information does not include the list of available sub-commands. To retrieve the list of sub-commands, use one of the --help-xxx options, where xxx determines the group of sub-commands to be displayed.

Note:

Use the --help-all option used to display all of the available sub-commands.

For example, to find all the sub-commands relating to distribution, use the following command:

$ dsconfig --help-distribution

14.1.3.3 Getting Help for an Individual Subcommand

When you have determined which subcommand you want, you can get more detailed help on that subcommand by using the subcommand --help option as follows:

$ dsconfig create-monitor-provider --help

14.1.3.4 Displaying a Summary of a Component's Properties

The dsconfig command has built-in documentation for all of the components and their properties. This documentation can be accessed by using the list-properties subcommand. For example, a summary of the properties associated with a work queue can be displayed by using the following command:

$ dsconfig list-properties -c work-queue

If the -c option is not specified, a summary of the properties for all components is displayed.

14.1.3.5 Displaying Detailed Help on a Property

The summary table displays only brief usage information for each property. More detailed information are available using the verbose mode of the list-properties subcommand:

$ dsconfig list-properties -c work-queue --property num-worker-threads -v

If the --property option is not specified, verbose help is provided for all the work-queue properties.

14.1.4 Configuring a Server Instance With dsconfig

The dsconfig command is the recommended utility for accessing the server configuration. Accessing the configuration directly over LDAP, using the ldap* utilities is discouraged. This section describes the utility to access the server components and contains the following topics:

• Section 14.1.4.1, "To Display the Properties of a Component"

• Section 14.1.4.2, "To List Components"

• Section 14.1.4.3, "To Create a Component"

• Section 14.1.4.4, "To Modify the Properties of a Component"

• Section 14.1.4.5, "To Modify the Values of a Multi-Valued Property"

• Section 14.1.4.6, "To Delete a Component"

• Section 14.1.4.7, "To Use dsconfig in Batch Mode"

14.1.4.1 To Display the Properties of a Component

Each component has one or more properties that can be displayed by using the component's get-xxx-prop subcommand. Each component is associated with a single LDAP entry in the server configuration, and each property is associated with a single LDAP attribute.

To display the properties of the default LDAP connection handler, run the following command:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  get-connection-handler-prop --handler-name "LDAP Connection Handler"

Property : Value(s)
------------------------:-------------------------------------------------------
allow-ldap-v2 : true
allow-start-tls : false
allowed-client : -
denied-client : -
enabled : true
keep-stats : true
key-manager-provider : -
listen-address : 0.0.0.0
listen-port : 1389
ssl-cert-nickname : server-cert
ssl-cipher-suite : -
ssl-client-auth-policy : optional
ssl-protocol : -
trust-manager-provider : -
use-ssl : false

The dsconfig command displays the default values or behavior for properties that have not been customized.

14.1.4.2 To List Components

You can view a list and summary of the instances of one component by using the component's list-xxxs subcommand. This can be particularly useful if you have more than one instance of the same component.

For example, to list the configured connection handlers, run this command:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  list-connection-handlers

Depending on your installation, the output will be similar to the following.

Connection Handler       : Type : enabled : listen-port : use-ssl-------------------------:------:---------:-------------:--------JMX Connection Handler   : jmx  : false   : 1689        : falseLDAP Connection Handler  : ldap : true    : 1389        : falseLDAPS Connection Handler : ldap : false   : 636         : trueLDIF Connection Handler  : ldif : false   : -           : -SNMP Connection Handler  : snmp : false   : 161         : -

14.1.4.3 To Create a Component

New instances of a component can be created by using the component's create-xxx subcommand. Often there are several subtypes of the component. For example, there are four types of connection handler: LDAP, LDIF, JMX, and SNMP. Because all of these are created by using the same subcommand, you must specify the type of component that you want to create. Do this by using the subcommand -t or --type.

When you create a new component, you must specify the component's mandatory properties. The mandatory properties depend on the type of component that is being created. For example, an LDAP connection handler might have different mandatory properties to a JMX connection handler. If a mandatory property is left undefined, dsconfig enters interactive mode and prompts you for the undefined properties. If you include the -n (non-interactive) option, dsconfig fails to create the component and displays an error message indicating which properties need to be defined.

1. Display the types of connection handler that can be created by accessing the help for the connection handler component.

   $ dsconfig create-connection-handler --help
   
   Usage: dsconfig create-connection-handler {options}
   Creates Connection Handlers
   
   Global Options:
   See "dsconfig --help"
   
   SubCommand Options:
   --handler-name {NAME}
   The name of the new Connection Handler
   --set {PROP:VALUE}
   Assigns a value to a property where PROP is the name of the property and
   VAL is the single value to be assigned. Specify the same property multiple
   times in order to assign more than one value to it
   -t, --type {TYPE}
   The type of Connection Handler which should be created. The value for TYPE
   can be one of: custom | jmx | ldap | ldif | snmp
   

2. Create a new LDAP connection handler, specifying values for the mandatory enabled and the listen-port properties.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
     create-connection-handler -t ldap --handler-name "My LDAP Connection Handler"
   

   An error message similar to the following will be displayed.

   The LDAP Connection Handler could not be created because the following
   mandatory properties were not defined:
   
   Property     Syntax
   ----------------------------------
   enabled      false | true
   listen-port  1 <= INTEGER <= 65535
   

14.1.4.4 To Modify the Properties of a Component

The properties of a component can be modified by using the component's set-xxx-prop subcommand. Multiple properties can be modified at the same time by using multiple occurrences of the --set option. The following example uses the set-connection-handler-prop subcommand to modify the properties of a connection handler.

Note:

Many components have a Java class property that specifies the name of a Java class to be used as the implementation of the component. Do not modify this property, as doing so could prevent your server from operating correctly. These properties are treated as advanced properties and hidden from view unless you run dsconfig with the --advanced option.

For example, to configure the LDAP connection handler to accept LDAPv2 connections, run this command:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-connection-handler-prop --handler-name="LDAP Connection Handler" \
  --set allow-ldap-v2:true

14.1.4.5 To Modify the Values of a Multi-Valued Property

You can set multiple values for a property by using the --add option multiple times in the same dsconfig command.

This example sets multiple values for the allowed-client property.

To restrict connections through the LDAP connection handler to specific clients, run these commands:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  set-connection-handler-prop --handler-name "LDAP Connection Handler" \
  --add allowed-client:myhost --add allowed-client:myhost.example \
  --add allowed-client:myhost.example.com

14.1.4.6 To Delete a Component

Existing instances of a component can be removed using the dsconfig delete-xxx subcommand

The following example deletes the LDAP connection handler that was created in the previous example:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  delete-connection-handler --handler-name "My LDAP Connection Handler"

14.1.4.7 To Use dsconfig in Batch Mode

The -F or --batchFilePath option of the dsconfig command enables you to specify a number of operations that are completed in a single command by consolidating those operations in a file. This can significantly improve performance when several dsconfig commands are required.

To use dsconfig in batch mode, complete the following steps:

1. Create a script that contains the required commands for creating a new backend that is used to store a new suffix.

   For example, the following file (named new-backend.txt) achieves three separate tasks:

   • creates the db-local-backend workflow element

   • adds a set of index entry limit for the uniquemember attribute (for example, how to set properties, but this step is not mandatory)

   • creates the workflow for the new suffix

   • registers the new suffix in the default network group

   create-workflow-element --element-name myBackend --type db-local-backend \
   --set enabled:true --set base-dn:cn=myexample,cn=com 
   set-local-db-index-prop --element-name myBackend --index-name uniqueMember \
   --set index-entry-limit:5000
   create-workflow --workflow-name myWorkflow --set base-dn:cn=myexample,cn=com \
   --set enabled:true --set workflow-element:myBackend
   set-network-group-prop --group-name network-group --add workflow:myWorkflow
   

2. Run the dsconfig command with that file as a parameter.

   $ dsconfig -h localhost -p 4444 -D cn="directory manager" -j pwd-file \
     -F new-backend.txt -X -n
   

14.1.5 Configuring Connection Handlers With dsconfig

Connection handlers are responsible for handling all interaction with client applications, including accepting connections, reading requests, and sending responses.

For information about configuring secure connections, see Section 20.5, "Configuring SSL and StartTLS for LDAP and JMX."

The section describes how to configure the connection handlers by using the dsconfig command, and contains the following topics:

• Section 14.1.5.1, "To Display All Connection Handlers"

• Section 14.1.5.2, "Configuring the LDAP Connection Handler"

• Section 14.1.5.3, "Configuring the LDIF Connection Handler"

• Section 14.1.5.4, "Configuring the JMX Connection Handler"

These sections provide examples on only a few aspects of the configuration. For details about all the configuration properties, use the following command:

$ dsconfig list-properties -c connection-handler

14.1.5.1 To Display All Connection Handlers

Oracle Unified Directory supports the following types of connection handler:

• LDAP connection handler. This connection handler is used to interact with clients using LDAP. It provides full support for LDAPv3 and limited support for LDAPv2.

• LDAPS connection handler. This connection handler is used to interact with clients using LDAP over SSL.

• LDIF connection handler. This connection handler is used to process changes in the server using internal operations.

• JMX connection handler. This connection handler allows interactions with clients using the Java Management Extensions (JMX) framework and the Remote Method Invocation (RMI) protocol.

• SNMP. This connection handler is used to process SNMP requests to retrieve monitoring information described by MIB 2605. The supported SNMP protocols are SNMP V1, V2c and V3.

To display all configured connection handlers, along with their basic properties, use the dsconfig list-connection-handlers command.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  list-connection-handlers

Connection Handler       : Type : enabled : listen-port : use-ssl
-------------------------:------:---------:-------------:--------
JMX Connection Handler   : jmx  : false   : 1689        : falseLDAP Connection Handler  : ldap : true    : 1389        : falseLDAPS Connection Handler : ldap : false   : 636         : trueLDIF Connection Handler  : ldif : false   : -           : -SNMP Connection Handler  : snmp : false   : 161         : -

14.1.5.2 Configuring the LDAP Connection Handler

The following command displays the properties of the LDAP connection handler:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  get-connection-handler-prop --handler-name "LDAP Connection Handler"

Depending on your configuration, the output will be similar to the following.

Property               : Value(s)
-----------------------:------------
allow-ldap-v2          : true
allow-start-tls        : false
allowed-client         : -
denied-client          : -
enabled                : true
keep-stats             : true
key-manager-provider   : -
listen-address         : 0.0.0.0
listen-port            : 1389
ssl-cert-nickname      : server-cert
ssl-cipher-suite       : -
ssl-client-auth-policy : optional
ssl-protocol           : -
trust-manager-provider : -
use-ssl                : false

14.1.5.2.1 To Control Which Clients Have LDAP Access to the Directory Server

You can specify a list of clients that may or may not access the directory server over LDAP. To do this, set the allowed-client or denied-client property of the LDAP connection handler. These properties take an IP address or subnetwork with subnetwork mask as values.

By default, these properties are not set and all clients are allowed access. Changes to these properties take effect immediately but do not interfere with connections that are already established.

This example permits access only to clients in the subnet mask 255.255.255.10.

Run the dsconfig command as follows:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-connection-handler-prop --handler-name "LDAP Connection Handler" \
  --set allowed-client:255.255.255.10

14.1.5.3 Configuring the LDIF Connection Handler

The LDIF connection handler is disabled by default. This connection handler can be used to process changes in the server using internal operations. The changes to be processed are read from an LDIF file.

The following command displays the default properties of the LDIF connection handler:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  get-connection-handler-prop --handler-name "LDIF Connection Handler"

Depending on your installation, the output will be similar to the following.

Property       : Value(s)
---------------:-------------------------
allowed-client : -
denied-client  : -
enabled        : false 
ldif-directory : config/auto-process-ldif
poll-interval  : 5 s

The ldif-directory property specifies the directory in which the LDIF files are located. The connection handler checks if there are any files in this directory, at an interval specified by the poll-interval property. The connection handler then processes the changes contained in those files as internal operations and writes the result to an output file with comments indicating the result of the processing.

14.1.5.3.1 To Enable the JMX Alert Handler Through the LDIF Connection Handler

This example demonstrates how to enable the JMX alert handler through the LDIF connection handler.

1. Check the status of the JMX alert handler (disabled by default).

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
     get-alert-handler-prop --handler-name "JMX Alert Handler"
   

   Depending on your installation, the output will be similar to the following.

   Property            : Value(s) 
   --------------------:--------- 
   disabled-alert-type : - 
   enabled             : false 
   enabled-alert-type  : -
   

2. Create an LDIF file in the default LDIF directory that enables the JMX alert handler.

   $ cd ../config/ 
   $ mkdir auto-process-ldif 
   $ cd auto-process-ldif/ 
   $ cat > disable-jmx.ldif << EOM 
   > dn: cn=JMX Alert Handler,cn=Alert Handlers,cn=config 
   > changetype: modify 
   > replace: ds-cfg-enabled 
   > ds-cfg-enabled: true 
   > EOM 
   $
   

3. After a period of time longer than poll-interval, recheck the status of the JMX alert handler.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
     get-alert-handler-prop --handler-name "JMX Alert Handler"
   
   Property            : Value(s) 
   --------------------:--------- 
   disabled-alert-type : - 
   enabled             : true 
   enabled-alert-type  : -
   

14.1.5.4 Configuring the JMX Connection Handler

The following command displays the default properties of the JMX connection handler:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  get-connection-handler-prop --handler-name "JMX Connection Handler"

Depending on your installation, the output will be similar to the following.

Property             : Value(s)
---------------------:------------
allowed-client       : -
denied-client        : -
enabled              : false
key-manager-provider : -
listen-port          : 1689
ssl-cert-nickname    : server-cert
use-ssl              : false

14.1.5.4.1 To Change the Port on Which the Server Listens for JMX Connections

This example changes the port on which the server listens for JMX connections to 1789.

Use the dsconfig command as follows:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  set-connection-handler-prop \
  --handler-name "JMX Connection Handler" --set listen-port:1789

14.1.6 Configuring Network Groups With dsconfig

Network groups are the single entry point of all client requests to the Oracle Unified Directory. The network group handles all client interactions, dispatching them and delegating the treatment of the request to workflows. A client connection is associated to the network group with the highest priority and for which all the criteria are met. During installation, a default network group with a priority of 1 is created. To set request filtering policies or resource limits, you must create a network group quality of service policy.

Each network group is associated with one or more workflows. The workflows provide access to a naming context (or suffix). By associating a workflow with a network group, you indicate to the network group which naming contexts are available. Typically to create a network group, you would already have a workflow created. For information about workflows, see Section 14.1.7, "Configuring Workflows With dsconfig."

This section describes how to configure network groups using the dsconfig command, and covers the following topics:

• Section 14.1.6.1, "Creating a Network Group"

• Section 14.1.6.2, "Modifying Network Group Properties"

• Section 14.1.6.3, "Creating a Network Group Quality of Service Policy"

• Section 14.1.6.4, "Modifying a Network Group Quality of Service Policy"

• Section 14.1.6.5, "Relocating the Root DSE Entry for a Network Group"

All the commands in the following procedures specify the hostname (-h), the admin port (-p), the bind DN (-D), and the bind password file (-j). The examples use the -X option to trust all certificates.

14.1.6.1 Creating a Network Group

You can create many network groups, in which case client requests will be handled by the network group with the highest priority, for which the criteria are met. Therefore, when you create a network group, you must consider all the network groups you plan to create, and the priority of each. The priority can be 0 or above, where 0 is the highest priority.

It is possible to create two network groups with the same priority. However, if two or more network groups have the same priority and match the client request, the network group that will handle the request is random, among those matching the client request. You should therefore specify a different priority for each network group.

The default properties of a new network group are as follows.

Property                 Value(s)
----------------------------------------------------------------------
allowed-auth-method      All authorization methods are allowed.
allowed-bind-dn          All bind DNs are allowed.
allowed-bind-id          All bind IDs are allowed.
allowed-client           All clients with addresses that do not match
                         an address on the deny list are allowed. If
                         there is no deny list, then all clients are
                         allowed.
allowed-protocol         All supported protocols are allowed.
certificate-mapper       The global certificate mapper will be used.
denied-client            If an allow list is specified, then only
                         clients with addresses on the allow list are
                         allowed. Otherwise, all clients are allowed.
enabled                  true
generic-identity-mapper  The global generic identity mapper will be
                         used.
gssapi-identity-mapper   The global GSSAPI identity mapper will be
                         used.
is-security-mandatory    false
priority                 1
workflow                 userroot0

To create a network group, use the dsconfig create-network-group command, as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  create-network-group --group-name network-group1 --set enabled:true\
  --set workflow:workflow1 --set priority:1

After you have created a network group, you can associate a network group quality of service policy to it. For information about creating a quality of service policy, see Section 14.1.6.3, "Creating a Network Group Quality of Service Policy."

14.1.6.2 Modifying Network Group Properties

The network group properties filter the traffic and indicate how a request is directed.

You can modify network group properties, by using the dsconfig set-network-group-prop command. For example, to modify the priority of the network group:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-network-group-prop --group-name network-group1 --set priority:3

You can configure the network group properties to set the following criteria:

• the authentication method allowed between the client and the network group (allowed-auth-method).

• the bind DN allowed to connect to the network group (allowed-bind-dn).

• the list of clients authorized to access the Oracle Unified Directory (allowed-client), expressed by the IP address or name of the client. If no allowed client list is provided, all clients are allowed, assuming they are not listed in the denied client list.

• the protocol allowed to connect to the Oracle Unified Directory (allowed-protocol). If none is specified, all protocols are allowed.

• the name of the certificate mapper that should be used to match client certificates to user entries (certificate-mapper). If none is specified, the global certificate mapper is used.

• the list of clients not authorized to access the Oracle Unified Directory (denied-client). If no denied client list is provided, all clients are authorized, assuming there is no limitation set by an allowed client list.

• the set of identity mappers that will be used by the network group to map an identity while performing SIMPLE, non-GSSAPI SASL bind requests and proxy authorization controls (generic-identity-mapper).

• the set of identity mappers that will be used by the network group to map an identity while performing GSSAPI/SASL bind requests (gssapi-identity-mapper).

• whether security between the client and the Oracle Unified Directory is always required (is-security-mandatory).

• the priority of the network group (priority). A client connection is first compared against the network group with the highest priority. If the client connection does not match its connection criteria, the client connection is compared against the network group with the next highest priority, and so on. If no network group is selected, the client connection is rejected.

For example, you can ensure that no connections are accepted from the IP address 208.77.188.166, by network-group1 as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-network-group-prop --group-name network-group1 \
  --set denied-client:208.77.188.166 

14.1.6.2.1 Setting an Allowed or Denied Client List

For allowed-client and denied-client lists, you must be aware of the name service configuration on the server. For example, if the name service knows the host as myclienthost.example.com, you must specify myclienthost.example.com as the value, and not just myclienthost. Similarly, if the name service knows the host as myclienthost, you must specify the value as myclienthost. If you do not know how the name service is configured, you should specify both the fully qualified domain name (for example myclienthost.sun.com) and the short name (myclienthost) of the machine. Specifying multiple values will ensure that the name is resolved correctly. For example:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-network-group-prop \
  --group-name network-group1 \
  --add denied-client:myhost \
  --add denied-client:myhost.example \
  --add denied-client:myhost.example.com

To avoid any issues, use the IP address for clarity.

If you use localhost or the name of the local machine when connecting to Oracle Unified Directory, the IP addresses of the client will be different. To prevent connections from the localhost, specify both localhost and the name of the local machine in the list of denied clients.

14.1.6.3 Creating a Network Group Quality of Service Policy

You can, optionally, associate a quality of service (QoS) policy with a network group. A QoS policy applies additional filtering criteria to client connections to determine how the network group handles the request.

Oracle Unified Directory supports four types of QoS policy:

• request filtering policy

• resource limits

• affinity

• referral

Note:

ODSM accesses an Oracle Unified Directory instance over the administration connector. The administration connector is not subject to the QoS policies defined for a network group. ODSM therefore bypasses the QoS policies defined for a network group. For more information, see Section 14.3, "Managing Administration Traffic to the Server".

To create a network group quality of service policy, use the dsconfig create-network-group-qos-policy command. You must specify the name of the network group to which the quality of service policy applies, and the type of quality of service policy.

14.1.6.3.1 Creating a Request Filtering Quality of Service Policy

A request filtering policy applies the following criteria to an incoming client request:

• allowed-attributes: list of attributes that can be specified in the filter of a search request

• allowed-operations: type of operation accepted by the network group. For example, you can specify that a network group should accept only read requests.

• allowed-search-scopes: scope of a search accepted, for example one-level only.

• allowed-subtrees: list of specific subtrees that can be specified as a base DN in a search request

• prohibited-attributes: list of attributes which, if specified in the filter of a search request, will be rejected

• prohibited-subtrees: list of specific subtrees that, if specified as base DNs in a search request, may not be specified will not manage a request

The following example defines a request filtering policy that ensures that users can only search and not modify data:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  create-network-group-qos-policy --group-name network-group1 \
  --type request-filtering --set allowed-operations:search 

14.1.6.3.2 Creating a Resource Limit Quality of Service Policy

A resource limit policy sets specific limits on the client connections that can access the server via that network group. The following limits can be defined:

• max-concurrent-ops-per-connection: the maximum number of simultaneous operations per established connection. To run the server in synchronous mode, set the maximum to 1.

• max-ops-per-connection: the maximum number of operations per connection.

• max-connections: the maximum number of concurrent client connections to the server. If you do not set a maximum number of connections, the server limit is used.

• max-connections-from-same-ip: the maximum number of connections from the same IP address. Set this parameter if you want to avoid Denial of Service attacks. This parameter should not be set if you know that most requests typically come from the same client.

• max-ops-per-interval: the maximum number of operations per specified interval. For example, a setting of 1,000 will limit the number of operations to 1,000 per the interval set using max-ops-interval.

• max-ops-interval: the interval during which the number of operations is counted for the max-ops-per-interval parameter. For example, an interval set to one second results in operations being counted per second. The limit (max-ops-per-interval) is checked and enforced during each interval.

• min-substring-length: the minimum search string length. The shorter the search string, the more results that need to be found and displayed. It is therefore useful to set a minimum search string length in the substring search filter to limit the resources that are used.

• size-limit: the maximum number of entries that can be returned to the client during a single search operation. It is recommended that you keep the default setting for this property.

• time-limit: the maximum length of time that should be spent processing a search operation. It is recommended that you keep the default setting for this property.

The following example defines a resource limit policy that ensures that a user enters a search string of at least five characters, to limit the number of return values:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  create-network-group-qos-policy --group-name network-group1 \
  --type resource-limits --set min-substring-length:5 

14.1.6.3.3 Creating an Affinity Quality of Service Policy

In a load balancing deployment, you can use affinity to override the regular routing process. The properties of the affinity policy determine the routing process that should be followed.

The following properties can be configured:

• affinity-policy: specifies the routing policy that should be used.

  The affinity policy can take one of the following values:

  • all-requests-after-first-request

  • all-requests-after-first-write-request

  • all-write-requests-after-first-write-request

  • first-read-request-after-write-request

  Specific operations will set affinity, depending on the affinity policy. For the first policy in the previous list (all-requests-after-first-request) all operations will set affinity. For the remaining policies (all-requests-after-first-write-request, all-write-requests-after-first-write-request, and first-read-request-after-write-request) only an ADD, DELETE, MOD or MODDN operation will set affinity.

• affinity-timeout defines the duration during which the affinity applies.

Even when affinity has been set by a previous operation, the load balancing algorithm is only bypassed in specific situations, depending on the affinity policy and the current operation type. If the affinity policy is all-requests-after-first-request or all-requests-after-first-write-request, the affinity route will be used for every operation type, unless the affinity timeout has expired. If the affinity policy is all-write-requests-after-first-write, the affinity route will be used for any ADD, DELETE, MOD or MODDN operation, unless the timeout has expired. The affinity route will not be used for other operations. If the affinity policy is first-read-request-after-write-request, the affinity route will be used for all operations except ADD, DELETE, MOD or MODDN operations, unless the timeout has expired.

The following example sets an affinity policy that can be set by any operation and used for all operations, for a maximum of sixty seconds.

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  create-network-group-qos-policy --group-name network-group1 \
  --type affinity --set affinity-timeout:60s \
  --set affinity-policy:all-requests-after-first-request

Note:

The affinity feature can be used with all load balancing algorithms except for the failover algorithm. With the failover algorithm, only one route is active at a time. The active route changes when the remote server goes down, so all connections to the remote server are broken. Affinity can therefore not apply in a failover scenario.

14.1.6.3.4 Creating a Referral Quality of Service Policy

You can configure the behavior of a proxy server when a referral is received from the remote LDAP server by defining a referral quality of service policy. The referral itself must be defined on the remote LDAP server.

When you create a network group quality of service, you can set the following referral properties:

• the maximum number of hops supported (referral-hop-limit) when the referral policy is set to follow. The default is set to 5.

• define the type of referral policy (referral-policy), such as discard, forward, or follow. This defines how a referral will be treated by the network group.

For example, the referral-policy is set by default to forward. You can change it to discard or to follow, as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  create-network-group-qos-policy --group-name network-group1 \
  --type referral --set referral-policy:follow 

14.1.6.4 Modifying a Network Group Quality of Service Policy

To modify a QoS policy, use the dsconfig set-network-group-qos-policy-prop command, specifying the network group name and the policy type.

The following example sets the minimum search string limit of a resource limits quality of service policy.

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-network-group-qos-policy-prop --group-name network-group1 \
  --policy-type resource-limits --set min-substring-length:5

14.1.6.5 Relocating the Root DSE Entry for a Network Group

The Root DSE is a special entry that provides information about the server's name, version, naming contexts, and supported features. The Root DSE entry of a network group can be in a local server or a remote server.

To relocate the Root DSE, use the dsconfig set-network-group-prop command, as shown in the following example:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-network-group-prop --group-name network-group1 \
  --set relocated-rootdse-workflow-element:<new rootDSE workflow element>  \

The value of the relocated-rootdse-workflow-element property is the workflow element where a Root DSE can be found (This is the entry returned by a search on the null DN).

14.1.7 Configuring Workflows With dsconfig

A workflow is the link between the network group and the naming context (suffixes). It defines the naming context that will be accessible for a given network group, when handling a request to a load balancing or distribution configuration. To create a workflow, you must already have a load balancing or distribution workflow element created. For information on workflow elements, see Section 14.1.8, "Configuring Workflow Elements With dsconfig."

The proxy automatically creates a number of private workflows. These workflows should not be modified or deleted. Privacy settings of the remote LDAP servers must be considered when configuring workflows. Privacy settings are as follows:

LDIFBackend

Privacy defined by the property ds-cfg-is-private-backend. This flag is set by default to private, but can be changed.

JEB backend

Always public, and contains user data.

Config File Handler backend

Always private

Backup backend

Always private

Schema backend

Always private

Tasks backend

Always private

Monitor backend

Always private

Truststore backend

Always private

This section describes examples to configure workflows using the dsconfig command, and contains the following topics:

• Section 14.1.7.1, "Listing Existing Workflows"

• Section 14.1.7.2, "Viewing Workflow Properties"

• Section 14.1.7.3, "Creating a Workflow"

All the commands in the following procedures specify the proxy hostname (-h), the proxy admin port (-p), the bind DN (-D), and the bind password file (-j). The examples use the -X option to trust all certificates.

14.1.7.1 Listing Existing Workflows

To display all the workflows configured on a server instance, use the dsconfig list-workflows command. The following example shows the default workflow configured on a proxy server instance:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  list-workflows

Workflow       : Type    : enabled
---------------:---------:--------
workflow1      : generic : true

14.1.7.2 Viewing Workflow Properties

To view the properties of a specific workflow, use the dsconfig get-workflow-prop command. For example:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  get-workflow-prop --workflow-name workflow1

Property         : Value(s)
-----------------:-------------------
base-dn          : "ou=people,o=test"
enabled          : true
workflow-element : load-bal-we1

The base-dn indicates the base DN used for the workflow, and therefore for the deployment using that workflow. The workflow-element property indicates the workflow element that will process the requests.

Note:

The base-dn property is read-only and cannot be modified.

14.1.7.3 Creating a Workflow

Each workflow is associated with a workflow element. When you create a workflow, you must specify the associated workflow element name (--set workflow-element). In other words, you must already have created the workflow element. See Section 14.1.8, "Configuring Workflow Elements With dsconfig."

To create a workflow, use the dsconfig create-workflow command. For example:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  create-workflow \
  --workflow-name workflow1 \
  --set base-dn:ou=people,o=test \
  --set enabled:true \
  --set workflow-element:load-bal-we1

14.1.8 Configuring Workflow Elements With dsconfig

Workflow elements are part of a routing structure, and are linked to workflows. In the case of a directory server instance, DB local workflow elements are associated with a physical database.

For information about all the types of workflow elements that can be configured, and what they are used for, see Section 4.1.3, "Workflow Elements".

A proxy deployment must include LDAP proxy workflow elements and either a load balancing or distribution workflow element.

This section describes how to configure workflow elements by using the dsconfig command, and covers the following topics:

• Section 14.1.8.1, "Listing Workflow Elements"

• Section 14.1.8.2, "Creating Workflow Elements"

• Section 14.1.8.3, "Modifying Workflow Elements"

All the commands in the following procedures specify the hostname (-h), the administration port (-p), the bind DN (-D), and the bind password file (-j). The examples use the -X option to trust all certificates.

14.1.8.1 Listing Workflow Elements

To display all the configured workflow elements, use the dsconfig list-workflow-elements command.

The following example shows the default workflow elements for a directory server instance.

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  list-workflow-elements

Workflow Element : Type               : enabled
-----------------:--------------------:--------
adminRoot        : ldif-local-backend : true
userRoot         : db-local-backend   : true
virtualAcis      : db-local-backend   : true

The following example shows the default workflow elements for a proxy server instance, deployed for load balancing:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  list-workflow-elements

Workflow Element : Type               : enabled
-----------------:--------------------:--------
adminRoot        : ldif-local-backend : true
load-bal-we1     : load-balancing     : true
proxy-we1        : proxy-ldap         : true
proxy-we2        : proxy-ldap         : true

14.1.8.2 Creating Workflow Elements

To create workflow elements in interactive mode, use the dsconfig create-workflow-element command. If you configured a proxy instance during the setup, the required workflow elements will already have been created.

You can create the following types of workflow elements:

• DB Local Backend. For more information, see Section 14.1.8.2.1, "To Create a DB Local Backend Workflow Element.".

• Proxy LDAP. For more information, see Section 15.1.1.3.3, "To Create a Proxy LDAP Workflow Element."

• Load balancing. For more information, see Section 15.1.3.2, "Creating a Load Balancing Workflow Element."

• Distribution. For more information, see Section 15.1.4.2, "Creating a Distribution Workflow Element."

• DN renaming. For more information, see Section 15.1.5, "Configuring DN Renaming With dsconfig."

• Kerberos Authentication. For more information, see Section 20.8.4, "Creating a Kerberos Workflow Element Using dsconfig"

14.1.8.2.1 To Create a DB Local Backend Workflow Element

A local backend workflow element provides access to a backend in a directory server instance. To create a new local backend workflow element, use the dsconfig create-workflow-element command, specifying one or more base DNs that will be accessed through the workflow element.

A single backend can be responsible for one or more base DNs. No two backends may have the same base DN, but one backend can have a base DN that is below a base DN provided by another backend. If any of the base DNs is subordinate to a base DN for another backend, then all base DNs for that backend must be subordinate to that same base DN.

The following example creates and enables a local backend workflow element to access the base DN ou=admins,dc=example,dc=com.

$ dsconfig create-workflow-element -h localhost -p 4444 -D "cn=directory manager"\
  -j pwd-file -X -n --element-name admins --type db-local-backend \
  --set base-dn:ou=admins,dc=example,dc=com --set enabled:true

14.1.8.3 Modifying Workflow Elements

Once you have created a workflow element, you can modify its properties using the dsconfig set-workflow-element-prop command.

14.1.9 Configuring Plug-Ins With dsconfig

Plug-ins are responsible for providing custom logic in the course of processing an operation or at other well-defined points within the directory server. The dsconfig command is used to manage the configuration of the directory server. For information about using dsconfig, see Section 14.1, "Managing the Server Configuration With dsconfig". This section covers the following topics:

• Section 14.1.9.1, "Overview of Plug-In Types"

• Section 14.1.9.2, "Modifying the Plug-In Configuration"

14.1.9.1 Overview of Plug-In Types

The dsconfig plugin-type property can be used to configure a plug-in to use one or more of the numerous plug-in types supported by the server. You cannot add a new default plug-in type to the configuration of an existing plug-in. Although, you can remove one or more of the default plug-in type values from a plug-in's configuration, you must take care when doing this. Usually a plug-in has been engineered to support its default plug-in types for a reason. Removing one or more plug-in types might endanger the safe operation of the directory server.

Most of the plug-ins support more than one type, and multiple plug-ins are sometimes defined with the same plug-in type. The order in which these plug-ins are invoked during processing is undefined. If a specific order is required (for example, if the processing performed by one plug-in depends on the result of another), you can specify the order in which the plug-ins are invoked. For more information, see Section 14.1.9.2.5, "To Configure Plug-In Invocation Order."

14.1.9.2 Modifying the Plug-In Configuration

The following sections show various examples of managing plug-in configuration using dsconfig. dsconfig uses the administration connector to access the server. All of the examples in this section assume that the administration connector is listening on the default port (4444) and that the command is accessing the server running on the local host. If this is not the case, the --port and --hostname options must be specified.

The dsconfig command always accesses the server over a secured connection with certificate authentication. If you run dsconfig in interactive mode, you are prompted as to how you want to trust the certificate. If you run dsconfig in non-interactive mode (that is, with the -n option) you must specify the -X or --trustAll option, otherwise the command will fail.

This section describes examples to manage plug-in configuration, and covers the following topics:

• Section 14.1.9.2.1, "To Display the List of Plug-Ins"

• Section 14.1.9.2.2, "To Create a New Plug-In"

• Section 14.1.9.2.3, "To Enable or Disable a Plug-In"

• Section 14.1.9.2.4, "To Display and Configure Plug-In Properties"

• Section 14.1.9.2.5, "To Configure Plug-In Invocation Order"

14.1.9.2.1 To Display the List of Plug-Ins

This example shows a directory server configured with the current supported plug-ins. For a description of these plug-ins and their purpose, see "The Plug-In Configuration" in the Oracle Unified Directory Configuration Reference.

Use dsconfig to display the list of plug-ins that are currently configured.

$ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -j pwd-file -X -n \
  list-plugins

Depending on your installation, the output will be similar to the following.

Plugin                          : Type                            : enabled
--------------------------------:---------------------------------:--------
7-Bit Clean                     : seven-bit-clean                 : false
Change Number Control           : change-number-control           : true
Entry UUID                      : entry-uuid                      : true
LastMod                         : last-mod                        : true
LDAP Attribute Description List : ldap-attribute-description-list : true
Password Policy Import          : password-policy-import          : true
Profiler                        : profiler                        : true
Referential Integrity           : referential-integrity           : false
Replication LDIF Import         : replication-ldif-import         : true
UID Unique Attribute            : unique-attribute                : false

The output of the command shows (from left to right):

• Plug-in. The name of the plug-in, usually descriptive of what it does.

• Type. The type of plug-in. It is possible to have more than one plug-in of a specific type.

• Enabled. Plug-ins can be enabled or disabled. Disabled plug-ins remain in the server configuration but do not perform any processing.

14.1.9.2.2 To Create a New Plug-In

The easiest way to configure plug-ins is to use dsconfig in interactive mode. Interactive mode walks you through the plug-in configuration, and is therefore not documented here.

This example creates and enables a new Password Policy Import Plug-in by using dsconfig in non-interactive mode.

Run the dsconfig command to create and enable a new Password Policy Import plug-in, as follows:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  create-plugin --type password-policy-import \
  --plugin-name "My Password Policy Import Plugin" --set enabled:true

14.1.9.2.3 To Enable or Disable a Plug-In

You can enable or disable a plug-in by setting the enabled property to true or false. This example disables the Password Policy Import plug-in created in the previous example.

Run the dsconfig command to disable the new Password Policy Import plug-in.

$ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -j pwd-file -X -n \
  set-plugin-prop --plugin-name "My Password Policy Import Plugin" \ 
  --set enabled:false

14.1.9.2.4 To Display and Configure Plug-In Properties

To display the properties of a plug-in, use the get-plugin-prop subcommand. To change the properties of a plug-in, use the set-plugin-prop subcommand. This example displays the properties of the plug-in created in the previous example, then enables the plug-in and sets the default authentication password storage scheme to Salted SHA-512.

1. Display the plug-in properties.

   $ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -j pwd-file -X -n \
     get-plugin-prop --plugin-name "My Password Policy Import Plugin"
   

   Depending on your installation, the output will be similar to the following.

   Property                             : Value(s)
   -------------------------------------:---------
   default-auth-password-storage-scheme : -
   default-user-password-storage-scheme : -
   enabled                              : false
   

2. Enable the plug-in and set the default authentication password storage scheme to Salted SHA-512.

   $ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -j pwd-file -X -n \
     set-plugin-prop --plugin-name "My Password Policy Import Plugin" \
     --set enabled:true\
     --set default-auth-password-storage-scheme:"Salted SHA-512"
   

3. Display the plug-in properties again to verify the change.

   $ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -j pwd-file -X -n \
     get-plugin-prop --plugin-name "My Password Policy Import Plugin" 
   
   Property                             : Value(s)
   -------------------------------------:---------------
   default-auth-password-storage-scheme : Salted SHA-512
   default-user-password-storage-scheme : -
   enabled                              : true
   

14.1.9.2.5 To Configure Plug-In Invocation Order

By default, the order in which plug-ins are invoked is undefined. You can specify that plug-ins be invoked in a specific order by using the set-plugin-root-prop --set plugin-type:value subcommand. The value in this case is the plug-in order, expressed as a comma-delimited list of plug-in names. The plug-in order string should also include a single asterisk element, which is a wildcard that will match any plug-in that is not explicitly named.

This example specifies that the Entry UUID plug-in should be invoked before any other pre-operation add plug-ins.

1. Display the current plug-in invocation order.

   $ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -j pwd-file -X -n \
     get-plugin-root-prop
   
   Property                                    : Value(s)
   --------------------------------------------:---------
   plugin-order-intermediate-response          : -
   plugin-order-ldif-export                    : -
   plugin-order-ldif-import                    : -
   plugin-order-post-connect                   : -
   ...
   

2. Set the plug-in order.

   $ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -j pwd-file -X -n \
     set-plugin-root-prop --set plugin-order-pre-operation-add:"Entry UUID,*"
   

   Note:

   Plug-in order values are not validated. Values that do not match defined plug-ins are ignored.

14.1.10 Configuring Suffixes with dsconfig

Oracle Unified Directory allows you to configure multiple suffixes, either during the setup or later.

This section contains the following topics:

• Section 14.1.10.1, "Configuring Suffixes with dsconfig During Setup"

• Section 14.1.10.2, "Configuring Suffixes with dsconfig on a Running Server"

You can also use dsconfig in interactive mode to achieve the configuration described in the following sections.

14.1.10.1 Configuring Suffixes with dsconfig During Setup

You can configure suffixes with the dsconfig command during the setup by creating the base entries.

Perform one of the following steps to create the base entries, dc=example,dc=com;dc=other,dc=com;dc=test,dc=com.

• Create the base entries using the following command:

  oud-setup --cli --baseDN dc=example,dc=com --baseDN dc=test,dc=com --baseDN \  
  dc=other,dc=com --addBaseEntry --ldapPort 2389 --adminConnectorPort 24444 \
  --rootUserDN cn=Directory Manager --rootUserPassword password --no-prompt \
  --noPropertiesFile
  

• Create the base entries with sample data using the following command:

  oud-setup --cli --baseDN dc=example,dc=com --baseDN dc=test,dc=com --baseDN \
  dc=other,dc=com --sampleData 15 --ldapPort 2389 --adminConnectorPort 24444 \
  --rootUserDN cn=Directory Manager --rootUserPassword password --no-prompt \
  --noPropertiesFile
  

You can now access data below all the suffixes without additional configuration.

14.1.10.2 Configuring Suffixes with dsconfig on a Running Server

You can configure suffixes on a running server instance either with the dsconfig command or by using ODSM. For more information about configuring suffixes with ODSM, see Section 14.2.3.1, "Create a Suffix."

Perform the following steps to configure suffixes with the dsconfig command:

1. Add the base DN to your local backend workflow element.

   dsconfig set-workflow-element-prop \
   --element-name userRoot \
   --add base-dn:dc=example2,dc=com \ 
   --hostname localhost \
   --port 24444 \
   --trustAll \ 
   --bindDN cn=directory manager \ 
   --bindPassword ****** \
   --no-prompt
   

2. Create a workflow for your new base DN.

   dsconfig create-workflow \
   --set base-dn:dc=example2,dc=com \
   --set enabled:true \
   --set workflow-element:userRoot \
   --type generic \
   --workflow-name dc=example2,dc=com \ 
   --hostname localhost \
   --port 24444 \
   --trustAll \ 
   --bindDN cn=directory manager \
   --bindPassword ****** \
   --no-prompt 
   

3. Add your new workflow to your network group.

   dsconfig set-network-group-prop \
   --group-name network-group \
   --add workflow:dc=example2,dc=com \
   --hostname localhost \ 
   --port 24444 \
   --trustAll \ 
   --bindDN cn=directory manager \
   --bindPassword ****** \
   --no-prompt
   

4. Create the base entry, dc=example2,dc=com.

5. Populate your new suffix with the required entries.

14.2 Managing the Server Configuration With Oracle Directory Services Manager

The Configuration tab of each server instance in ODSM enables you to modify elements of the server configuration. For additional information about managing the configuration that is specific to a proxy server instance, see Section 15.2, "Managing the Proxy Configuration With ODSM."

This section provides an overview of the tasks that can be performed on the Configuration tab in ODSM, and covers the following topics:

• Section 14.2.1, "Selecting a Configuration View"

• Section 14.2.2, "Shortcuts to Configuring Objects With ODSM"

• Section 14.2.3, "Configuring Suffixes With ODSM"

• Section 14.2.5, "Configuring Workflows With ODSM"

• Section 14.2.4, "Configuring Workflow Elements With ODSM"

• Section 14.2.6, "Configuring Connection Handlers With ODSM"

• Section 14.2.7, "Configuring Network Groups With ODSM"

• Section 14.2.8, "Modify the General Server Configuration"

14.2.1 Selecting a Configuration View

The Configuration tab presents two separate views of the server configuration:

• Naming Contexts. This is the default view, and shows the server configuration in terms of the naming contexts or suffixes configured on that server instance.

• Core Configuration. This view displays the server configuration in terms of the workflows, workflow elements and server extensions configured on that server instance.

The configuration view that you select determines the items that are available under the Create menu.

14.2.2 Shortcuts to Configuring Objects With ODSM

When you create server components by using ODSM, you can duplicate an existing component using the Create Like . When you select a component on the configuration tab and click Create Like, a new component with the same configuration is created. You can then edit the properties of the new component to suit your requirements.

You can also use the Create to create the same type of component as the one you have selected. For example, if you select LDAP Connection Handler in the left hand menu, and click Create, a new, unconfigured LDAP connection handler is created.

Right-clicking on a component in the left hand menu provides a list of actions related to that component. For example, if you right-click on LDAP Connection Handler, a drop-down menu is displayed, enabling you to create a new LDAP connection handler, duplicate that LDAP connection handler, or delete the connection handler.

14.2.3 Configuring Suffixes With ODSM

The following sections describe how to configure suffixes, or naming contexts, by using ODSM. For information about configuring suffixes by using dsconfig, see Section 14.1.10, "Configuring Suffixes with dsconfig".

14.2.3.1 Create a Suffix

Oracle Unified Directory allows you to configure one or more suffixes by using the ODSM interface as follows:

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

2. Select the Configuration tab.

3. Select the Naming Contexts view.

4. From the Create menu, select Local Naming Context.

5. In the Naming Context region, perform the following steps:

   1. In the Base DN field, type a name for the suffix that you want to create.

   2. From the Directory Data Options group, select one of the following options for populating the suffix with data:

      Only Create Base Entry creates the database along with the base entry of the suffix. Any additional entries must be added after suffix creation.

      Leave Database Empty creates an empty database. The base entries and any additional entries must be added after suffix creation.

      Import Generated Sample Data populates the suffix with sample entries.

      Specify the number of entries that should be generated in the Number of User Entries field. You can import a maximum of 30,000 sample entries through ODSM. If you want to add more than 30,000 entries, you must use the import-ldif command.

6. In the Oracle Components Integration region, select one of the following option to enable the new suffix:

   • No Specific Integration: Select this option, if you do not want to integrate the naming context with Oracle components.

   • Enable for Enterprise User Security (EUS):

     To enable a suffix for EUS, you must have at least one LDAP listener with SSL enabled, in addition to the administration listener. The suffix must contain at least one entry (in other words, you must not have selected "Leave Database Empty" in the previous step).

     When you select EUS, in addition to creating this suffix, two suffixes are created automatically: "cn=oracleschemaversion" and "cn=oraclecontext." An EUS workflow element is also added in front of the local backend workflow element. Further, a DN renaming workflow element for "cn=schema" is added, so that it can be accessed using the "cn=subschemasubentry" DN.

   • Enable for Oracle Database Net Services: Select this option if you want the naming context to store the Database Connect Identifiers.

7. In the Network Group region, attach the suffix to at least one network group by performing the following steps:

   • To attach the suffix to an existing network group, select Use Existing and select the required network group from the list.

   • To attach the suffix to a new network group, select Create New and then in the Name field, type a name for the network group you want to create.

   You can attach several network groups to the same suffix.

8. In the Workflow Element region, attach the suffix to the workflow element by performing either of the following steps:

   • To attach the suffix to an existing workflow element, select Use Existing and then select the required workflow element from the list.

   • To attach the suffix to a new workflow element, select Create New and then in the Name field, type a name for the workflow element you want to create. You can create a Local DB Workflow Element or a Local LDIF Workflow Element.

9. Click Create.

   The following confirmation message is displayed:

   Configuration created successfully.

   You can configure the tombstone entry purge interval and the tombstone entry lifetime after creating the suffix, in the local backend workflow element configuration.

14.2.3.2 Display and Edit Suffix Properties

In the Naming Contexts view, the Configuration tab displays all of the suffixes that have been configured on the server.

To display the properties of a configured suffix, follow these steps:

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

2. Select the Configuration tab.

3. Select the Naming Contexts view.

4. Expand the Naming Contexts element.

5. Click the suffix whose properties you want to display.

   The suffix properties are displayed in the right hand pane.

6. Make any required changes to the suffix configuration.

   You can change the network group to which this suffix is attached, and enable the suffix for Enterprise User Security (EUS) or Enable for Oracle Database Net Services.

   Note:

   If the Oracle Components Integration option was previously configured for the Enable for Enterprise User Security (EUS) or the Enable for Oracle Database Net Services options and if you have made changes in the Oracle Components Integration region, the Configuration Required dialog box appears. Depending on the option you choose, select one of the following:

   • Keep Oracle Context: Select this option, if you want to keep the naming context for EUS and Oracle Database Net Service.

   • Delete Oracle Context: Select this option, if you want to delete the naming context for EUS and Oracle Database Net Service.

   Click Apply to save your changes.

14.2.3.3 Delete a Suffix

In the Naming Contexts view, the Configuration tab displays all of the suffixes that have been configured on the server.

To delete a suffix, follow these steps:

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

2. Select the Configuration tab.

3. Select the Naming Contexts view.

4. Expand the Naming Contexts element.

5. Select the suffix that you want to delete.

6. Click the Delete configuration .

14.2.4 Configuring Workflow Elements With ODSM

A workflow element is the key building block of a workflow process. Workflow elements define how client requests that are sent to the server are treated. In a deployment that includes a proxy server, workflow elements are configured for load balancing or distribution. In a deployment that does not include a proxy server, workflow elements are configured directly for each backend.

The following sections describe how to configure workflow elements by using ODSM. For information about configuring workflow elements by using dsconfig, see Section 14.1.8, "Configuring Workflow Elements With dsconfig".

14.2.4.1 Create a Workflow Element

To create a workflow element by using ODSM, follow these steps:

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

2. Select the Configuration tab.

3. Select the Core Configuration view.

   For more information, see Section 14.2.1, "Selecting a Configuration View".

4. From the Create menu, select Workflow Element and select the type of workflow element that you want to create.

   For more information about the various workflow element types, see Section 4.1.3, "Workflow Elements".

5. The properties of the workflow element that must be configured depend on the type of workflow element that you are creating.

   All workflow elements require the following basic properties to be configured:

   Name. Enter a name for the workflow element.

   Enabled. When you create a workflow element, it is enabled by default. Clear this item to disable the workflow element.

   In addition, the following properties must be configured for each corresponding workflow element type:

   • DN Renaming Workflow Element

     • Client Base DN: Specify the base DN that is used by the client application.

     • Source Base DN: Specify the base DN that is stored in the LDAP server.

     • Next Workflow Element: Select the workflow element that should be next in the workflow.

     • Attribute White List: Click Add to select the list of attributes that contain DNs and must be transformed by the renaming operation.

     • Attribute Black List: Click Add to select the list of attributes that contain DNs but must not be transformed by the renaming operation.

   • EUS Workflow Element

     • EUS Realm: Enter the part of the DIT to which the EUS workflow element applies.

     • Next Workflow Element: Select the workflow element that should be next in the workflow.

     • Server Type: Select the server containing the EUS user entries.

     • Password Attribute: Enter the attribute type that should be used to hold the EUS user passwords.

   • EUS Context Workflow Element

     • EUS Context: Enter the DN that contains the Oracle Context. The oracle context is a top-level directory entry that contains the data used by any installed Oracle product that uses the directory.

     • EUS Administrator: Enter the DN of the administration user. This user will be the uniquemember of the groups created in Oracle Context.

     • Next Workflow Element: Select the workflow element that should be next in the workflow.

   • Kerberos Authentication Provider Workflow Element

     • Realm: Specify the realm to be used for Kerberos authentication. If you do not specify any realm then the server attempts to determine the realm from the underlying system configuration.

     • Principal Name Attribute: Click Select and specify the Principal Name Attribute.

     • KDC Address: Specify the Key Distribution Center (KDC) server address.

   • Local DB Workflow Element

     • Writability Mode: Specify whether the backend associated with this workflow element should process write operations.

     • Base DN: Specify one or more base DNs for the data that is handled by the backend.

     • Database Properties: Specify any specific properties for the database. For a detailed list of these properties, and their values, see "DB Local Backend Workflow Element" in the Oracle Unified Directory Configuration Reference.

     • Tombstone Configuration: Specify how tombstone entries should be handled for the database. For a detailed list of these properties, and their values, see "DB Local Backend Workflow Element" in the Oracle Unified Directory Configuration Reference.

     • Index Properties: Specify the following parameters:

       Index Subtrees: Enable or disable the check box to indicate whether or not the backend should index subtrees to maintain subtree specific data retaining information on direct and indirect children entries of each parent entry.

       Local DB Index: Specify the local DB index configuration for the database. For a detailed list of these properties, and their values, see "DB Local Backend Workflow Element" in the Oracle Unified Directory Configuration Reference.

       Local DB VLV Index: Specify the local DB VLV index configuration for the database. For a detailed list of these properties, and their values, see "DB Local Backend Workflow Element" in the Oracle Unified Directory Configuration Reference.

   • Local LDIF Workflow Element

     • Writability Mode: Specify whether the backend associated with this workflow element should process write operations.

     • Base DN: Specify one or more base DNs for the data that is handled by the backend.

     • Private Backend: Specify whether the backend should be considered a private backend, which indicates that it is used for storing operational data rather than user-defined information.

     • LDIF File: Enter the path to the LDIF file containing the data for this backend.

   • Pass Through Authentication Workflow Element

     • User Provider Workflow Element: Select the workflow element providing the requested user entry.

     • Authentication Provider Workflow Element: Select the workflow element providing the authentication service for the user entry. For example, you can use Kerberos Authentication Provider workflow element or Local DB workflow element as the authentication provider.

   • Local Memory Workflow Element

     • Base DN: Specify one or more base DNs for the data that is handled by the backend.

   • RDN Changing Workflow Element

     • Next Workflow Element: Select the workflow element that should be next in the workflow.

     • Object Class: Select the object class type for RDN changing operation.

     • Source RDN Attribute: Select the original RDN attribute name from the source directory to be replaced or renamed in Oracle Unified Directory.

     • Client RDN Attribute: Select the new RDN attribute name to be used in Oracle Unified Directory.

     • Replace RDN Value: Specify whether the original RDN value should be replaced by the new RDN value. It is enabled by default.

     • DN Attributes: Click Add to select the list of attributes with DNs to perform RDN renaming on.

   • Transformations Workflow Element

     • Next Workflow Element: Select the workflow element that should be next in the workflow.

     • Entry Matching Filter: This is an LDAP filter. If this option is selected then entries will be transformed only if they match this LDAP Filter.

     • Entry Parent Suffixes: This is optional, you can specify a list of suffixes to restrict applying transformation to entries under specific subtrees. If you specify this option then the entries will be specified only if they are in subtrees rooted at any of these suffixes.

     • Excluded Operations: If you specify this option, the entries will not be transformed during any of the specified operations

     • Transformations: The list of transformations that the Transformations Workflow Element will process. The order in which transformations are listed here does not guarantee the order in which these transformations will be applied when processing a request at runtime.)

6. Click Create.

   The following confirmation message is displayed:

   Workflow Element created successfully.

14.2.4.2 Display and Edit Workflow Element Properties

To display or modify the properties of an existing workflow element, follow these steps:

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

2. Select the Configuration tab.

3. Select the Core Configuration view.

   For more information, see Section 14.2.1, "Selecting a Configuration View".

4. Expand the Core Configuration element.

5. Expand the Workflow Elements element.

6. Click on the workflow element that you want to view, or modify.

   The properties of the workflow element are displayed in the right hand pane

7. The properties that you can edit depend on the type of workflow element that is configured.

8. Click Apply to save your changes.

14.2.4.3 Delete a Workflow Element

To delete an existing workflow element, follow these steps:

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

2. Select the Configuration tab.

3. Select the Core Configuration view.

   For more information, see Section 14.2.1, "Selecting a Configuration View".

4. Expand the Core Configuration element.

5. Expand the Workflow Elements element.

6. Click on the workflow element that you want to delete and click the Delete configuration .

7. Click OK to confirm the deletion.

14.2.5 Configuring Workflows With ODSM

A workflow is defined by a naming context, or suffix, and a workflow element that define how Oracle Unified Directory should handle an incoming request. A workflow must be registered with at least one network group, but can be attached to several network groups.

For more information about workflows, workflow elements and the other components of Oracle Unified Directory, see Section 4.1, "Oracle Unified Directory Components."

The following sections describe how to configure workflows by using ODSM. For information about configuring workflows by using dsconfig, see Section 14.1.7, "Configuring Workflows With dsconfig".

14.2.5.1 Create a Workflow

To create a workflow by using ODSM, follow these steps:

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

2. Select the Configuration tab.

3. Select the Core Configuration view.

   For more information, see Section 14.2.1, "Selecting a Configuration View".

4. From the Create menu, select Workflow.

5. In the Workflow Properties region, enter the following information:

   1. In the Name field, type a name for the workflow that you want to create.

   2. Select the Enabled check box if you want this workflow to be enabled.

      Deselect this check box if you do not want to enable the workflow at this stage.

6. In the Base DN field, enter the naming context that will be accessible through this workflow.

7. Select the Workflow Element with which this workflow should be associated.

   The workflow element must already exist before you create the workflow.

8. Select True, False, or Partial depending on whether the workflow is critical enough to fail a search operation involving multiple workflows and if the operation fails on this workflow.

9. Click Create.

   The following confirmation message is displayed:

   Workflow created successfully.

14.2.5.2 Display and Edit Workflow Properties

In the Core Configuration view, the Configuration tab displays all of the workflows and workflow elements that have been configured on the server.

To display the properties of a configured workflow, follow these steps:

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

2. Select the Configuration tab.

3. Select the Core Configuration view.

   For more information, see Section 14.2.1, "Selecting a Configuration View".

4. Expand the Workflows element.

5. Click the workflow whose properties you want to display.

   The workflow properties are displayed in the right hand pane.

6. Make any required changes to the suffix configuration.

   You can disable the workflow, or change the workflow element with which this workflow is associated.

   Click Apply to save your changes.

14.2.5.3 Delete a Workflow

You can delete a workflow by using ODSM, only if that workflow is not referenced by any network group.

To delete a workflow, follow these steps:

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

2. If the workflow is referenced by a network group, modify the properties of the network group to remove that workflow.

   For more information, see Section 14.2.7.2, "Modify a Network Group".

3. Select the Configuration tab.

4. Select the Core Configuration view.

   For more information, see Section 14.2.1, "Selecting a Configuration View".

5. Expand the Workflows element.

6. Select the workflow that you want to delete and click the Delete configuration.

7. Click OK to confirm the deletion.

14.2.6 Configuring Connection Handlers With ODSM

Connection handlers are responsible for accepting connections from clients, reading and parsing requests submitted by the clients, ensuring that they are processed by the server, and sending the corresponding responses back to the client. A connection handler manages all communication with the client and therefore needs to implement support for the associated protocol.

The following sections describe how to configure connection handlers by using ODSM. For information about configuring connection handlers by using dsconfig, see Section 14.1.5, "Configuring Connection Handlers With dsconfig".

14.2.6.1 Create a Connection Handler

To create a connection handler by using ODSM, follow these steps:

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

2. Select the Configuration tab.

3. From the Create menu, select Connection Handler.

4. Select the type of connection handler that you want to create:

   • LDAP. This connection handler is used to interact with clients using LDAP. It provides full support for LDAPv3 and limited support for LDAPv2.

   • LDAPS. This connection handler is used to interact with clients using LDAP over SSL.

   • LDIF. This connection handler is used to process changes in the server using internal operations.

   • JMX. This connection handler allows interactions with clients using the Java Management Extensions (JMX) framework and the Remote Method Invocation (RMI) protocol.

   • SNMP. This connection handler is used to process SNMP requests to retrieve monitoring information described by MIB 2605. The supported SNMP protocols are SNMP V1, V2c and V3.

5. Enter the properties to configure the connection handler in the right hand pane.

   The configurable properties will depend on the type of connection handler you have selected. For a comprehensive list of all configurable properties, and their allowed values, see "The Connection Handler Configuration" in the Oracle Unified Directory Configuration Reference.

6. When you have configured the required properties for your specific connection handler type, click Create.

   The following confirmation message is displayed:

   Connection Handler created successfully.

14.2.6.2 Modify a Connection Handler

To view or modify connection handler properties by using ODSM, follow these steps:

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

2. Select the Configuration tab.

3. Expand the General Configuration element.

4. Expand the Connection Handlers element.

5. Click on the connection handler whose properties you want to modify.

   The properties are displayed in the right hand pane.

   For a comprehensive list of all configurable properties, and their allowed values, see "The Connection Handler Configuration" in the Oracle Unified Directory Configuration Reference.

6. Change the required properties and click Apply.

14.2.6.3 Delete a Connection Handler

To delete an existing connection handler by using ODSM, follow these steps:

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

2. Select the Configuration tab.

3. Expand the General Configuration element.

4. Expand the Connection Handlers element.

5. Click on the connection handler that you want to delete and click the Delete configuration .

6. You are prompted to confirm the deletion. Click OK.

14.2.7 Configuring Network Groups With ODSM

Network groups are the entry point of all client requests that are handled by an Oracle Unified Directory server. The properties of a network group indicate how client requests are directed.

The following sections describe how to configure network groups by using ODSM. For information about configuring network groups by using dsconfig, see Section 14.1.6, "Configuring Network Groups With dsconfig".

14.2.7.1 Create a Network Group

To create a network group by using ODSM, follow these steps:

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

2. Select the Configuration tab.

3. From the Create menu, select Network Group.

4. Enter the properties to configure the network group in the right hand pane.

   • Name. Enter a name for the network group.

   • Enabled. Select or deselect this check box to enable or disable the network group. If you disable a network group, no client requests can be handled by that network group. If you disable the only configured network group, you effectively stop client applications from accessing the backend.

   • Priority. In the event of multiple network groups, set priority for this network group. Client requests are handled by the network group with the highest priority, for which the criteria are met. The highest priority a network group can have is 0.

   • Workflow. Click the Add () to add one or more workflows that can be accessed through this network group.

   • Root DSE to Expose. Select the Root DSE that you want this network group to expose. You can expose the Root DSE of the local server, the Root DSE stored in a remote server, or the Root DSE defined in a local file.

     Click Other and select one of the following option:

     • Root DSE Defined in LDIF File: Enter the path of the LDIF file containing the Root DSE. The server must have access to this file.

     • Root DSE of a Remote Server: Enter the following parameters:

       Host Name: Enter the host name of the remote server.

       Ports Available: Enter the LDAP port, LDAPS port, or LDAP and LDAPS ports of the remote server.

       Trust All: Select this check box to trust all the certificates presented by the remote server.

       Trust Manager: Select the trust manager that the server will use when connecting to the LDAPS ports of the remote server to forward requests.

   • Security Mandatory. Select this option if you require clients to use a secure connection to access this network group. By default, a secure connection is not required.

   • Allowed auth method. Specify the authentication method/s that are allowed between the client and the network group.

   • Allowed protocol. Specify the protocol/s that are allowed for client connections. If you do not specify a protocol, all protocols are allowed.

   • Allowed BindDN. Click the Add to add one or more bind DNs that are allowed to connect to this network group. Click the Delete () to remove the bind DNs that should not be accepted by the network group.

   • Allowed Client. Click the Add to add one or more clients that are authorized to access this network group. Clients can be expressed by their IP addresses or names, or by a subnet mask. If no allowed client list is provided, all clients are allowed, unless they are specifically listed on the denied client list.

   • Denied Client. Click the Add to add one or more clients that are prohibited from accessing this network group. Clients can be expressed by their IP addresses or names, or by a subnet mask. If no denied client list is provided, all clients are allowed, unless a limitation is set by using the allowed client list.

   • QoS Policy. Select a quality of service policy for this network group. For more information, see Section 14.1.6.3, "Creating a Network Group Quality of Service Policy."

5. When you have configured the required properties for the network group, click Create.

   The following confirmation message is displayed:

   Network Group created successfully.

14.2.7.2 Modify a Network Group

You can display or modify the properties of a network group, as follows:

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

2. Select the Configuration tab.

3. Expand the General Configuration element.

4. Expand the Network Groups element.

5. Select the network group whose properties you want to modify.

   The properties of the network group are displayed in the right hand pane

6. Change the required properties and click Apply.

   For an explanation of each of the configured properties, see Section 14.2.7.1, "Create a Network Group".

14.2.7.3 Delete a Network Group

To delete an network group by using ODSM, follow these steps:

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

2. Select the Configuration tab.

3. Expand the General Configuration element.

4. Expand the Network Groups element.

5. Click on the network group that you want to delete and click the Delete configuration .

6. You are prompted to confirm the deletion. Click OK.

14.2.8 Modify the General Server Configuration

Certain elements of the general server configuration can be modified by using ODSM, as follows:

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

2. Select the Configuration tab.

3. Select the General Configuration element.

   The properties are displayed in the right hand pane.

4. You can modify the following properties:

   • Default Password Policy

   • Etime Resolution

   • Idle Time Limit

   • Max Allowed Client Connections

   • Maintain Authenticated Users

   • Reject Unauthenticated Requests

   • Size Limit

   • Writability Mode

   • Root DSE Properties

   • Work Queue Properties

   • Number of Worker Threads

   Click Apply to save your changes.

   For a comprehensive list of the configurable properties, and their allowed values, see "Global Configuration" in the Oracle Unified Directory Configuration Reference.

14.3 Managing Administration Traffic to the Server

Connection handlers are responsible for handling all interaction with client applications, including accepting connections, reading requests, and sending responses.Oracle Unified Directory includes a special connection handler, the administration connector, to manage administration traffic to the server. The administration connector enables the separation of user traffic and administration traffic to simplify monitoring, and to ensure that administrative commands take precedence over commands that manipulate user data.

This section describes how administration traffic is handled, and covers the following topics:

• Section 14.3.1, "Overview of the Administration Connector"

• Section 14.3.2, "Accessing Administrative Suffixes"

• Section 14.3.3, "To Configure the Administration Connector"

• Section 14.3.4, "Key Managers and Trust Managers for the Administration Connector"

14.3.1 Overview of the Administration Connector

The administration connector is based on the LDAP protocol and uses LDAP over SSL by default. All command-line utilities that access the administrative suffixes use the administration connector. This includes the following commands:

• backup

• dsconfig

• dsreplication

• export-ldif

• import-ldif

• manage-account

• manage-tasks

• restore

• status

• stop-ds

• uninstall

The administration connector is always present and enabled. You cannot disable or delete the connector but you can use dsconfig to manipulate the following properties of the connector:

• listen-address. The address on which the server listens for administration traffic.

• listen-port. The default port of the administration connector is 4444. You can change this port during setup if required. If you use the default port, you do not need to specify a port when running the administration commands (the default port is assumed). If you change the port, you must specify the new port when running the administration commands.

  If you have multiple directory server instances running on the same host, you will have specified multiple separate administration listen ports during setup. In this case, for the server instances whose administration connectors do not use the default listen port (4444), you will need to specify the port when running the administration commands.

• Security-related properties. Traffic using the administration connector is always secured. As with the LDAPS connection handler, the administration connector is configured with a self-signed certificate (admin-cert) during server setup. This self-signed certificate is generated the first time the server is started. You can manage the administration connector certificate using external tools, such as keytool.

  The security-related properties of the administration include the following:

  • ssl-cert-nickname

  • ssl-cipher-suite

  • key-manager-provider

  • trust-manager-provider

  When you run the administration commands, you are prompted as to how you want to trust the certificate. If you run the administration commands in non-interactive mode, you must specify the -X or --trustAll option to trust the certificate, otherwise the command will fail.

14.3.2 Accessing Administrative Suffixes

The administrative suffixes include the following:

• cn=config

• cn=monitor

• cn=tasks

• cn=backups

• cn=ads-truststore

• cn=schema

• cn=admin data

In general, direct LDAP access to the administrative suffixes (using the ldap* utilities) is discouraged, with the exception of the cn=monitor suffix. In most cases, it is preferable to use the dedicated administrative command-line utilities to access these suffixes.

If you must use the ldap* commands to access the administrative suffixes, you must use the administration connector port (with the --useSSL or -Z option). Using the administration connector ensures that monitoring data is not polluted and that server administration takes precedence over user traffic. The same restriction applies if you are accessing the administrative suffixes using an LDAP browser.

14.3.3 To Configure the Administration Connector

This example displays the default properties of the administration connector, and changes the listen port of the connector to 5555.

1. View the default properties of the administration connector, using the dsconfig command.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
     get-administration-connector-prop
   

   The output is similar to the following.

   Property               : Value(s)
   -----------------------:---------------
   key-manager-provider   : Administration
   listen-address         : 0.0.0.0
   listen-port            : 4444
   ssl-cert-nickname      : admin-cert
   ssl-cipher-suite       : -
   trust-manager-provider : Administration
   

2. Change the listen port, using the dsconfig command.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
    set-administration-connector-prop --set listen-port:5555
   

   Note:

   You must restart the server for changes to this property to take effect.

14.3.4 Key Managers and Trust Managers for the Administration Connector

The administration connector is an LDAPS connector. As with all SSL-based connectors, the administration connector requires a key manager and trust manager.

Oracle Unified Directory provides a dedicated key manager and trust manager for the administration connector, that are enabled by default. You can change the properties of the default administration key manager and trust manager. For more information, see Section 20.2, "Configuring Key Manager Providers" and Section 20.3, "Configuring Trust Manager Providers".

14.4 Configuring Commands As Tasks

Certain command-line utilities can be used to schedule tasks to run within the directory server as well as to perform their functions locally. Tasks that can be scheduled support the options used to connect to the directory server to interact with the task back end.

This section contains the following topics:

• Section 14.4.1, "Commands That Can Schedule Tasks"

• Section 14.4.2, "Controlling Which Tasks Can Be Run"

• Section 14.4.3, "Scheduling and Configuring Tasks"

• Section 14.4.4, "Managing and Monitoring Scheduled Tasks"

14.4.1 Commands That Can Schedule Tasks

The following utilities can schedule tasks:

• import-ldif

• export-ldif

• backup

• restore

• stop-ds

• stop-ds --restart

• rebuild-index

• dsreplication purge-historical

For a proxy server, only the stop-ds command can be scheduled to run as a task.

14.4.2 Controlling Which Tasks Can Be Run

You can control the tasks that can be run by setting the allowed-tasks advanced global configuration property. By default, all tasks supported by the tasks back end are allowed. To prevent a task from being run, remove its value from the allowed-tasks property. For example, to prevent the server from being stopped using a task, run the following command:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-global-configuration-prop --remove \
  allowed-task:org.opends.server.tasks.ShutdownTask

14.4.3 Scheduling and Configuring Tasks

The procedures in this section indicate how to schedule a task, how to configure task notification, and how to configure task dependencies. All of the examples in this section assume that the commands are being run on the local host, using the default administration port (4444), and the local certificate configuration. If you are running the commands remotely, you might need to specify the certificate parameters. For more information, see Section 14.3, "Managing Administration Traffic to the Server."

This section describes procedures to schedule and configure tasks, and contains the following topics:

• Section 14.4.3.1, "To Schedule a Task"

• Section 14.4.3.2, "To Schedule a Recurring Task"

• Section 14.4.3.3, "To Configure Task Notification"

• Section 14.4.3.4, "To Configure Task Dependencies"

14.4.3.1 To Schedule a Task

To schedule a task, invoke the required utility with the options used to connect to the directory server, an optional start time, and any options that will be used as arguments for the task execution.

If the -t or --start option is provided, the utility exits immediately after scheduling the task. To schedule a task for immediate execution and have the utility exit immediately after scheduling the task, specify 0 as the value for the start time.

If the -t or --start option is omitted, the utility schedules the task for immediate execution and tracks the task's progress, printing log messages as they are available and exiting when the task has completed.

Schedule the export-ldif task to start at 12:15 on September 24th, 2009.

$ export-ldif -D "cn=directory manager" -j pwd-file \
  -l /ldif-files/example.ldif --start 20090924121500 -n userRoot

14.4.3.2 To Schedule a Recurring Task

To schedule a recurring task, invoke the required utility with the options used to connect to the directory server, specifying the recurring task schedule, and any options that will be used as arguments for the task execution. The following commands can be scheduled as recurring tasks:

• import-ldif

• export-ldif

• backup

• restore

• rebuild-index

• dsreplication purge-historical

The --recurringTask option specifies a recurring task schedule that is used by the task scheduler to determine when and how often a recurring task should run. The pattern used to specify the schedule is based on UNIX crontab(5) scheduling patterns and rules and includes the following five integer pattern fields, separated by blank spaces:

• Minute [0,59]

• Hour [0,23]

• Day of the month [1,31]

• Month of the year [1,12]

• Day of the week [0,6] (with 0=Sunday)

Each of these patterns can be either an asterisk (meaning all valid values), an element, or a list of elements separated by commas. An element is either a number or two numbers separated by a dash (meaning an inclusive range).

The task scheduler spawns regular task iterations according to the specified schedule.

Schedule the task using the --recurringTask option.

The following command schedules a backup task to execute at the beginning of every hour.

$ backup -D "cn=directory manager" -j pwd-file --recurringTask \
  "00 * * * *" --backupDirectory /example/backup --backUpAll --backupID "Hourly Backup"

The following example shows an export task that is scheduled to run every 15 minutes, every Sunday.

$ export-ldif -D "cn=directory manager" -j pwd-file --recurringTask \
  "0,15,30,45 * * * 0" -l PATH/export-recurring.ldif -n userRoot
Recurring Export task  ExportTask-a614e45d-6ba5-4c29-a8e1-d518c20e46ab scheduled
successfully

14.4.3.3 To Configure Task Notification

The task scheduling options of a utility enable you to notify an administrator when a task completes or if an error occurs during the task's execution. To use the notification facility, an SMTP server must be configured for the directory server.

1. Specify an SMTP server by setting the smtp-server global configuration property.

   The following command configures the SMTP server named mailserver.example.com:

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
     set-global-configuration-prop --set smtp-server:mailserver.example.com
   

2. Use the completionNotify and errorNotify options to specify the email address to which the task notification should be sent.

   The following command schedules a backup task and specifies that [e-mail] should be notified when the task completes, or when an error occurs:

   $ backup -D "cn=directory manager" -j pwd-file -a -d /tmp/backups \
     --start 20080924121500 --completionNotify [e-mail] \
     --errorNotify [e-mail]
   Backup task 20080924121500 scheduled to start Sep 24, 2008 12:15:00 PM SAST
   

14.4.3.4 To Configure Task Dependencies

Certain tasks might require that another task be completed before the task begins. The task dependency options of a utility enable you to specify that the task depends on another task, and what the task should do should the other task fail.

Schedule the task and specify the dependency and failedDependencyAction.

The following example schedules a backup task that depends on another task, and specifies that the backup should be canceled should the other task fail:

$ backup -D "cn=directory manager" -j pwd-file -a -d /tmp/backups \
  --start 2008102914530410 --dependency 20080924121500 \
  --failedDependencyAction cancel
Backup task 2008102914530410 scheduled to start Oct 29, 2008 14:53:04 PM SAST

14.4.4 Managing and Monitoring Scheduled Tasks

The manage-tasks utility can be used to obtain a list of scheduled tasks, to display task status, and to cancel scheduled tasks. The following procedures provide examples of managing scheduled tasks:

• Section 14.4.4.1, "To Obtain Information About Scheduled Tasks"

• Section 14.4.4.2, "To Cancel a Scheduled Task"

• Section 14.4.4.3, "To Cancel a Recurring Task"

14.4.4.1 To Obtain Information About Scheduled Tasks

1. Display a summary of all scheduled tasks.

   $ manage-tasks -D "cn=directory manager" -j pwd-file -n -s
   ID                Type    Status
   ------------------------------------------------
   2008100912550010  Backup  Completed successfully
   2008100912554710  Backup  Completed successfully
   2008100912560510  Backup  Waiting on start time
   2008100912561410  Backup  Waiting on start time
   

2. Display additional information on a particular task, specified by its task ID.

   $ manage-tasks -D "cn=directory manager" -j pwd-file -n -i 2008100912550010
   
   Task Details
   ------------------------------------------------------
   ID                        2008100912550010
   Type                      Backup
   Status                    Completed successfully
   Scheduled Start Time      Immediate execution
   Actual Start Time         Oct 9, 2008 12:55:00 PM SAST
   Completion Time           Oct 9, 2008 12:55:01 PM SAST
   Dependencies              None
   Failed Dependency Action  None
   Email Upon Completion     None Specified
   Email Upon Error          None Specified
   
   Backup Options
   ----------------------------
   Backup All        true
   Backup Directory  ../backups
   
   Last Log Message
   ------------------------------------------------------------------------------
   [09/Oct/2008:12:55:01 +0200] severity="NOTICE" msgCount=4 msgID=10944795
   message="The backup process completed successfully"
   

14.4.4.2 To Cancel a Scheduled Task

Run the manage-tasks utility with the -c or --cancel option.

The following command cancels a particular task, specified by its task ID:

$ manage-tasks -D "cn=directory manager" -j pwd-file -n -c 2008100912561410

14.4.4.3 To Cancel a Recurring Task

You can cancel an entire recurring task, in which case both the recurring task and its next scheduled iteration are canceled. Alternatively, you can cancel only the next scheduled task iteration, in which case future recurring task iterations will be spawned by the task scheduler.

1. Use the manage-tasks command to display the summary of scheduled tasks.

   $ manage-tasks -D "cn=directory manager" -j pwd-file -n -s
   
    ID                                             Type    Status
   ----------------------------------------------------------------------------
    Hourly Backup                                  Backup  Recurring
    Hourly Backup - Wed Jan 14 13:00:00 SAST 2009  Backup  Waiting on start time
   

2. Run the manage-tasks utility with the -c or --cancel option.

   1. Cancel the entire recurring task by specifying its task ID.

      $ manage-tasks -D "cn=directory manager" -j pwd-file -n -c "Hourly Backup"
      Task Hourly Backup canceled
      

   2. Cancel the next scheduled task by specifying its task ID.

      $ manage-tasks -D "cn=directory manager" -j pwd-file -n \
        -c "Hourly Backup - Wed Jan 14 13:00:00 SAST 2009 "
      Task Hourly Backup - Wed Jan 14 13:00:00 SAST 2009  canceled 
      

14.5 Deploying and Configuring the DSML Gateway

The Directory Services Markup Language (DSML) is a SOAP-based mechanism that can communicate with directory servers using an XML-based representation instead of the LDAP protocol. Oracle Unified Directory 11g Release 2 PS1 (11.1.2.1.0) supports the use of DSML through a web application that acts as a DSML-to-LDAP gateway, in which clients communicate with the gateway using DSML, but the gateway communicates with the directory server through LDAP.

This section describes how to configure and deploy the DSML gateway, and contains the following topics:

• Section 14.5.1, "Deploying the DSML Gateway"

• Section 14.5.2, "Confirming the DSML Gateway Deployment"

14.5.1 Deploying the DSML Gateway

The DSML gateway can be deployed like any other web application, in most common application containers. The following section describes how to deploy the DSML gateway in Oracle WebLogic Server 10.3.5, on a UNIX system.

• Section 14.5.1.1, "Deploying the DSML Gateway in Oracle WebLogic Server"

• Section 14.5.1.2, "Deploying the DSML Gateway in IBM WebSphere"

14.5.1.1 Deploying the DSML Gateway in Oracle WebLogic Server

This section assumes that you have Oracle WebLogic Server installed. If you do not, install Oracle WebLogic Server, as described in "Installing Oracle WebLogic Server" in Oracle Fusion Middleware Installation Guide for Oracle Unified Directory.

Configuring WebLogic Server for the DSML Gateway

1. Run the configuration wizard from the following location:

   OUD_BASE_LOCATION_HOME/wlserver_10.3/common/bin/config.sh

2. On the Welcome screen, select Create a new WebLogic domain and click Next.

3. On the Select Domain Source screen, accept the default selection (Basic WebLogic Server Domain) and click Next.

4. On the Specify Domain Name and Location screen, type a domain name and specify its location.

   A new WebLogic domain is created in this location. The DSML gateway will be deployed into this domain.

5. On the Configure Administrator User Name and Password screen, type a name and password for the user who will administer this domain.

   The password must be at least eight characters and must contain at least one number or special character. Confirm the password and click Next.

   Make a note of these details as you will need them to start or restart the WebLogic domain.

6. On the Configure Server Start Mode screen, select Production Mode.

   Select a valid JDK (at least Java 1.6) and click Next.

7. On the Optional Configuration screen, click Next.

8. On the Configuration Summary screen, verify the domain details and click Create.

9. On the Creating Domain Screen, click Done.

10. Set the Java options for the WebLogic Server.

    $ export JAVA_OPTIONS=-Djavax.xml.soap.MessageFactory=weblogic.xml.saaj.MessageFactoryImpl
    

    If you do not set the Java options, an error will be returned.

11. Set the enforce-valid-basic-auth-credentials flag in the configuration file of the WebLogic domain (DOMAIN_HOME/config/config.xml, where DOMAIN_HOME is the domain that you created in Step 4.

    For example, edit the file OUD_BASE_LOCATION_HOME/user_projects/domains/base_domain/config/config.xml by adding the following line to the security-configuration element:

    <enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>

    For more information, see https://download.oracle.com/docs/cd/E12840_01/wls/docs103/security/thin_client.html#understanding_basic_atn.

12. Start the WebLogic Server by running DOMAIN_HOME/bin/startWebLogic.sh (where DOMAIN_HOME is the domain that you created in Step 4.

    For example:

    OUD_BASE_LOCATION_HOME/user_projects/domains/base_domain/bin/startWebLogic.sh

13. Deploy the DSML Gateway WAR file, as described in the following section.

Deploying the DSML Gateway WAR File

1. Create a DSML directory in the addons directory and change to that directory.

   $ cd OUD_BASE_LOCATION_HOME/ORACLE_HOME/addons
   $ mkdir DSML
   $ cd DSML
   

2. Explode the DSML gateway WAR file.

   $ jar xvf ../OUD-DSML.zip
   

3. Edit the DSML configuration, if required.

   The WEB-INF/web.xml file includes initialization parameters that can be used to specify the address (in the ldap.host parameter) and port number (in the ldap.port parameter) of the directory server to which DSML requests should be forwarded.

   By default, the DSML gateway is configured to communicate with a directory server on the same system, that is, localhost) on port 389. If you need to change the host address and port number, edit the web.xml file and restart the web container.

4. In a browser window, connect to the WebLogic Administration Console (for example http://hostname:7001/console), where hostname is the host on which WebLogic Server is running.

   Use the administrator user name and password that you established in Step 5 of the preceding procedure.

5. Follow the WebLogic Server Documentation to install a Web application (https://download.oracle.com/docs/cd/E12840_01/wls/docs103/ConsoleHelp/taskhelp/web_applications/InstallWebApplications.html).

   • In step 4 of the procedure, provide the path to the exploded application (OUD_BASE_LOCATION_HOME/ORACLE_HOME/addons/DSML).

   • In step 6 of the procedure, select Install this deployment as an application.

   • Accept the default values for the other steps.

6. On the left panel of the Administration Console, click Deployments.

7. Select the checkbox next to the DSML application and click Start then Servicing all requests.

8. On the Start Deployments panel, click Yes.

9. The DSML application is now deployed and available for use.

14.5.1.2 Deploying the DSML Gateway in IBM WebSphere

To deploying the DSML Gateway WAR File in IBM Websphere, complete the following:

Note:

Ensure that you have installed and configured IBM WebSphere, as described in the "Configuring IBM WebSphere for Oracle Directory Services Manager" in Oracle Fusion Middleware Installation Guide for Oracle Unified Directory.

1. Create a DSML directory in the addons directory and change to that directory.

   $ cd OUD_BASE_LOCATION_HOME/ORACLE_HOME/addons
   $ mkdir DSML
   $ cd DSML
   

2. Explode the DSML gateway WAR file.

   $ jar xvf ../OUD-DSML.war
   

3. Edit the DSML configuration, if required.

   The WEB-INF/web.xml file includes initialization parameters that can be used to specify the address (in the ldap.host parameter) and port number (in the ldap.port parameter) of the directory server to which DSML requests should be forwarded.

   By default, the DSML gateway is configured to communicate with a directory server on the same system, that is, localhost) on port 389. If you need to change the host address and port number, edit the web.xml file and restart the web container.

4. In a browser, log in to the IBM WebSphere Administrative Console.

   http://Hostname:Port-Number/ibm/console/
   

5. Choose Application, and then New Application in the left panel.

6. Click New Enterprise Application.

   The Preparing for the application installation page is displayed.

   1. Specify the path to the OUD-DSML.war file and click Next.

      • If the OUD-DSML.war file is located on the local system, type its complete path under Local File System.

      • If the file is on a remote IBM WebSphere machine, specify the path for the remote file system.

   2. Select Detailed - Show me all installation options and parameters.

   3. On the Choose to generate default bindings and mappings page keep the default configuration and click Next.

7. Click Continue on the Application Security Warning page.

   The Select Installation Options page is displayed.

8. Enter the following details:

   1. To install the application to a location other than the default location, type the path in the Directory to Install Application field. For example, on UNIX systems:

      /opt/IBM/Websphere/AppServer/installed Apps/Hostname

   2. Verify that the following options are selected:

      • Precompile JavaServer Pages files

      • Distribute application

      • User binary configuration

   3. Enter the name of the application in the Application Name field, and click Next. The default application name is set to OUD-DSML.war.

9. On the Map modules to servers page, verify that the Oracle Unified Directory application mapping is set to the appropriate cluster/server and click Next.

   The Provide options to compile JSPs page is displayed.

10. Make the following changes and click Next:

    1. Select Web Module Oracle Unified Directory.

    2. Change JDK Source Level to 15.

11. On the Provide JSP reloading options for Web Modules page keep the default configuration.

12. On the Map shared libraries page, verify your settings and click Next.

    On the Map shared library relationships page, verify your settings and click Next.

    On the Map virtual hosts for Web modules page, verify that the Oracle Unified Directory application mapping is set to the appropriate virtual host and click Next.

13. On the Map context roots for Web modules page, provide context root /DSML and click Next.

14. Choose Applications > Application Types > WebSphere Enterprise Applications > OUD-DSML_war > Manage Modules, and do the following:

    1. Verify that the cluster/server mapping is correct.

    2. Select OUD-DSML.war > Class loader order.

    3. Under Class loader order, select Class loaded with local class loader first (parent last), and save your changes.

       Note:

       When running two or more applications in the same cell, it is important that you configure the application server such that the application class loader can override the parent and provide its own version of a class. For WebSphere, choose Class loaded with local class loader first (parent last), as documented above.

15. Restart IBM WebSphere.

14.5.2 Confirming the DSML Gateway Deployment

After the DSML gateway has been deployed and configured, you can communicate with it by using any DSMLv2 client. The following sections describe two ways to accomplish this:

• Section 14.5.2.1, "To Confirm the DSML Gateway Deployment with JXplorer"

• Section 14.5.2.2, "Confirming the DSML Gateway Deployment with the Directory Server Resource Kit"

14.5.2.1 To Confirm the DSML Gateway Deployment with JXplorer

The JXplorer tool is a Java-based LDAP browser that can be used to browse, search, and edit the contents of an Oracle Unified Directory instance. This tool can communicate using both LDAP and DSML. Although JXplorer's DSML support does not allow authentication (and therefore is restricted to the set of operations available to anonymous users), it is still possible to use it to verify that the DSML gateway is functioning as expected.

You can download JXplorer, and the accompanying documentation, at jxplorer.org.

To confirm a DSML gateway by using JXplorer, follow these steps:

1. Start JXplorer and chose the Connect option from the File menu.

   The Open LDAP/DSML Connection window opens with fields for connection information. The following figure shows typical entries.

   
   Description of the illustration jxplorer-dsml-settings.png
   
   

2. Enter the address and port number of the Web application on which the DSML gateway is running.

3. Choose DSMLv2 from the Protocol list.

4. Specify the path to the DSMLServlet in the DSML Service field.

5. Provide an appropriate base DN value for your directory.

6. Click OK to connect the directory server and display a JXplorer window where you can search and browse the tree (with the limitations imposed for anonymous users).

   
   Description of the illustration jxplorer-dsml-browse.png
   
   

14.5.2.2 Confirming the DSML Gateway Deployment with the Directory Server Resource Kit

The Directory Server Resource Kit (DSRK) is a collection of utilities that can be used in conjunction with directory servers. The DSRK was originally intended for use with Oracle Directory Server Enterprise Edition, but in most cases the applications also work with Oracle Unified Directory. The most recent version of the DSRK is included as part of Oracle Directory Server Enterprise Edition 11g Release 1 PS1 (11.1.1.7.0), and contains the dsmlsearch and dsmlmodify tools that can interact with a directory server using DSML rather than LDAP.

Note that even though an older version of these DSML tools was provided with earlier versions of the Directory Server Resource Kit, the version provided with Oracle Directory Server Enterprise Edition 11g Release 1 PS1 (11.1.1.7.0) is strongly recommended because it is easier to use. You can download Oracle Directory Server Enterprise Edition 11g Release 1 PS1 (11.1.1.7.0) from Oracle Technology Network (OTN) here:

http://www.oracle.com/technetwork/middleware/downloads/oid-11g-161194.html

14.5.2.2.1 Using the dsmlsearch Command

The dsmlsearch command is a DSML-based counterpart to the ldapsearch command. dsmlsearch operates in a similar manner to ldapsearch but there are certain key differences. To see usage information, invoke the command with no arguments, as in the following example:

$ ./dsmlsearch
usage: dsmlsearch -h http://host:port -b basedn [options] filter [attributes...]
where:
-h hostURL URL of the directory server
-b basedn  base dn for search
-D binddn  bind dn
-w passwd  bind password (for simple HTTP authentication)
use "-w - " to prompt for a password
-j pwfile  file where password is stored
-s scope   specify the scope of the search
baseObject - For searching only the base entry
singleLevel - For searching only the children
wholeSubtree - For searching the base entry and all childrens
-a deref   specify how aliases are deferenced
neverDerefAliases - Aliases are never dereferenced
derefFindingBaseObj - Dereferenced when finding the base DN
derefAlways - Dereferenced when finding below the base DN
-l seconds specify the maximum number of seconds to wait for the search
-z number  specify the maximum number of entries to return for the search
-f file    specify the name of the file containing the search filter

The dsmlsearch command differs in usage from ldapsearch:

• The -h argument is used to provide a URL to use to access the server. It should include the host and port number, as well as the URI for the gateway servlet (for example, http://127.0.0.1:8080/dsml/DSMLServlet).

• The -b argument is used to specify the search scope, but note that the values you provide are different (baseObjectinstead of base, singleLevelinstead of one, and wholeSubtreeinstead of sub).

• The results are output in DSML format, which is not as user-friendly or human-readable as the LDIF output provided by ldapsearch.

An example usage of this tool is as follows. Note that the DSML output does not contain any line breaks, but line breaks are added here for readability.

$ ./dsmlsearch -h http://127.0.0.1:8080/dsml/DSMLServlet \-b "dc=example,dc=com" -s baseObject \"(objectClass=*)"
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body><dsml:batchResponse xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">
<dsml:searchResponse><dsml:searchResultEntry dn="dc=example,dc=com"><dsml:attr
name="objectClass"><dsml:value>domain</dsml:value><dsml:value>top</dsml:value>
</dsml:attr><dsml:attr name="dc"><dsml:value>example</dsml:value></dsml:attr>
</dsml:searchResultEntry><dsml:searchResultDone><dsml:resultCode code="0"/>
</dsml:searchResultDone></dsml:searchResponse></dsml:batchResponse>
</SOAP-ENV:Body></SOAP-ENV:Envelope>

14.5.2.2.2 Using the dsmlmodify Utility

dsmlmodify utility is a DSML-based counterpart to the ldapmodify command, and it can perform add, delete, modify, and modify DN operations over DSML. To see the usage information for this tool, run it with no arguments, as shown in this example:

$ ./dsmlmodify
usage: dsmlmodify -h http://host:port [options] -f file
where:
-h hostURL URL of the directory server
-D binddn  bind dn
-w passwd  bind password (for simple HTTP authentication)
use "-w - " to prompt for a password
-j pwfile  file where password is stored
-f file    specify the name of the file containing
the modifications

As with the dsmlsearch utility, the -h argument specifies a URL, and the output is returned in DSML form. Unlike ldapmodify, the dsmlmodify tool does not accept the changes through standard input. Changes must be specified in a file, and that file must be in DSML format instead of than LDIF, and the changes cannot contain an outer batchRequest wrapper. The following example shows a typical input file.

<addRequest dn="uid=test.user,dc=example,dc=com">
<attr name="objectClass">
<value>top</value>
<value>person</value>
<value>organizationalPerson</value>
<value>inetOrgPerson</value>
</attr>
<attr name="uid">
<value>test.user</value>
</attr>
<attr name="givenName">
<value>Test</value>
</attr>
<attr name="sn">
<value>User</value>
</attr>
<attr name="cn">
<value>Test User</value>
</attr>
<attr name="userPassword">
<value>password</value>
</attr>
</addRequest>
<modifyRequest dn="uid=test.user,dc=example,dc=com">
<modification name="description" operation="replace">
<value>This is the new description</value>
</modification>
</modifyRequest>
<modDNRequest dn="uid=test.user,dc=example,dc=com" newrdn="cn=Test User" 
 deleteoldrdn="false" newSuperior="ou=People,dc=example,dc=com" />
<delRequest dn="cn=Test User,ou=People,dc=example,dc=com" />

The following example shows the output from applying these changes. Line breaks have been added to the output to make it more readable:

$ dsmlmodify -h http://127.0.0.1:8080/dsml/DSMLServlet \  -D "cn=Directory Manager" -j pwd-file -f /tmp/test.dsml
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body><dsml:batchResponse xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">
<dsml:addResponse><dsml:resultCode code="0"/></dsml:addResponse>
<dsml:modifyResponse><dsml:resultCode code="0"/></dsml:modifyResponse>
<dsml:modDNResponse><dsml:resultCode code="0"/></dsml:modDNResponse>
<dsml:delResponse><dsml:resultCode code="0"/><dsml:errorMessage>The number of
entries deleted was 1</dsml:errorMessage></dsml:delResponse></dsml:batchResponse>
</SOAP-ENV:Body></SOAP-ENV:Envelope>

$ dsmlmodify -h http://localhost:8080/dsml/DSMLServlet \  -D "cn=directory manager" -j pwd-file -f /tmp/dsml.ldif
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body><batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">
<addResponse><resultCode code="0"/></addResponse>
<modifyResponse><resultCode code="0"/></modifyResponse>
<modDNResponse><resultCode code="0"/></modDNResponse>
<delResponse><resultCode code="0"/></delResponse></batchResponse>
</SOAP-ENV:Body></SOAP-ENV:Envelope>