JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Fusion Middleware Administration Guide for Oracle Unified Directory 11g Release 1 (11.1.1)
search filter icon
search icon

Document Information


1.  Starting and Stopping the Server

2.  Configuring the Server Instance

Managing the Server Configuration With dsconfig

Overview of the dsconfig Command

dsconfig and Certificate Checking

dsconfig Sub-Commands

dsconfig Advanced Properties

Using dsconfig in Interactive Mode

Getting Help With dsconfig

Global Usage

Finding the Correct Subcommand

Getting Help for an Individual Subcommand

Displaying a Summary of a Component's Properties

Displaying Detailed Help on a Property

Configuring a Server Instance With dsconfig

To Display the Properties of a Component

To List Components

To Create a Component

To Modify the Properties of a Component

To Modify the Values of a Multi-Valued Property

To Delete a Component

To Use dsconfig in Batch Mode

Configuring the Connection Handlers With dsconfig

To Display All Connection Handlers

Configuring the LDAP Connection Handler

Configuring the LDIF Connection Handler

Configuring the JMX Connection Handler

Configuring Network Groups With dsconfig

Creating a Network Group

Modifying Network Group Properties

Setting an Allowed or Denied Client List

Creating a Network Group Quality of Service Policy

Creating a Request Filtering Policy

Creating a Network Group Resource Limit

Creating an Affinity Quality of Service Policy

Creating a Referral Quality of Service Policy

To Modify a Network Group Quality of Service Policy

Configuring Workflows With dsconfig

Listing Existing Workflows

Viewing Workflow Properties

Creating a Workflow

Configuring Workflow Elements With dsconfig

Listing Workflow Elements

Creating Workflow Elements

Modifying Workflow Elements

Configuring Plug-Ins With dsconfig

Overview of Plug-In Types

Modifying the Plug-In Configuration

Managing the Server Configuration With Oracle Directory Services Manager

Select a Configuration View

Display Suffix Properties

Modify a Network Group

Modify a Workflow Element

Modify the General Server Configuration

Modify a Connection Handler

Modify Logger Properties

Modify Log Rotation Policies

Modify Log Retention Policies

Configure Alerts

Managing Administration Traffic to the Server

Accessing Administrative Suffixes

To Configure the Administration Connector

Configuring Commands As Tasks

Commands That Can Schedule Tasks

Controlling Which Tasks Can Be Run

Scheduling and Configuring Tasks

To Schedule a Task

To Schedule a Recurring Task

To Configure Task Notification

To Configure Task Dependencies

Managing and Monitoring Scheduled Tasks

To Obtain Information About Scheduled Tasks

To Cancel a Scheduled Task

To Cancel a Recurring Task

Deploying and Configuring the DSML Gateway

Deploying the DSML Gateway

Deploying the DSML Gateway in Oracle WebLogic Server

Configuring WebLogic Server for the DSML Gateway

Deploying the DSML Gateway WAR File

Confirming the DSML Gateway Deployment

To Confirm the DSML Gateway Deployment with JXplorer

Confirming the DSML Gateway Deployment with the Directory Server Resource Kit

Using the dsmlsearch Command

Using the dsmlmodify Utility

3.  Configuring the Proxy Components

4.  Configuring Security Between Clients and Servers

5.  Configuring Security Between the Proxy and the Data Source

6.  Managing Oracle Unified Directory With Oracle Directory Services Manager

7.  Managing Directory Data

8.  Replicating Directory Data

9.  Controlling Access To Data

10.  Managing Users and Groups With dsconfig

11.  Managing Password Policies

12.  Managing Directory Schema

13.  Monitoring Oracle Unified Directory

14.  Tuning Performance

15.  Advanced Administration

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 1 (11.1.1) 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.

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.

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/oracle_common/common/bin/
  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:


    For more information, see

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

    For example:

    $ OUD-Base-Location-Home/user_projects/domains/base_domain/bin/
  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 ../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 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 previous procedure.

  5. Follow the WebLogic Server Documentation to install a web application (

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

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:

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.

  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.

    Figure shows the Open LDAP/DSML Connection window.
  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 the OK button 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).
    Figure shows the JXplorer window populated with values from a sample directory.
Confirming the DSML Gateway Deployment with the Directory Server Resource Kit

The Directory Server Resource Kit (DSRK) is a collection of utilities that may be used in conjunction with directory servers. It is originally intended for use with Oracle Directory Server Enterprise Editionr, but in most cases the applications also work with Oracle Unified Directory. The most recent version of the DSRK is included as part of DSEE 6.0, and it contains 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 DSEE 6 is strongly recommended because it is easier to use.

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...]
-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:

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 \ -b "dc=example,dc=com" -s baseObject \"(objectClass=*)"
<SOAP-ENV:Envelope xmlns:SOAP-ENV="">
<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
</dsml:attr><dsml:attr name="dc"><dsml:value>example</dsml:value></dsml:attr>
</dsml:searchResultEntry><dsml:searchResultDone><dsml:resultCode code="0"/>
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
-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">
<attr name="uid">
<attr name="givenName">
<attr name="sn">
<attr name="cn">
<value>Test User</value>
<attr name="userPassword">
<modifyRequest dn="uid=test.user,dc=example,dc=com">
<modification name="description" operation="replace">
<value>This is the new description</value>
<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 \ -D "cn=Directory Manager" -w password -f /tmp/test.dsml
<SOAP-ENV:Envelope xmlns:SOAP-ENV="">
<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>
$ dsmlmodify -h http://localhost:8080/dsml/DSMLServlet \ -D "cn=directory manager" -w password -f /tmp/dsml.ldif
<SOAP-ENV:Envelope xmlns:SOAP-ENV="">
<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>