DSEE 7 Cheat Sheet

This is a short (recently updated) list of commands commonly used in administering DSEE 7 (Oracle Directory Server Enterprise Edition version 7).

Note: The links to Sun (now Oracle) documentation cited below are subject to change at the whim of the vendor, so please don’t be upset with me if they wind up dead-ending at some point. Right now you should find it here.

Here are the commands to get help on the two major utilities described below:

dsadm --help
dsconf help-properties

You can grep major subject areas (e.g. SER, for SERver, SUF, for SUFfix) to narrow down the results.

The examples that follow assume a zip install of the software to a directory on the filesystem like /opt/sun/dsee7, to which the $DSHOME variable is mapped. The host in the examples is ldap1.example.com. All this and more is found in the Administration Guide.

dsadm create -u dsadmin -g dsadmin-p 389 -P 636 $DSHOME/slapd-ldap1

This will create an instance of the directory server. The example specifies a user and group for the server to run as and the traditional listening ports for LDAP and LDAPS. It will prompt to set the cn=directory manager password.

dsadm start $DSHOME/slapd-ldap1

Starts the directory server instance. If the server listens on port 389/636 it has to be run as root on Unix systems.

dsconf create-suffix -h localhost -p 389 dc=example,dc=com

Sets up a naming context and creates the corresponding embedded database. This will prompt to accept a security cert and for the directory manager password.

dsadm stop $DSHOME/slapd-ldap1

Stops the directory instance.

dsadm import $DSHOME/slapd-ldap1 $DSHOME/prod.ldif dc=example,dc=com

Use this to initialize the suffix with new data contained in an LDIF file (here, $DSHOME/prod.ldif). Must be run with the directory off-line.

dsconf import -h localhost -p 389 $DSHOME/prod.ldif dc=example,dc=com

This is an alternate command to do the same thing as the last command, except that it can be run with the directory on-line.

dsconf export -h localhost -p 389 dc=example,dc=com $DSHOME/backup.ldif

Exports the data in the dc=example,dc=com suffix to an LDIF file named $DSHOME/backup.ldif.

dsadm export $DSHOME/slapd-ldap1 dc=example,dc=com $DSHOME/backup.ldif

This creates an off line backup (the command has to be run with the directory service down). Very useful in migrating data from one directory to another.

dsconf create-index -h localhost -p 389 'dc=example,dc=com' displayName

Indexing is a 2 or 3 step process, depending. Use this command to queue’s an index creation task for the displayName attribute. By default this will be of type presence (pres) and equality (eq) only.

dsconf set-index-prop -h localhost -p 389 'dc=example,dc=com' displayName sub-enabled:on

Modifies the index creation task to add a substring (sub) index for the displayName attribute.

dsconf reindex -a -h localhost -p 389 -t displayName 'dc=example,dc=com'

This is the command that actually creates the displayName indexes using the task set up by the previous two.

Some global options that apply to most commands that make executing them under cron a bit easier:

1. Specify the “-e” global option to tell the utility to use an unsecured channel, and the “-i” to suppress confirmations; and

2. Either use the “-w” option, or the $LDAP_ADMIN_PWF environment variable, to set a path that contains a file with the directory manager password in clear text.

Most basic settings, like the limits on the number of entries returned in a search, continue to be configurable over LDAP (by modifying attribute values found under the DSE root or “cn=config”) or by editing the dse.ldif file found in the instance config folder (e.g. $DSHOME/slapd-ldap1/config/dse.ldif). There is now a third method that is effective as well for many settings that previously could not be modified by either of the former. The new method involves a multitude of options using the dsconf command. The best way to learn about these is to browse through the Man Page Reference section on dsconf linked above, read in conjunction with the large section on Directory Server Configuration.

Four modifications I make on every directory I deploy is to:

1. Set the allidsthreshold much higher than the default of 4000 entries, usually 10000 or more entries;

2. Set the look through limit to unlimited (in earlier directory server versions you set the value to “-1”);

3. Increase the search size limit above the default of 2000 (again, usually 10000 entries);

4. Decrease the time limit below way too high default of 3600 seconds (say 900 seconds — 5 minutes).

To increase the allidsthreshold:

dsconf set-server-prop -h localhost -p 389 all-ids-threshold:10000

(if this change is successful, the system will prompt to remind you to reindex the directory database using the command:

dconf reindex -h localhost -p 389 'dc=example,dc=com'

To set the look through limit to unlimited:

dsconf set-server-prop -h localhost -p 389 look-through-limit:unlimited

To increase the search size limit:

dsconf set-server-prop -h localhost -p 389 search-size-limit:10000

To decrease the search time limit:

dsconf set-server-prop -h localhost -p 389 search-time-limit:900

One optional feature I almost always enable, even in an environment that isn’t going to be replicated, is the Retro Change Log Plug-in, which publishes the directory server Change Log at “cn=changelog”. This comes in handy for auditing and is also required by a number of applications that integrate with the directory (like Oracle’s Identity Manager product). While turning on the Audit Log will provide the same data as publishing the Change Log, audit logs have to be accessed on the file system of the server machine. By contrast, the “cn=changelog” directory suffix can be searched over LDAP from a remote host like any other part of the directory.

To turn on the Audit Log:

dsconf set-log-prop -h localhost -p 389 audit enabled:on

To enable the Retro Change Log Plug-in:

dsconf set-server-prop -h localhost -p 389 retro-cl-enabled:on

To rotate the changelog every 7 days:

dsconf set-server-prop -h localhost -p 389 repl-cl-max-age:7d

To see whether schema checking is turned on:

dsconf get-server-prop -h localhost -p 389 check-schema-enabled

To turn off schema checking:

dsconf set-server-prop -h localhost -p 389 check-schema-enabled:off

To turn on schema checking:

dsconf set-server-prop -h localhost -p 389 check-schema-enabled:on

See my later article on Managing replication agreements in DSEE7 for more.

Note: To make things a bit more convenient where your system account is a non-root user and the directory is running on port 389, you might want to give that user sudo rights to start the directory. Here are the lines you’d add to /etc/sudoers in the appropriate places (use visudo to edit the file to take advantage of its syntax-checking):

User_Alias DSGRP = dsadmin,myuser
	
Cmnd_Alias DSCMDS = /opt/sun/dsee7/bin/dsadm
	
DSGRP ALL = DSCMDS

Once this is done your system user (ldapcon in the example) will be able to do a “sudo dsadm start $DSHOME/slapd-ldap1 and won’t get an ugly error message (notice I’m not suppressing sudo’s prompting for a password, because I consider that default behavior A Good Thing [TM]).

To reset the Directory Manager password:

There are two ways to do this. The first, preferred one, is to use the command line tools.

Using dsconf:

1. Create a text file with the new password (e.g. newpwd.txt in your system user’s $HOME).

2. Run the following command:

dsconf set-server-prop -h localhost -p 389 root-pwd-file:$HOME/newpwd.txt

Remember to delete the newpwd.txt file once done.

Edit dse.ldif:

1. Generate a SSHA password hash using slappasswd.

[a01008@usmlrs425 ~]$ /usr/sbin/slappasswd -h {SSHA}
New password:
Re-enter new password:
{SSHA}rUIqZkmvF1n38dVzTM8kyP7248S2J7Sv

2. Edit dse.ldif (found under $DSHOME/slapd-ldap1/config) and replace the existing password hash with the new one.

nsslapd-rootpw: {SSHA}rUIqZkmvF1n38dVzTM8kyP7248S2J7Sv