OpenDJ Control Panel offers a graphical user interface for managing both local and remote servers. You choose the server to manage when you start the Control Panel. The Control Panel connects to the administration server port, making a secure LDAPS connection.

When you login to OpenDJ Control Panel, you authenticate over LDAP. This means that if users can run the Control Panel, they can use it to manage a running server. Yet, to start and stop the server process through OpenDJ Control Panel, you must start the Control Panel on the system where OpenDJ runs, as the user who owns the OpenDJ server files (such as the user who installed OpenDJ). In other words, the OpenDJ Control Panel does not do remote process management.

OpenDJ Control Panel displays key information about the server.

All OpenDJ command-line tools take the --help option.

All commands call Java programs and therefore involve starting a JVM.

The following list uses the UNIX names for the tools. On Windows all command-line tools have the extension .bat.

By default OpenDJ saves a compressed version of the server configuration used on successful startup. This ensures that the server provides a "last known good" configuration, which can be used as a reference or copied into the active configuration if the server fails to start with the current active configuration. It is possible, though not usually recommended, to turn this behavior off by changing the global server setting save-config-on-successful-startup to false.

OpenDJ tends to show resilience when restarting after a crash or after the server process is killed abruptly. OpenDJ might have to replay the last few entries in a transaction log. Generally OpenDJ returns to service quickly.

You can find Berkeley Java Edition database recovery messages in the database log file, such as /path/to/opendj/db/userRoot/je.info.0. The following shows two example messages from that log, the first written at the beginning of the recovery process, the second written at the end of the process.

111104 10:23:48:967 CONFIG [/path/to/opendj/db/userRoot]Recovery
 underway, found end of log
...
111104 10:23:49:015 CONFIG [/path/to/opendj/db/userRoot]Recovery finished:
 Recovery Info ...

What can take some time during server startup is preloading database content into memory when the server starts. Objects cached in memory do not survive a crash. By default, OpenDJ does not cache objects in memory before starting to accept client requests. You can however set a preload-time-limit for the database cache of your backend if you do want to load objects into the database cache before OpenDJ begins accepting client connections.

When you install OpenDJ, you have the option of importing sample data generated during the installation. This procedure demonstrates how to generate LDIF using the make-ldif command.

You can use the OpenDJ Control Panel to import data (Directory Data > Import LDIF...) and to export data (Directory Data > Export LDIF...). The following procedures demonstrate how to use the import-ldif and export-ldif commands.

This section demonstrates the ldifsearch, ldifmodify, and ldif-diff tools.

$ ldifsearch
 --baseDN dc=example,dc=org
 --ldifFile generated.ldif
 "(sn=Grenier)"
 mobile
dn: uid=user.4630,ou=People,dc=example,dc=org
mobile: +1 728 983 6669

$ cat changes.ldif 
dn: uid=user.0,ou=People,dc=example,dc=org
changetype: modify
replace: description
description: This is the new description for Aaccf Amar.
-
replace: initials
initials: AAA

$ ldifmodify
 --sourceLDIF generated.ldif
 --changesLDIF changes.ldif
 --targetLDIF new.ldif

$ ldif-diff --sourceLDIF old.ldif --targetLDIF new.ldif
dn: uid=user.0,ou=People,dc=example,dc=org
changetype: modify
add: initials
initials: AAA
-
delete: initials
initials: ASA
-
add: description
description: This is the new description for Aaccf Amar.
-
delete: description
description: This is the description for Aaccf Amar.

OpenDJ stores your data in a backend. OpenDJ stores directory data in backends. Backends are what you backup and restore. By default, OpenDJ stores your data in a backend named userRoot. You can create new backends using the dsconfig command. The following example creates a local backend named testData.

$ dsconfig create-backend --backend-name testData --type local-db


>>>> Configuring the "base-dn" property

    Specifies the base DN(s) for the data that the backend handles.

    A single backend may be responsible for one or more base DNs. Note that no
    two backends may have the same base DN although one backend may have a
    base DN that is below a base DN provided by another backend (similar to
    the use of sub-suffixes in the Sun Java System Directory Server). 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.

    Syntax:  DN

Enter a value for the "base-dn" property: dc=example,dc=org

Enter another value for the "base-dn" property [continue]: 


>>>> Configuring the "enabled" property

    Indicates whether the backend is enabled in the server.

    If a backend is not enabled, then its contents are not accessible when
    processing operations.

Select a value for the "enabled" property:

    1)  true
    2)  false

    ?)  help
    q)  quit

Enter choice: 1


>>>> Configure the properties of the Local DB Backend

        Property           Value(s)
        --------------------------------------
    1)  backend-id         testData
    2)  base-dn            "dc=example,dc=org"
    3)  compact-encoding   true
    4)  db-cache-percent   10
    5)  db-cache-size      0 b
    6)  db-directory       db
    7)  enabled            true
    8)  index-entry-limit  4000
    9)  writability-mode   enabled

    ?)  help
    f)  finish - create the new Local DB Backend
    q)  quit

Enter choice [f]: 

The Local DB Backend was created successfully

Alternatively, you can create a new backend in OpenDJ Control Panel (Directory Data > New Base DN... > Backend > New Backend: backend-name).

You delete a database backend by using the dsconfig delete-backend command.

When you delete a database backend by using the dsconfig delete-backend command, OpenDJ does not actually remove the database files for two reasons. First, a mistake could potentially cause lots of data to be lost. Second, deleting a large database backend could cause severe service degradation due to a sudden increase in I/O load.

Instead, after you run the dsconfig delete-backend command you must also manually remove the database backend files.

If you do run the dsconfig delete-backend command by mistake and have not yet deleted the actual files, then you can recover from the mistake by creating the backend again, reconfiguring the indexes that were removed, and rebuilding the indexes as described in the section on Configuring & Rebuilding Indexes.

You configure LDAP client access by using the command-line tool dsconfig. By default you configure OpenDJ to listen for LDAP when you install.

The standard port number for LDAP client access is 389. If you install OpenDJ directory server as a user who can use port 389 and the port is not yet in use, then 389 is the default port number presented at installation time. If you install as a user who cannot use a port < 1024, then the default port number presented at installation time is 1389.

One common way to protect connections between OpenDJ and client applications involves using StartTLS for LDAP or LDAPS to secure connections. OpenDJ and client applications use X.509 digital certificates to set up secure connections.

Both OpenDJ and client applications check that certificates are signed by a trusted party before accepting them. Merely setting up a secure connection therefore involves a sort of authentication using certificates. If either OpenDJ or the client application cannot trust the peer certificate, then the attempt to set up a secure connection must fail.

By default OpenDJ client tools prompt you if they do not recognize the server certificate. Other clients might not prompt you. OpenDJ server has no one to prompt when a client presents a certificate that cannot be trusted, so it must simply refuse to set up the connection.^[1] In other words, it is important for both OpenDJ and client applications to be able to verify that peer certificates exchanged have been signed by a trusted party.

In practice this means that both OpenDJ and client applications must put the certificates that were used to sign each others' certificates in their respective trust stores. Conventionally, certificates are therefore signed by a Certificate Authority (CA). A CA is trusted to sign other certificates. The Java runtime environment for example comes with a trust store holding certificates from many well-known CAs.^[2] If your client uses a valid certificate signed by one of these CAs, then OpenDJ can verify the certificate without additional configuration, because OpenDJ can find the CA certificate in the Java CA certificate trust store. Likewise if you set up StartTLS or LDAPS in OpenDJ using a valid certificate signed by one of these CAs, then many client applications can verify the OpenDJ server certificate without further configuration.

In summary, if you need a certificate to be recognized automatically, get the certificate signed by a well-known CA.

You can, however, choose to have your certificates signed some other way. You can set up your own CA. You can use a CA whose signing certificate is not widely distributed. You can also use self-signed certificates. In each case, you must add the signing certificates into the trust store of each peer making secure connections.

For OpenDJ directory server, you can choose to import your own CA-signed certificate as part of the installation process, or later using command-line tools. Alternatively, you can let the OpenDJ installation program create a self-signed certificate as part of the OpenDJ installation process. In addition, you can add a signing certificate to the OpenDJ trust store using the Java keytool command.

The following example shows the keytool command to add a client application's binary format, self-signed certificate to the OpenDJ trust store (assuming OpenDJ is already configured to use secure connections). This enables OpenDJ to recognize the self-signed client application certificate. (By definition a self-signed certificate is itself the signing certificate. Notice that the Owner and the Issuer are the same.)

$ keytool
 -import
 -alias myapp-cert
 -file myapp-cert.crt
 -keystore /path/to/opendj/config/truststore
 -storepass `cat /path/to/opendj/config/keystore.pin`
Owner: CN=My App, OU=Apps, DC=example, DC=com
Issuer: CN=My App, OU=Apps, DC=example, DC=com
Serial number: 5ae2277
Valid from: Fri Jan 18 18:27:09 CET 2013 until: Thu Jan 13 18:27:09 CET 2033
Certificate fingerprints:
	 MD5:  48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37
	 SHA1: F9:61:54:37:AA:C1:BC:92:45:07:64:4B:23:6C:BC:C9:CD:1D:44:0F
	 SHA256: 2D:B1:58:CD:33:40:E9:ED:...:EA:C9:FF:6A:19:93:FE:E4:84:E3
	 Signature algorithm name: SHA256withRSA
	 Version: 3

Extensions:

#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 54 C0 C5 9C 73 37 85 4B   F2 3B D3 37 FD 45 0A AB  T...s7.K.;.7.E..
0010: C9 6B 32 95                                        .k2.
]
]

Trust this certificate? [no]:  yes
Certificate was added to keystore

When working with a certificate in printable encoding format (.pem) rather than binary format, use the -rfc option, too.

Restart OpenDJ after adding certificates to the trust store to make sure that OpenDJ reads the updated trust store file.

On the client side, if your applications are also Java applications, then you can also import the OpenDJ signing certificate into the trust store for the applications using the keytool command.

The following example shows the keytool command to export the OpenDJ self-signed certificate in binary format.

$ keytool
 -export
 -alias server-cert
 -file server-cert.crt
 -keystore /path/to/opendj/config/keystore
 -storepass `cat /path/to/opendj/config/keystore.pin`
Certificate stored in file <server-cert.crt>

Importing the server certificate is similar to importing the client certificate, as shown above.

The following sections describe how to get and install certificates for OpenDJ directory server on the command line, for use when setting up StartTLS or LDAPS.

StartTLS (Transport Layer Security) negotiations start on the unsecure LDAP port, and then protect communication with the client. You can opt to configure StartTLS during installation, or later using the dsconfig command.

You configure LDAPS (LDAP/SSL) client access by using the command-line tool dsconfig. You can opt to configure LDAPS access when you install.

The standard port number for LDAPS client access is 636. If you install OpenDJ directory server as a user who can use port 636 and the port is not yet in use, then 636 is the default port number presented at installation time. If you install as a user who cannot use a port < 1024, then the default port number presented at installation time is 1636.

Using the OpenDJ directory server global configuration properties, you can add global restrictions on how clients access the server. These settings are per server, and so much be set independently on each server in replication topology.

These global settings are fairly coarse-grained. For a full discussion of the rich set of administrative privileges and fine-grained access control instructions that OpenDJ supports, see the chapter on Configuring Privileges & Access Control.

By default OpenDJ supports the SSL and TLS protocols and the cipher suites supported by the underlying Java virtual machine. For details see the documentation for the Java virtual machine in which you run OpenDJ. For Oracle Java, see the Java Cryptography Architecture Oracle Providers Documentation for the The SunJSSE Provider.

To list the available protocols and cipher suites, read the supportedTLSProtocols and supportedTLSCiphers attributes of the root DSE. Install unlimited strength Java cryptography extensions for stronger ciphers.

$ ldapsearch --port 1389 --baseDN "" --searchScope base "(objectclass=*)"
 supportedTLSCiphers supportedTLSProtocols
dn:
supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA
supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
supportedTLSCiphers: TLS_ECDHE_RSA_WITH_RC4_128_SHA
supportedTLSCiphers: SSL_RSA_WITH_RC4_128_SHA
supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_RC4_128_SHA
supportedTLSCiphers: TLS_ECDH_RSA_WITH_RC4_128_SHA
supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: SSL_RSA_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
supportedTLSCiphers: SSL_RSA_WITH_RC4_128_MD5
supportedTLSCiphers: TLS_EMPTY_RENEGOTIATION_INFO_SCSV
supportedTLSProtocols: SSLv2Hello
supportedTLSProtocols: SSLv3
supportedTLSProtocols: TLSv1
supportedTLSProtocols: TLSv1.1
supportedTLSProtocols: TLSv1.2

You can restrict the list of protocols and cipher suites used by setting the ssl-protocol and ssl-cipher-suite connection handler properties to include only the protocols or cipher suites you want.

For example, to restrict the cipher suites to TLS_EMPTY_RENEGOTIATION_INFO_SCSV and TLS_RSA_WITH_AES_256_CBC_SHA use the dsconfig set-connection-handler-prop command as shown in the following example.

$ dsconfig
   set-connection-handler-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name "LDAPS Connection Handler"
 --add ssl-cipher-suite:TLS_EMPTY_RENEGOTIATION_INFO_SCSV
 --add ssl-cipher-suite:TLS_RSA_WITH_AES_256_CBC_SHA
 --no-prompt
 --trustAll

Directory Services Markup Language (DSML) client access is implemented as a servlet that runs in a web application container.

You configure DSML client access by editing the WEB-INF/web.xml after you deploy the web application. In particular, you must at least set the ldap.host and ldap.port parameters if they differ from the default values, which are localhost and 389.

The DSML servlet translates between DSML and LDAP, and passes requests to the directory server. For initial testing purposes, you might try JXplorer, where DSML Service: /webapp-dir/DSMLServlet. Here, webapp-dir refers to the name of the directory in which you unpacked the DSML .war file.

JXplorer accessing OpenDJ through DSML

You configure Java Management Extensions (JMX) client access by using the command-line tool, dsconfig.

The LDIF connection handler lets you make changes to directory data by placing LDIF in a file system directory that OpenDJ server regularly polls for changes. The LDIF, once consumed, is deleted.

You configure LDIF file access by using the command-line tool dsconfig.

For instructions on setting up the SNMP Connection Handler, see the section, SNMP-Based Monitoring.

OpenDJ directory server access control instructions (ACIs) exist as operational aci attribute values on directory entries, and as global ACIs stored in the configuration. ACIs apply to a scope defined in the instruction, and set permissions that depend on what operation is requested, who requested the operation, and how the client connected to the server.

For example, the ACIs on the following entry allow anonymous read access to all attributes except passwords, and allow read-write access for directory administrators under dc=example,dc=com.

dn: dc=example,dc=com
objectClass: domain
objectClass: top
dc: example
aci: (target ="ldap:///dc=example,dc=com")(targetattr !=
 "userPassword")(version 3.0;acl "Anonymous read-search access";
 allow (read, search, compare)(userdn = "ldap:///anyone");)
aci: (target="ldap:///dc=example,dc=com") (targetattr =
 "*")(version 3.0; acl "allow all Admin group"; allow(all) groupdn =
 "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)
  

OpenDJ directory server's default behavior is that no access is allowed unless it is specifically granted by an access control instruction. In addition privileges assigned to certain users such as cn=Directory Manager allow them to bypass access control checks.

OpenDJ directory server provides several global ACIs out of the box to facilitate evaluation while maintaining a reasonable security policy. By default users are allow to read the root DSE, to read the schema, to use certain controls and extended operations, to modify their own entries, to bind, and so forth. Global ACIs are defined on the access control handler, and apply to the entire directory server. You must adjust the default global ACIs to match the security policies for your organization, for example to restrict anonymous access.

ACI attribute values use a specific language described in this section. Although ACI attribute values can become difficult to read in LDIF, the basic syntax is simple.

targets(version 3.0;acl "name";permissions subjects;)

The following list briefly explains the variables in the syntax above.

Separate multiple pairs of permissions subjects definitions with semicolons, ;. When you specify multiple permissions-subjects pairs, at least one must match (OR).

allow(action[, action …])

deny(action[, action …])

Privileges provide access control for server administration independently from access control instructions.

Directory root users, such as cn=Directory Manager, are granted privileges in the following list and marked with an asterisk (*) by default. Other administrator users can be assigned privileges, too.

* = default directory root user privileges

For root directory administrators, by default cn=Directory Manager, you configure privileges using the dsconfig command.

For non-root directory administrators, you add privileges with the ldapmodify command.

Access control instructions are defined in the data, as values for aci attributes. They can be imported in LDIF. They can be modified over LDAP. Yet in order to make changes to ACIs users first need the modify-acl privilege described previously. By default, only the root DN user has the modify-acl privilege.

Global ACIs on cn=Access Control Handler,cn=config can be set using the dsconfig command. Global ACIs have attribute type ds-cfg-global-aci. Modify global ACIs from the Access Control Handler menu in dsconfig.

Users with write access to add ACIs and with the modify-acl privilege can use the ldapmodify command to change ACIs located in user data.

This section therefore focuses on ACI examples, rather than demonstrating how to update the directory for each example. To update ACIs, either change them using the ldapmodify command, or using OpenDJ Control Panel.

If you use OpenDJ Control Panel, find the entry to modify in the Manage Entries window. Then try View > LDIF View to edit the entry. Control Panel checks your syntax and lets you know if you made an error before it saves any changes.

For hints on updating directory entries with ldapmodify, see the section on Modifying Entry Attributes, keeping in mind that the name of the ACI attribute is aci as shown in the examples that follow.

aci: (target ="ldap:///dc=example,dc=com")(targetattr !=
 "authPassword || userPassword")(version 3.0;acl "Anonymous read-search access";
 allow (read, search, compare)(userdn = "ldap:///anyone");)
 

$ dsconfig
 get-access-control-handler-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --property global-aci

$ dsconfig \
 set-access-control-handler-prop \
 --remove global-aci:\(targetattr!=\"userPassword\|\|authPassword\|\|changes\|\
\|changeNumber\|\|changeType\|\|changeTime\|\|targetDN\|\|newRDN\|\
\|newSuperior\|\|deleteOldRDN\|\|targetEntryUUID\|\|changeInitiatorsName\|\
\|changeLogCookie\|\|includedAttributes\"\)\(version\ 3.0\;\ acl\ \"Anonymous\
\ read\ access\"\;\ allow\ \(read,search,compare\)\
\ userdn=\"ldap:///anyone\"\;\)\
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN cn=Directory\ Manager \
 --bindPassword password \
 --trustAll \
 --no-prompt

$ dsconfig
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --commandFilePath /tmp/captured-command.sh

global-aci: (targetattr!="userPassword||
 authPassword||changes||changeNumber||changeType||changeTime||targetDN||newRDN||
 newSuperior||deleteOldRDN||targetEntryUUID||changeInitiatorsName||
 changeLogCookie||includedAttributes")(version 3.0; acl "Authenticated users
 read access"; allow (read,search,compare) userdn="ldap:///all";)

aci: (target="ldap:///dc=example,dc=com") (targetattr =
 "* || +")(version 3.0;acl "Admins can run amok"; allow(
 all, proxy, import, export) groupdn =
 "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)
 

aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr =
 "authPassword || userPassword")(version 3.0;acl "Allow users to change pass
 words"; allow (write)(userdn = "ldap:///self");)

aci: (target ="ldap:///ou=Self Service,ou=Groups,dc=example,dc=com")(
 targetattr = "member")(version 3.0;acl "Self registration"; allow(selfwrite)(
 userdn = "ldap:///uid=*,ou=People,dc=example,dc=com");)

aci: (target ="ldap:///ou=Self Service,ou=Groups,dc=example,dc=com")(
 targattrfilters="add=objectClass:(objectClass=groupOfNames)")(version 3.0;
 acl "All can create self service groups"; allow (add)(userdn= "
 ldap:///uid=*,ou=People,dc=example,dc=com");)
aci: (target ="ldap:///ou=Self Service,ou=Groups,dc=example,dc=com")(version 3
 .0; acl "Owner can delete self service groups"; allow (delete)(userattr= "
 owner#USERDN");)

aci: (target = "ldap:///dc=example,dc=com")(targetattr =
 "*")(version 3.0;acl "Use loopback only for LDAP in the clear"; deny (all)(
 ip != "127.0.0.1" and ssf <= "1");)

Once you set up a number of ACIs, you might find it difficult to understand by inspection what rights a user actually has to a given entry. The Get Effective Rights control can help.

In this example, Babs Jensen is the owner of a small group of people who are willing to carpool.

$ ldapsearch
 --port 1389
 --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
 --bindPassword hifalutin
 --baseDN "ou=Self Service,ou=Groups,dc=example,dc=com"
 "cn=*" 
dn: cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com
objectClass: groupOfNames
objectClass: top
member: uid=bjensen,ou=People,dc=example,dc=com
description: People who are willing to carpool
owner: uid=bjensen,ou=People,dc=example,dc=com
cn: Carpoolers

Performing the same search with the get effective rights control, and asking for the aclRights attribute, shows what rights Babs has on the entry.

$ ldapsearch
 --control effectiverights
 --port 1389
 --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
 --bindPassword hifalutin
 --baseDN "ou=Self Service,ou=Groups,dc=example,dc=com"
 "cn=*"
 aclRights
dn: cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com
aclRights;entryLevel: add:0,delete:1,read:1,write:0,proxy:0

Requesting the aclRightsInfo attribute results in information about the ACIs applied to arrive at the results.

$ ldapsearch
 --control effectiverights
 --port 1389
 --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
 --bindPassword hifalutin
 --baseDN "ou=Self Service,ou=Groups,dc=example,dc=com"
 "cn=*"
 aclRights
 aclRightsInfo
dn: cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com
aclRightsInfo;logs;entryLevel;read: acl_summary(main): access allowed(read) on e
 ntry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, objectClas
 s) to (uid=bjensen,ou=People,dc=example,dc=com) (not proxied) ( reason: evaluat
 ed allow , deciding_aci: Anonymous read-search access)
aclRightsInfo;logs;entryLevel;write: acl_summary(main): access not allowed(write
 ) on entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL
 ) to (uid=bjensen,ou=People,dc=example,dc=com) (not proxied) ( reason: no acis 
 matched the subject )
aclRightsInfo;logs;entryLevel;add: acl_summary(main): access not allowed(add) on
  entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL) to
  (uid=bjensen,ou=People,dc=example,dc=com) (not proxied) ( reason: no acis matc
 hed the subject )
aclRightsInfo;logs;entryLevel;delete: acl_summary(main): access allowed(delete) 
 on entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL) 
 to (uid=bjensen,ou=People,dc=example,dc=com) (not proxied) ( reason: evaluated 
 allow , deciding_aci: Owner can delete self service groups)
aclRights;entryLevel: add:0,delete:1,read:1,write:0,proxy:0
aclRightsInfo;logs;entryLevel;proxy: acl_summary(main): access not allowed(proxy
 ) on entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL
 ) to (uid=bjensen,ou=People,dc=example,dc=com) (not proxied) ( reason: no acis 
 matched the subject )

You can also request the effective rights for another user by using the --getEffectiveRightsAuthzid (short form: -g) option, which takes the authorization identity of the other user as an argument. The following example shows Directory Manager checking anonymous user rights to the same entry. Notice that the authorization identity for an anonymous user is expressed as "dn:".

$ ldapsearch
 --getEffectiveRightsAuthzid "dn:"
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --baseDN "ou=Self Service,ou=groups,dc=example,dc=com"
 "cn=*" aclRightsInfo
dn: cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com
aclRightsInfo;logs;entryLevel;read: acl_summary(main): access allowed(read) on e
 ntry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, objectClas
 s) to (anonymous) (not proxied) ( reason: evaluated allow , deciding_aci: Anony
 mous read-search access)
aclRightsInfo;logs;entryLevel;write: acl_summary(main): access not allowed(write
 ) on entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL
 ) to (anonymous) (not proxied) ( reason: no acis matched the subject )
aclRightsInfo;logs;entryLevel;add: acl_summary(main): access not allowed(add) on
  entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL) to
  (anonymous) (not proxied) ( reason: no acis matched the subject )
aclRightsInfo;logs;entryLevel;delete: acl_summary(main): access not allowed(dele
 te) on entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NU
 LL) to (anonymous) (not proxied) ( reason: no acis matched the subject )
aclRightsInfo;logs;entryLevel;proxy: acl_summary(main): access not allowed(proxy
 ) on entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL
 ) to (anonymous) (not proxied) ( reason: no acis matched the subject )

When you need to check access to an attribute that might not yet exist on the entry, you can further use the --getEffectiveRightsAttribute (short form: -e) option, which takes an attribute list as an argument. The following example shows Directory Manager checking anonymous user access to the description attribute for the Self Service groups organizational unit entry. The description attribute is not present on the entry, yet.

$ ldapsearch
 --port 1389
 --baseDN "ou=Self Service,ou=groups,dc=example,dc=com"
 "ou=Self Service" description
dn: ou=Self Service,ou=Groups,dc=example,dc=com

$ ldapsearch
 --getEffectiveRightsAuthzid "dn:"
 --getEffectiveRightsAttribute description
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --baseDN "ou=Self Service,ou=groups,dc=example,dc=com"
 "ou=Self Service" aclRights
dn: ou=Self Service,ou=Groups,dc=example,dc=com
aclRights;attributeLevel;description: search:1,read:1,compare:1,write:0,selfwrit
 e_add:0,selfwrite_delete:0,proxy:0
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

Searching the directory resembles searching for a phone number in a paper phone book. You can look up a phone number because you know the last name of a subscriber's entry. In other words, you use the value of one attribute of the entry to find entries that have another attribute you want.

Yet whereas a paper phone book has only one index (alphabetical order by name), the directory has many indexes. For a search you therefore always specify which index to use, by specifying which attribute(s) you are using to lookup entries.

Your paper phone book might be divided into white pages for residential subscribers, and yellow pages for businesses. If you are looking up an individual's phone number, you limit your search to the white pages. Directory services divide entries in various ways, often to separate organizations, and to separate groups from user entries from printers for example, but potentially in other ways. When searching you therefore also specify where in the directory to search.

The ldapsearch command thus takes at minimum a search base DN option and an LDAP filter. The search base DN identifies where in the directory to search for entries that match the filter. For example, if you are looking for printers, you might specify the base DN as ou=Printers,dc=example,dc=com. Perhaps you are visiting the GNB00 office and are looking for a printer.

$ ldapsearch --baseDN ou=Printers,dc=example,dc=com "(printerLocation=GNB00)"

In the example, the LDAP filter indicates to the directory that you want to lookup printer entries where the printerLocation attribute is equal to GNB00.

You also specify the host and port to access directory services, what protocol to use (for example, LDAP/SSL, or StartTLS to protect communication). If the directory service does not allow anonymous access to the data you want to search, you also identify who is performing the search and provide their credentials, such as a password or certificate. Finally, you can specify a list of attributes to return. If you do not specify attributes, then the search returns all user attributes for the entry.

$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=*jensen*)" uid
dn: uid=ajensen,ou=People,dc=example,dc=com
uid: ajensen

dn: uid=bjensen,ou=People,dc=example,dc=com
uid: bjensen

dn: uid=gjensen,ou=People,dc=example,dc=com
uid: gjensen

dn: uid=jjensen,ou=People,dc=example,dc=com
uid: jjensen

dn: uid=kjensen,ou=People,dc=example,dc=com
uid: kjensen

dn: uid=rjensen,ou=People,dc=example,dc=com
uid: rjensen

dn: uid=tjensen,ou=People,dc=example,dc=com
uid: tjensen


Result Code:  0 (Success)

$ ldapsearch
 --port 1389
 --baseDN ou=people,dc=example,dc=com
 "(&(uid=*jensen*)(l=Santa Clara))"
 @person
dn: uid=ajensen,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: top
cn: Allison Jensen
telephoneNumber: +1 408 555 7892
sn: Jensen

dn: uid=gjensen,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: top
cn: Gern Jensen
telephoneNumber: +1 408 555 3299
sn: Jensen

dn: uid=kjensen,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: top
cn: Kurt Jensen
telephoneNumber: +1 408 555 6127
sn: Jensen

dn: uid=tjensen,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: top
cn: Ted Jensen
telephoneNumber: +1 408 555 8622
sn: Jensen

$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen +
dn: uid=bjensen,ou=People,dc=example,dc=com
numSubordinates: 0
structuralObjectClass: inetOrgPerson
pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config
subschemaSubentry: cn=schema
hasSubordinates: false
entryDN: uid=bjensen,ou=people,dc=example,dc=com
entryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c

$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen @person
dn: uid=bjensen,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: top
cn: Barbara Jensen
cn: Babs Jensen
telephoneNumber: +1 408 555 1862
sn: Jensen

$ ldapsearch --port 1389 --baseDN dc=example,dc=com
 "(description=\28*\5c*\2a\29)" description
dn: uid=bjensen,ou=People,dc=example,dc=com
description: (A \great\ description*)

$ ldapmodify
 --port 1389
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
dn: cn=schema
changetype: modify
add: attributeTypes
attributeTypes: ( lastLoginTime-oid
  NAME 'lastLoginTime'
  DESC 'Last time the user logged in'
  EQUALITY generalizedTimeMatch
  ORDERING generalizedTimeOrderingMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
  SINGLE-VALUE
  NO-USER-MODIFICATION
  USAGE directoryOperation
  X-ORIGIN 'OpenDJ example documentation' )

Processing MODIFY request for cn=schema
MODIFY operation successful for DN cn=schema

$ dsconfig
 set-password-policy-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --policy-name "Default Password Policy"
 --set last-login-time-attribute:lastLoginTime
 --set last-login-time-format:"yyyyMMddHH'Z'"
 --trustAll
 --no-prompt

$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 "(lastLoginTime:1.3.6.1.4.1.26027.1.4.6:=13w)" mail
dn: uid=bjensen,ou=People,dc=example,dc=com
mail: bjensen@example.com

dn: uid=kvaughan,ou=People,dc=example,dc=com
mail: kvaughan@example.com

$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 "(givenName:fr:=Fréderique)" cn\;lang-fr
dn: uid=fdupont,ou=People,dc=example,dc=com
cn;lang-fr:: RnJlZMOpcmlxdWUgRHVwb250

$ base64 decode -d RnJlZMOpcmlxdWUgRHVwb250
Fredérique Dupont

The following table describes the operators you can use in LDAP search filters.

The compare operation checks whether an attribute value you specify matches the attribute value stored on one or more directory entries.

$ ldapcompare
 --port 1389
 --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
 --bindPassword bribery
 'authPassword:MD5$dFHgpDxXUT8=$qlC4xMXvmVlusJLz9/WJ5Q=='
 uid=kvaughan,ou=people,dc=example,dc=com
Comparing type authPassword with value
 MD5$dFHgpDxXUT8=$qlC4xMXvmVlusJLz9/WJ5Q== in entry
 uid=kvaughan,ou=people,dc=example,dc=com
Compare operation returned true for entry
 uid=kvaughan,ou=people,dc=example,dc=com

Authorized users can change directory data using the LDAP add, modify, modify DN, and delete operations.

$ cat new-users.ldif 
dn: cn=Arsene Lupin,ou=Special Users,dc=example,dc=com
objectClass: person
objectClass: top
cn: Arsene Lupin
telephoneNumber: +33 1 23 45 67 89
sn: Lupin

dn: cn=Horace Velmont,ou=Special Users,dc=example,dc=com
objectClass: person
objectClass: top
cn: Horace Velmont
telephoneNumber: +33 1 12 23 34 45
sn: Velmont

$ ldapmodify
 --defaultAdd
 --port 1389
 --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
 --bindPassword bribery
 --filename new-users.ldif
Processing ADD request for cn=Arsene Lupin,ou=Special Users,dc=example,dc=com
ADD operation successful for DN
 cn=Arsene Lupin,ou=Special Users,dc=example,dc=com
Processing ADD request for cn=Horace Velmont,ou=Special Users,dc=example,dc=com
ADD operation successful for DN
 cn=Horace Velmont,ou=Special Users,dc=example,dc=com

$ cat scarter-mods.ldif 
dn: uid=scarter,ou=people,dc=example,dc=com
changetype: modify
add: description
description: Accounting Manager
-
add: jpegphoto
jpegphoto:<file:///tmp/Samantha-Carter.jpg

$ ldapmodify
 --port 1389
 --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
 --bindPassword bribery
 --filename scarter-mods.ldif
Processing MODIFY request for uid=scarter,ou=people,dc=example,dc=com
MODIFY operation successful for DN uid=scarter,ou=people,dc=example,dc=com

$ cat scarter-newdesc.ldif
dn: uid=scarter,ou=people,dc=example,dc=com
changetype: modify
replace: description
description: Accounting Director

$ ldapmodify
 --port 1389
 --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
 --bindPassword bribery
 --filename scarter-newdesc.ldif 
Processing MODIFY request for uid=scarter,ou=people,dc=example,dc=com
MODIFY operation successful for DN uid=scarter,ou=people,dc=example,dc=com

$ cat /path/to/scarter-deljpeg.ldif 
dn: uid=scarter,ou=people,dc=example,dc=com
changetype: modify
delete: jpegphoto

$ ldapmodify
 --port 1389
 --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
 --bindPassword bribery
 --filename scarter-deljpeg.ldif 
Processing MODIFY request for uid=scarter,ou=people,dc=example,dc=com
MODIFY operation successful for DN uid=scarter,ou=people,dc=example,dc=com

dn: uid=bjensen,ou=People,dc=example,dc=com
telephoneNumber: +1 408 555 1862
roomNumber: 0209
l: Cupertino
ETag: 000000007a1999df

dn: uid=bjensen,ou=People,dc=example,dc=com
description: Updated by Alice
telephoneNumber: +47 2108 1746
roomNumber: 1389
l: Cupertino
ETag: 00000000aec2c1e9

$ cat /path/to/bobs.ldif
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
replace: l
l: Grenoble
-
add: description
description: Employee of the Month

$ ldapmodify
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --port 1389
 --filename /path/to/bobs.ldif
 --assertionFilter "(ETag=000000007a1999df)"
Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
MODIFY operation failed
Result Code:  122 (Assertion Failed)
Additional Information:  Entry uid=bjensen,ou=People,dc=example,dc=com
 cannot be modified because the request contained an LDAP assertion control
 and the associated filter did not match the contents of the that entry

dn: uid=bjensen,ou=People,dc=example,dc=com
description: Employee of the Month
telephoneNumber: +47 2108 1746
roomNumber: 1389
l: Grenoble
ETag: 00000000e882c35e

$ dsconfig
 create-plugin
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --type attribute-cleanup
 --plugin-name "Rename email to mail"
 --set enabled:true
 --set rename-inbound-attributes:email:mail
 --trustAll
 --no-prompt

$ cat email.ldif 
dn: uid=newuser,ou=People,dc=example,dc=com
uid: newuser
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
cn: New User
sn: User
ou: People
email: newuser@example.com
userPassword: changeme

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --defaultAdd
 --filename email.ldif
Processing ADD request for uid=newuser,ou=People,dc=example,dc=com
ADD operation successful for DN uid=newuser,ou=People,dc=example,dc=com
$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=newuser mail
dn: uid=newuser,ou=People,dc=example,dc=com
mail: newuser@example.com

$ dsconfig
 create-plugin
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --type attribute-cleanup
 --plugin-name "Remove attrs"
 --set enabled:true
 --set remove-inbound-attributes:creatorsName
 --set remove-inbound-attributes:createTimestamp
 --set remove-inbound-attributes:modifiersName
 --set remove-inbound-attributes:modifyTimestamp
 --trustAll
 --no-prompt

$ cat badattrs.ldif 
dn: uid=badattr,ou=People,dc=example,dc=com
uid: newuser
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
cn: Bad Attr
sn: Attr
ou: People
mail: badattr@example.com
userPassword: changeme
creatorsName: cn=Bad Attr
createTimestamp: Never in a million years.
modifiersName: cn=Directory Manager,cn=Root DNs,cn=config
modifyTimestamp: 20110930164937Z

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --defaultAdd
 --filename badattrs.ldif
Processing ADD request for uid=badattr,ou=People,dc=example,dc=com
ADD operation successful for DN uid=badattr,ou=People,dc=example,dc=com
$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=badattr +
dn: uid=badattr,ou=People,dc=example,dc=com
numSubordinates: 0
structuralObjectClass: inetOrgPerson
pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config
subschemaSubentry: cn=schema
hasSubordinates: false
entryDN: uid=badattr,ou=people,dc=example,dc=com
entryUUID: 35e5cb0e-e929-49d8-a50f-2df036d60db9
pwdChangedTime: 20110930165959.135Z
creatorsName: cn=Directory Manager,cn=Root DNs,cn=config
createTimestamp: 20110930165959Z

$ cat /path/to/scarter-sjensen.ldif
dn: uid=scarter,ou=people,dc=example,dc=com
changetype: modrdn
newrdn: uid=sjensen
deleteoldrdn: 1

dn: uid=sjensen,ou=people,dc=example,dc=com
changetype: modify
replace: cn
cn: Sam Jensen
-
replace: sn
sn: Jensen
-
replace: homeDirectory
homeDirectory: /home/sjensen
-
replace: mail
mail: sjensen@example.com

$ ldapmodify
 --port 1389
 --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
 --bindPassword bribery
 --filename /path/to/scarter-sjensen.ldif 
Processing MODIFY DN request for uid=scarter,ou=people,dc=example,dc=com
MODIFY DN operation successful for DN uid=scarter,ou=people,dc=example,dc=com
Processing MODIFY request for uid=sjensen,ou=people,dc=example,dc=com
MODIFY operation successful for DN uid=sjensen,ou=people,dc=example,dc=com

$ cat move-customers.ldif 
dn: ou=Customers,dc=example,dc=com
changetype: modrdn
newrdn: ou=People
deleteoldrdn: 1
newsuperior: dc=example,dc=com

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --filename move-customers.ldif 
Processing MODIFY DN request for ou=Customers,dc=example,dc=com
MODIFY DN operation successful for DN ou=Customers,dc=example,dc=com
$ cat move-employees.pl 
#!/usr/bin/perl -w

# For each employee, construct a spec to move under ou=People.
while (<>)
{
    # Next line folded for readability only. Should not be split.
    $_ =~ s/dn: (.*?)(,.*)/dn: $1$2\nchangetype: moddn\nnewrdn: $1\n
     deleteoldrdn: 0\nnewsuperior: ou=People,dc=example,dc=com/;
    print;
}
$ ldapsearch --port 1389 --baseDN ou=Employees,dc=example,dc=com uid=* - |
 move-employees.pl > /tmp/move-employees.ldif
$ head -n 6 /tmp/move-employees.ldif 
dn: uid=abarnes,ou=Employees,dc=example,dc=com
changetype: moddn
newrdn: uid=abarnes
deleteoldrdn: 0
newsuperior: ou=People,dc=example,dc=com

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --filename /tmp/move-employees.ldif
Processing MODIFY DN request for uid=abarnes,ou=Employees,dc=example,dc=com
MODIFY DN operation successful for DN uid=abarnes,ou=Employees,dc=example,dc=com
Processing MODIFY DN request for uid=abergin,ou=Employees,dc=example,dc=com
MODIFY DN operation successful for DN uid=abergin,ou=Employees,dc=example,dc=com
...
Processing MODIFY DN request for uid=wlutz,ou=Employees,dc=example,dc=com
MODIFY DN operation successful for DN uid=wlutz,ou=Employees,dc=example,dc=com
$ ldapdelete
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 ou=Employees,dc=example,dc=com
Processing DELETE request for ou=Employees,dc=example,dc=com
DELETE operation successful for DN ou=Employees,dc=example,dc=com

$ ldapdelete
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --deleteSubtree "ou=Special Users,dc=example,dc=com"
Processing DELETE request for ou=Special Users,dc=example,dc=com
DELETE operation successful for DN ou=Special Users,dc=example,dc=com

With the ldappasswordmodify command, authorized users can change and reset user passwords.

$ ldappasswordmodify
 --useStartTLS
 --port 1389
 --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
 --bindPassword bribery
 --authzID "dn:uid=scarter,ou=people,dc=example,dc=com"
 --newPassword ChangeMe
The LDAP password modify operation was successful

$ manage-account
 set-password-is-reset
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --targetDN uid=scarter,ou=people,dc=example,dc=com
 --operationValue true
Password Is Reset:  true

$ ldappasswordmodify
 --port 1389
 --authzID "dn:uid=bjensen,ou=people,dc=example,dc=com"
 --currentPassword hifalutin
 --newPassword secret12
The LDAP password modify operation was successful

$ ldappasswordmodify
 --port 1389
 --authzID "dn:cn=Directory Manager"
 --currentPassword password
 --newPassword secret12
The LDAP password modify operation was successful

$ echo $LANG
en_US.utf8
$ ldappasswordmodify
 --port 1389
 --bindDN uid=bjensen,ou=People,dc=example,dc=com
 --bindPassword hifalutin
 --currentPassword hifalutin
 --newPassword pàsswȏrd
The LDAP password modify operation was successful
$ ldapsearch
 --port 1389
 --bindDN uid=bjensen,ou=People,dc=example,dc=com
 --bindPassword pàsswȏrd
 --baseDN dc=example,dc=com
 "(uid=bjensen)" cn
dn: uid=bjensen,ou=People,dc=example,dc=com
userPassword: {SSHA}k0eEeCxj9YRXUp8yJn0Z/mwqe+wrcFb1N1gg2g==
cn: Barbara Jensen
cn: Babs Jensen

You can use ~/.opendj/tools.properties to set the defaults for bind DN, host name, and port number as in the following example.

hostname=directory.example.com
port=1389
bindDN=uid=kvaughan,ou=People,dc=example,dc=com

ldapcompare.port=1389
ldapdelete.port=1389
ldapmodify.port=1389
ldappasswordmodify.port=1389
ldapsearch.port=1389

The location on Windows is %UserProfile%/.opendj/tools.properties.

Authentication is the act of confirming the identity of a principal. Authorization is the act of determining whether to grant or to deny access to a principal. Authentication is done to make authorization decisions.

As explained in Configuring Privileges & Access Control, OpenDJ directory server implements fine-grained access control for authorization. What is authorized depends on who is requesting the operation. Directory servers like OpenDJ must first therefore authenticate the principals using the clients before they can authorize or deny access. The LDAP bind operation, where a directory client authenticates with the directory server, is therefore the first LDAP operation in every LDAP session.

Clients bind by providing both a means to find their principal's entry in the directory and also providing some credentials that the directory server can check against their entry.

In the simplest bind operation, the client provides a zero-length name and a zero-length password. This results in an anonymous bind, meaning the client is authenticated as an anonymous user of the directory. In the simplest examples in Section 6.1, "Searching the Directory", notice that no authentication information is provided. The examples work because the client commands default to requesting anonymous binds when you provide no credentials, and because access controls for the sample data allow anonymous clients to read, search, and compare some directory data.

In a simple bind operation, the client provides an LDAP name, such as the DN identifying its entry, and the corresponding password stored on the userPassword attribute of the entry. In Section 6.3, "Updating the Directory", notice that to change directory data the client provides the bind DN and bind password of a user who has permission to change directory data. The commands do not work with a bind DN and bind password because access controls for the sample data only allow authorized users to change directory data.

Users rarely provide client applications with DNs, however. Instead users might provide a client application with an identity string like a user ID or an email address for example. Depending on how the DNs are constructed, the client application can either build the DN directly from the user's identity string, or use a session where the bind has been done with some other identity to search for the user entry based on the user's identity string. Given the DN constructed or found, the client application can then perform a simple bind.

For example, suppose Babs Jensen enters her email address, bjensen@example.com, and her password in order to log in. The client application might search for the entry matching (mail=bjensen@example.com) under base DN dc=example,dc=com. Alternatively, the client application might know to extract the user ID bjensen from the address, and then build the corresponding DN, uid=bjensen,ou=people,dc=example,dc=com in order to bind.

When an identifier string provided by the user can readily be mapped to the user's entry DN, OpenDJ directory server can do the translation between the identifier string and the entry DN. This translation is the job of a component called an identity mapper. Identity mappers are used to perform PLAIN SASL authentication (with a user name and password), SASL GSSAPI authentication (Kerberos V5), SASL CRAM MD5 and DIGEST MD5 authentication. They also handle authorization IDs during password modify extended operations and proxied authorization.

One use of PLAIN SASL is to translate user names from HTTP Basic authentication to LDAP authentication. The following example shows PLAIN SASL authentication using the default Exact Match identity mapper. In this (contrived) example, Babs Jensen reads the hashed value of her password. (According to the access controls in the example data, Babs must authenticate to read her password.) Notice the authentication ID is her user ID, u:bjensen, rather than the DN of her entry.

$ ldapsearch
 --port 1389
 --useStartTLS
 --baseDN dc=example,dc=com
 --saslOption mech=PLAIN
 --saslOption authid=u:bjensen
 --bindPassword hifalutin
 "(cn=Babs Jensen)" cn userPassword
dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen
userPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA==

The Exact Match identity mapper searches for a match between the string provided (here, bjensen) and the value of a specified attribute (by default the uid attribute). If you know users are entering their email addresses, you could create an exact match identity mapper for email addresses, and then use that for PLAIN SASL authentication as in the following example.

$ dsconfig
 create-identity-mapper
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --mapper-name "Email Mapper"
 --type exact-match
 --set match-attribute:mail
 --set enabled:true
 --no-prompt
$ dsconfig
 set-sasl-mechanism-handler-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name PLAIN
 --set identity-mapper:"Email Mapper"
 --no-prompt
$ ldapsearch
 --port 1389
 --useStartTLS
 --baseDN dc=example,dc=com
 --saslOption mech=PLAIN
 --saslOption authid=u:bjensen@example.com
 --bindPassword hifalutin
 "(cn=Babs Jensen)" cn userPassword
dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen
userPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA==

The Regular Expression identity mapper uses a regular expression to extract a substring from the string provided, and then searches for a match between the substring and the value of a specified attribute. In the case of example data where an email address is user ID + @ + domain, you can use the default Regular Expression identity mapper in the same way as the email mapper from the previous example. The default regular expression pattern is ^([^@]+)@.+$, and the part of the identity string matching ([^@]+) is used to find the entry by user ID.

$ dsconfig
 set-sasl-mechanism-handler-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name PLAIN
 --set identity-mapper:"Regular Expression"
 --no-prompt
$ ldapsearch
 --port 1389
 --useStartTLS
 --baseDN dc=example,dc=com
 --saslOption mech=PLAIN
 --saslOption authid=u:bjensen@example.com
 --bindPassword hifalutin
 "(cn=Babs Jensen)" cn userPassword
dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen
userPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA==

Try the dsconfig command interactively to experiment with match-pattern and replace-pattern settings for the Regular Expression identity mapper. The match-pattern can be any regular expression supported by javax.util.regex.Pattern.

Proxied authorization provides a standard control as defined in RFC 4370 (and an earlier Internet-Draft) for binding with the user credentials of a proxy, who carries out LDAP operations on behalf of other users. You might use proxied authorization, for example, to have your application bind with its credentials, and then carry out operations as the users who login to the application.

Suppose you have an administrative directory client application that has an entry in the directory with DN cn=My App,ou=Apps,dc=example,dc=com. You can give that application the access rights and privileges to use proxied authorization. The default access control for OpenDJ permits authenticated users to use the proxied authorization control.

Suppose also that when directory administrator, Kirsten Vaughan, logs in to your application to change Babs Jensen's entry, your application looks up Kirsten's entry, and finds that she has DN uid=kvaughan,ou=People,dc=example,dc=com. For the example commands in the following procedure. My App uses proxied authorization to make a change to Babs's entry as Kirsten.

If you need to map authorization identifiers using the u: form rather than using dn:, you can set the identity mapper with the global configuration setting, proxied-authorization-identity-mapper. For example, if you get user ID values from the client, such as bjensen, you can use the Exact Match Identity Mapper to match those to DNs based on an attribute of the entry. Use the dsconfig command interactively to investigate the settings you need.

One alternative to simple binds with user name/password combinations consists in storing a digital certificate on the user entry, and then using the certificate as credentials during the bind. You can use this mechanism for example to let applications bind without using passwords.

Simply by setting up a secure connection with a certificate, the client is in effect authenticating to the server. The server must close the connection if it cannot trust the client certificate. However, the process of establishing a secure connection does not in itself identify the client to OpenDJ directory server.

Instead when binding with a certificate, the client must request the SASL External mechanism by which OpenDJ directory server maps the certificate to the client entry in the directory. When it finds a match, OpenDJ sets the authorization identity for the connection to that of the client, and the bind is successful.

For the whole process of authenticating with a certificate to work smoothly, OpenDJ and the client must trust each others' certificates, the client certificate must be stored on the client entry in the directory, and OpenDJ must be configured to map the certificate to the client entry.

$ echo changeit > keystore.pin
$ chmod 400 keystore.pin

$ keytool
 -export
 -alias server-cert
 -file server-cert.crt
 -keystore /path/to/opendj/config/keystore
 -storepass `cat /path/to/opendj/config/keystore.pin`
$ keytool
 -import
 -trustcacerts
 -alias server-cert
 -file server-cert.crt
 -keystore keystore
 -storepass `cat keystore.pin`

$ keytool
 -import
 -trustcacerts
 -alias ca-cert
 -file ca-cert.crt
 -keystore keystore
 -storepass `cat keystore.pin`

$ ldapsearch
 --port 1389
 --hostname opendj.example.com
 --baseDN dc=example,dc=com
 --useStartTLS
 --trustStorePath keystore
 --trustStorePasswordFile keystore.pin
 "(cn=My App)" userPassword
dn: cn=My App,ou=Apps,dc=example,dc=com

$ ldapsearch
 --port 1389
 --hostname opendj.example.com
 --baseDN dc=example,dc=com
 --useStartTLS
 --useSASLExternal
 --certNickName myapp-cert
 --keyStorePath keystore
 --keyStorePasswordFile keystore.pin
 --trustStorePath keystore
 --trustStorePasswordFile keystore.pin
 "(cn=My App)" userPassword
dn: cn=My App,ou=Apps,dc=example,dc=com
userPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==

# Fingerprint mapper
$ dsconfig
 set-sasl-mechanism-handler-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name External
 --set certificate-mapper:"Fingerprint Mapper"
 --no-prompt
$ ldapsearch
 --port 1389
 --hostname opendj.example.com
 --baseDN dc=example,dc=com
 --useStartTLS
 --useSASLExternal
 --certNickName myapp-cert
 --keyStorePath keystore
 --keyStorePasswordFile keystore.pin
 --trustStorePath keystore
 --trustStorePasswordFile keystore.pin
 "(cn=My App)" userPassword
dn: cn=My App,ou=Apps,dc=example,dc=com
userPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==

# Subject Attribute to User Attribute mapper
$ dsconfig
 set-sasl-mechanism-handler-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name External
 --set certificate-mapper:"Subject Attribute to User Attribute"
 --no-prompt
$ ldapsearch
 --port 1389
 --hostname opendj.example.com
 --baseDN dc=example,dc=com
 --useStartTLS
 --useSASLExternal
 --certNickName myapp-cert
 --keyStorePath keystore
 --keyStorePasswordFile keystore.pin
 --trustStorePath keystore
 --trustStorePasswordFile keystore.pin
 "(cn=My App)" userPassword
dn: cn=My App,ou=Apps,dc=example,dc=com
userPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==

# Subject DN to User Attribute mapper
$ dsconfig
 set-sasl-mechanism-handler-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name External
 --set certificate-mapper:"Subject DN to User Attribute"
 --no-prompt
$ ldapsearch
 --port 1389
 --hostname opendj.example.com
 --baseDN dc=example,dc=com
 --useStartTLS
 --useSASLExternal
 --certNickName myapp-cert
 --keyStorePath keystore
 --keyStorePasswordFile keystore.pin
 --trustStorePath keystore
 --trustStorePasswordFile keystore.pin
 "(cn=My App)" userPassword
dn: cn=My App,ou=Apps,dc=example,dc=com
userPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==

The OpenDJ REST API is built on a common ForgeRock HTTP-based REST API for interacting with JSON Resources. APIs built on this common layer all let you perform the following operations.

The present implementation in OpenDJ maps JSON resources onto LDAP entries, meaning REST clients can in principle do just about anything an LDAP client can do with directory data.

When you first try to get a resource that you can read as an LDAP entry with an anonymous search, you might be surprised that you must authenticate.

$ curl http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "code" : 401,
  "reason" : "Unauthorized",
  "message" : "Unauthorized"
}

HTTP status code 401 tells your HTTP client that the request requires user authentication. You can change this behavior by setting the HTTP connection handler property, authentication-required, to false.

$ dsconfig
 set-connection-handler-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name "HTTP Connection Handler"
 --set authentication-required:false
 --no-prompt
 --trustAll

Out of the box both the HTTP Connection Handler and also the REST LDAP gateway are configured to allow HTTP Basic authentication and HTTP header based authentication in the style of OpenIDM. The authentication mechanisms translate HTTP authentication to LDAP authentication on the directory server side.

When you install OpenDJ either with generated sample user entries or with data from Example.ldif, the relative distinguished name attribute for the sample user entries is the user ID (uid) attribute. For example, the DN and user ID for Babs Jensen are as follows.

dn: uid=bjensen,ou=People,dc=example,dc=com
uid: bjensen

Given this pattern in the user entries, the default REST to LDAP configuration assumes that the user name on the HTTP side is the value of the user ID, and that user entries can be found under ou=People,dc=example,dc=com. In other words, Babs Jensen authenticates as bjensen (password: hifalutin) over HTTP. This is mapped for an LDAP bind to the bind DN uid=bjensen,ou=People,dc=example,dc=com.

With HTTP Basic authentication, it looks like this.

$ curl
 --user bjensen:hifalutin
 http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "_rev" : "0000000016cbb68c",
  ...
}

Or, using the HTTP Basic username:password@ form in the URL, it looks like this.

$ curl
http://bjensen:hifalutin@opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "_rev" : "0000000016cbb68c",
  ...
}

With HTTP header based authentication, it looks like this.

$ curl
 --header "X-OpenIDM-Username: bjensen"
 --header "X-OpenIDM-Password: hifalutin"
 http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "_rev" : "0000000016cbb68c",
  ...
}

If your directory data are laid out differently, or if your user names are email addresses rather than user IDs for example, then you must update the configuration in order for authentication to work.

The REST LDAP gateway can also translate HTTP user name and password authentication to PLAIN SASL authentication on the LDAP side. Moreover, the gateway can fall back to proxied authorization as necessary, using a root DN authenticated connection to LDAP servers. See REST LDAP Configuration for details on all configuration choices.

There are two ways to create resources.

To read a resource, perform an HTTP GET.

$ curl
 --request GET
 --user kvaughan:bribery
 http://opendj.example.com:8080/users/newuser?_prettyPrint=true
{
  "_rev" : "000000005b337348",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1212",
    "emailAddress" : "newuser@example.com"
  },
  "_id" : "newuser",
  "name" : {
    "familyName" : "New",
    "givenName" : "User"
  },
  "userName" : "newuser@example.com",
  "displayName" : "New User",
  "meta" : {
    "created" : "2013-04-11T09:58:27Z"
  },
  "manager" : [ {
    "_id" : "kvaughan",
    "displayName" : "Kirsten Vaughan"
  } ]
}

To update a resource, perform an HTTP PUT with the changes to the resource. For read-only fields, either include unmodified versions, or omit them from your updated version.

The following example adds a manager for Sam Carter.

$ curl
 --request PUT
 --user kvaughan:bribery
 --header "Content-Type: application/json"
 --data '{
   "contactInformation": {
     "telephoneNumber": "+1 408 555 4798",
     "emailAddress": "scarter@example.com"
   },
   "name": {
     "familyName": "Carter",
     "givenName": "Sam"
   },
   "userName": "scarter@example.com",
   "displayName": "Sam Carter",
   "groups": [
     {
       "_id": "Accounting Managers"
     }
   ],
   "manager": [
     {
       "_id": "trigden",
       "displayName": "Torrey Rigden"
     }
   ]
 }'
 http://opendj.example.com:8080/users/scarter?_prettyPrint=true
{
  "_rev" : "00000000a1923db2",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 4798",
    "emailAddress" : "scarter@example.com"
  },
  "_id" : "scarter",
  "name" : {
    "familyName" : "Carter",
    "givenName" : "Sam"
  },
  "userName" : "scarter@example.com",
  "displayName" : "Sam Carter",
  "manager" : [ {
    "_id" : "trigden",
    "displayName" : "Torrey Rigden"
  } ],
  "meta" : {
    "lastModified" : "2013-04-12T07:42:34Z"
  },
  "groups" : [ {
    "_id" : "Accounting Managers"
  } ]
}

To update a resource only if the resource matches a particular version, use an If-Match: revision header.

 $ curl
 --user kvaughan:bribery
 http://opendj.example.com:8080/users/scarter?_fields=_rev
{"_rev":"00000000b017c5b8"}
$ curl
 --request PUT
 --user kvaughan:bribery
 --header "If-Match: 00000000b017c5b8"
 --header "Content-Type: application/json"
 --data '{
   "contactInformation": {
     "telephoneNumber": "+1 408 555 1212",
     "emailAddress": "scarter@example.com"
   },
   "name": {
     "familyName": "Carter",
     "givenName": "Sam"
   },
   "userName": "scarter@example.com",
   "displayName": "Sam Carter",
   "groups": [
     {
       "_id": "Accounting Managers"
     }
   ],
   "manager": [
     {
       "_id": "trigden",
       "displayName": "Torrey Rigden"
     }
   ]
 }'
 http://opendj.example.com:8080/users/scarter?_prettyPrint=true
{
  "_rev" : "00000000a1ee3da3",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1212",
    "emailAddress" : "scarter@example.com"
  },
  "_id" : "scarter",
  "name" : {
    "familyName" : "Carter",
    "givenName" : "Sam"
  },
  "userName" : "scarter@example.com",
  "displayName" : "Sam Carter",
  "meta" : {
    "lastModified" : "2013-04-12T07:47:45Z"
  },
  "groups" : [ {
    "_id" : "Accounting Managers"
  } ],
  "manager" : [ {
    "_id" : "trigden",
    "displayName" : "Torrey Rigden"
  } ]
}

To delete a resource, perform an HTTP DELETE on the resource URL. On success, the operation returns the resource you deleted.

$ curl
 --request DELETE
 --user kvaughan:bribery
 http://opendj.example.com:8080/users/newuser?_prettyPrint=true
{
  "_rev" : "000000003a5f3cb2",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1212",
    "emailAddress" : "newuser@example.com"
  },
  "_id" : "newuser",
  "name" : {
    "familyName" : "New",
    "givenName" : "User"
  },
  "userName" : "newuser@example.com",
  "displayName" : "New User",
  "meta" : {
    "created" : "2013-04-11T09:58:27Z"
  },
  "manager" : [ {
    "_id" : "kvaughan",
    "displayName" : "Kirsten Vaughan"
  } ]
}

To delete a resource only if the resource matches a particular version, use an If-Match: revision header.

$ curl
 --user kvaughan:bribery
 http://opendj.example.com:8080/users/newuser?_fields=_rev
{"_rev":"000000006d8d7358"}
$ curl
 --request DELETE
 --user kvaughan:bribery
 --header "If-Match: 000000006d8d7358"
 http://opendj.example.com:8080/users/newuser?_prettyPrint=true
{
  "_rev" : "00000000383f3cae",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1212",
    "emailAddress" : "newuser@example.com"
  },
  "_id" : "newuser",
  "name" : {
    "familyName" : "New",
    "givenName" : "User"
  },
  "userName" : "newuser@example.com",
  "displayName" : "New User",
  "meta" : {
    "created" : "2013-04-11T12:48:48Z"
  },
  "manager" : [ {
    "_id" : "kvaughan",
    "displayName" : "Kirsten Vaughan"
  } ]
}

$ ldapsearch --port 1389 --baseDN uid=nbohr,ou=people,dc=example,dc=com "(&)" dn
dn: uid=nbohr,ou=People,dc=example,dc=com

dn: cn=quantum dot,uid=nbohr,ou=People,dc=example,dc=com

dn: cn=qubit generator,uid=nbohr,ou=People,dc=example,dc=com

OpenDJ lets you patch JSON resources, updating part of the resource rather than replacing it. For example, you could change Babs Jensen's email address by issuing an HTTP PATCH request, as in the example that follows.

Notice that the data sent specifies the type of patch operation, the field to change, and a value that depends on the field you change and on the operation. A single-valued field takes an object, boolean, string, or number depending on its type, whereas a multi-valued field takes an array of values. Getting the type wrong results in an error. Also notice that the patch data is itself an array, since you could patch more than one part of the resource by using a set of patch operations in the same request.

$ curl
 --user kvaughan:bribery
 --request PATCH
 --header "Content-Type: application/json"
 --data '[
  {
    "operation": "replace",
    "field": "/contactInformation/emailAddress",
    "value": "babs@example.com"
  }
 ]'
 http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "_rev" : "00000000f3fdd370",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1862",
    "emailAddress" : "babs@example.com"
  },
  "_id" : "bjensen",
  "name" : {
    "familyName" : "Jensen",
    "givenName" : "Barbara"
  },
  "userName" : "babs@example.com",
  "displayName" : "Barbara Jensen",
  "meta" : {
    "lastModified" : "2013-05-13T14:35:31Z"
  },
  "manager" : [ {
    "_id" : "trigden",
    "displayName" : "Torrey Rigden"
  } ]
}

One key nuance in how patch works with OpenDJ has to do with multi-valued fields. Although JSON resources represent multi-valued fields as arrays, OpenDJ treats those values as sets. In other words, values in the field are unique, and the ordering of an array of values is not meaningful in the context of patch operations. If you reference array values by index, OpenDJ returns an error.^[5]

Instead use the patch operations as if arrays values were sets. For example, you can include Barbara Jensen in a group by adding her to the set of members.

$ curl
 --user kvaughan:bribery
 --request PATCH
 --header "Content-Type: application/json"
 --data '[
  {
    "operation": "add",
    "field": "/members",
    "value": [
      {
        "_id": "bjensen"
      }
    ]
  }
 ]'
 http://opendj.example.com:8080/groups/Directory%20Administrators
 ?_prettyPrint=true
{
  "_rev" : "00000000b70c881a",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "_id" : "Directory Administrators",
  "displayName" : "Directory Administrators",
  "meta" : {
    "lastModified" : "2013-05-13T16:40:23Z"
  },
  "members" : [ {
    "_id" : "kvaughan",
    "displayName" : "Kirsten Vaughan"
  }, {
    "_id" : "rdaugherty",
    "displayName" : "Robert Daugherty"
  }, {
    "_id" : "bjensen",
    "displayName" : "Barbara Jensen"
  }, {
    "_id" : "hmiller",
    "displayName" : "Harry Miller"
  } ]
}

Removing her from the group is similar.

$ curl
 --user kvaughan:bribery
 --request PATCH
 --header "Content-Type: application/json"
 --data '[
  {
    "operation": "remove",
    "field": "/members",
    "value": [
      {
        "_id": "bjensen"
      }
    ]
  }
 ]'
 http://opendj.example.com:8080/groups/Directory%20Administrators
 ?_prettyPrint=true
{
  "_rev" : "00000000e241797e",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "_id" : "Directory Administrators",
  "displayName" : "Directory Administrators",
  "meta" : {
    "lastModified" : "2013-05-13T16:40:55Z"
  },
  "members" : [ {
    "_id" : "kvaughan",
    "displayName" : "Kirsten Vaughan"
  }, {
    "_id" : "rdaugherty",
    "displayName" : "Robert Daugherty"
  }, {
    "_id" : "hmiller",
    "displayName" : "Harry Miller"
  } ]
}

You can use resource revision numbers in If-Match: revision headers to patch the resource only if the resource matches a particular version.

$ curl
 --user kvaughan:bribery
 "http://opendj.example.com:8080/users/bjensen?_prettyPrint=true&_fields=_rev"
{
  "_rev" : "00000000c1b6d4c7"
}
$ curl
 --user kvaughan:bribery
 --request PATCH
 --header "If-Match: 00000000c1b6d4c7"
 --header "Content-Type: application/json"
 --data '[
  {
    "operation": "add",
    "field": "/contactInformation/emailAddress",
    "value": "babs@example.com"
  }
 ]'
 http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "_rev" : "00000000f946d377",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1862",
    "emailAddress" : "babs@example.com"
  },
  "_id" : "bjensen",
  "name" : {
    "familyName" : "Jensen",
    "givenName" : "Barbara"
  },
  "userName" : "babs@example.com",
  "displayName" : "Barbara Jensen",
  "meta" : {
    "lastModified" : "2013-05-13T16:56:33Z"
  },
  "manager" : [ {
    "_id" : "trigden",
    "displayName" : "Torrey Rigden"
  } ]
}

The resource revision changes after you successfully perform the patch operation.

OpenDJ implements an action that lets the server set the resource ID on creation. To use this action, perform an HTTP POST with header Content-Type: application/json, _action=create in the query string, and the JSON content of your resource.

The following example creates a new user entry.

$ curl
 --request POST
 --user kvaughan:bribery
 --header "Content-Type: application/json"
 --data '{
  "_id": "newuser",
  "contactInformation": {
    "telephoneNumber": "+1 408 555 1212",
    "emailAddress": "newuser@example.com"
  },
  "name": {
    "familyName": "New",
    "givenName": "User"
  },
  "displayName": "New User",
  "manager": [
    {
      "_id": "kvaughan",
      "displayName": "Kirsten Vaughan"
    }
  ]
 }'
 "http://opendj.example.com:8080/users?_action=create&_prettyPrint=true"
{
  "_rev" : "0000000034a23ca7",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1212",
    "emailAddress" : "newuser@example.com"
  },
  "_id" : "newuser",
  "name" : {
    "familyName" : "New",
    "givenName" : "User"
  },
  "userName" : "newuser@example.com",
  "displayName" : "New User",
  "meta" : {
    "created" : "2013-04-11T11:19:08Z"
  },
  "manager" : [ {
    "_id" : "kvaughan",
    "displayName" : "Kirsten Vaughan"
  } ]
}

To query resource collections, perform an HTTP GET with a _queryFilter=filter parameter in your query string.

OpenDJ provides several different index types, each corresponding to a different type of search.

$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn~=Babs Jansen)" cn
dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen

$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=bjensen)" mail
dn: uid=bjensen,ou=People,dc=example,dc=com
mail: bjensen@example.com

$ ldapsearch --port 1389 --baseDN dc=example,dc=com
 "(&(uidNumber>=1120)(roomNumber>=4500))" uid
dn: uid=charvey,ou=People,dc=example,dc=com
uid: charvey

dn: uid=eward,ou=People,dc=example,dc=com
uid: eward

dn: uid=mvaughan,ou=People,dc=example,dc=com
uid: mvaughan

dn: uid=pchassin,ou=People,dc=example,dc=com
uid: pchassin

$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(aci=*)" -
dn: dc=example,dc=com

dn: ou=People,dc=example,dc=com

$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=Barb*)" cn
dn: uid=bfrancis,ou=People,dc=example,dc=com
cn: Barbara Francis

dn: uid=bhal2,ou=People,dc=example,dc=com
cn: Barbara Hall

dn: uid=bjablons,ou=People,dc=example,dc=com
cn: Barbara Jablonski

dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen

dn: uid=bmaddox,ou=People,dc=example,dc=com
cn: Barbara Maddox

You modify index configurations using the dsconfig command. The configuration changes then take effect after you rebuild the index according to the new configuration, using the rebuild-index. The dsconfig --help-database command lists subcommands for creating, reading, updating, and deleting index configuration.

$ dsconfig
 create-local-db-index
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --index-name description
 --set index-type:substring
 --trustAll
 --no-prompt

$ dsconfig
 set-local-db-index-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --index-name cn
 --set index-type:approximate
 --trustAll
 --no-prompt

$ dsconfig
 create-local-db-index
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --set index-type:extensible
 --set index-extensible-matching-rule:1.3.6.1.4.1.26027.1.4.5
 --set index-extensible-matching-rule:1.3.6.1.4.1.26027.1.4.6
 --index-name lastLoginTime
 --trustAll
 --no-prompt

8.2.2. Configuring a Virtual List View Index

In the OpenDJ Control Panel, select Manage Indexes > New VLV Index..., and then set up your VLV index using the New VLV Index window.

After you finish configuring your index and click OK, the Control Panel prompts you to make the additional changes necessary to complete the VLV index configuration, and then to build the index.

You can also create the equivalent index configuration using the dsconfig command.

$ dsconfig
 create-local-db-vlv-index
 --port 4444
 --hostname opendj.example.com
 --bindDn "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --index-name people-by-last-name
 --set base-dn:ou=People,dc=example,dc=com
 --set filter:"(|(givenName=*)(sn=*))"
 --set scope:single-level
 --set sort-order:"+sn +givenName"
 --trustAll
 --no-prompt

Note

When referring to a virtual list view (VLV) index after creation, you must add vlv. as a prefix. In other words, if you named the VLV index people-by-last-name, you refer to it as vlv.people-by-last-name when rebuilding indexes, changing index properties such as the index entry limit, or verifying indexes.

$ rebuild-index
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --baseDN dc=example,dc=com
 --index cn
 --start 0
Rebuild Index task 20110607171639867 scheduled to start Jun 7, 2011 5:16:39 PM

$ rebuild-index
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --baseDN dc=example,dc=com
 --rebuildDegraded
...
[31/Jan/2012:16:43:25 +0100] severity="NOTICE" msgCount=7 msgID=8847510
 message="Due to changes in the configuration, index
 dc_example_dc_com_description is currently operating in a degraded state
 and must be rebuilt before it can be used"
[31/Jan/2012:16:43:25 +0100] severity="NOTICE" msgCount=8 msgID=8847591
 message="Rebuild of all degraded indexes started with 160 total entries
 to process"
...
[31/Jan/2012:16:43:25 +0100] severity="NOTICE" msgCount=10 msgID=8847493
 message="Rebuild complete. Processed 160 entries in 0 seconds (average
 rate 1860.5/sec)"
...
Rebuild Index task 20120131164324838 has been successfully completed

$ dbtest
 list-index-status
 --backendID userRoot
 --baseDN dc=example,dc=com
 | grep newUnusedAttribute
newUnusedAttribute.equality   Index  ...newUnusedAttribute.equality   false...
newUnusedAttribute.presence   Index  ...newUnusedAttribute.presence   false...
newUnusedAttribute.substring  Index  ...newUnusedAttribute.substring  false...
$ rebuild-index
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --baseDN dc=example,dc=com
 --clearDegradedState
 --index newUnusedAttribute
 --start 0
Rebuild Index task 20130211175925012 scheduled to start Feb 11, 2013 5:59:25
 PM CET
$ dbtest
 list-index-status
 --backendID userRoot
 --baseDN dc=example,dc=com
 | grep newUnusedAttribute
newUnusedAttribute.equality   Index  ...newUnusedAttribute.equality   true...
newUnusedAttribute.presence   Index  ...newUnusedAttribute.presence   true...
newUnusedAttribute.substring  Index  ...newUnusedAttribute.substring  true...

$ dsconfig
 set-local-db-index-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --index-name objectClass
 --set index-entry-limit:5000
 --trustAll
 --no-prompt
$ rebuild-index
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --baseDN dc=example,dc=com
 --index objectclass
 --start 0
Rebuild Index task 20110607160349596 scheduled to start Jun 7, 2011 4:03:49 PM

You can verify that indexes correspond to current directory data, and that indexes do not contain errors using the verify-index command.

$ verify-index
 --baseDN dc=example,dc=com
 --index cn
 --clean
 --countErrors
[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
 msgID=9437595 msg=Local DB backend userRoot does not specify the number of
 lock tables: defaulting to 97
[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
 msgID=9437594 msg=Local DB backend userRoot does not specify the number of
 cleaner threads: defaulting to 24 threads
[07/Jun/2011:16:06:51 +0200] category=JEB severity=NOTICE msgID=8847461
 msg=Checked 1316 records and found 0 error(s) in 0 seconds
 (average rate 2506.7/sec)
[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
 msgID=8388710 msg=Number of records referencing more than one entry: 315
[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
 msgID=8388711 msg=Number of records that exceed the entry limit: 0
[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
 msgID=8388712 msg=Average number of entries referenced is 1.58/record
[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
 msgID=8388713 msg=Maximum number of entries referenced by any
 record is 32

When searching, you can improve performance by making sure your search is indexed as you expect. One way of checking is to request the debugsearchindex attribute in your results.

$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 "(uid=bjensen)"
 debugsearchindex
dn: cn=debugsearch
debugsearchindex: filter=(uid=bjensen)[INDEX:uid.equality:uid.equality][COUNT:1:1]
 final=[COUNT:1:1]

When you request the debugsearchindex attribute, instead of performing the search, OpenDJ returns debug information indicating how it would process the search operation. In the example above you notice OpenDJ hits the equality index for uid right away.

A less exact search requires more work from OpenDJ. In the following example OpenDJ would have to return 160 entries.

$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 "(uid=*)"
 debugsearchindex
dn: cn=debugsearch
debugsearchindex: filter=(uid=*)[NOT-INDEXED] scope=wholeSubtree[COUNT:160:160]
 final=[COUNT:160:160]

By default OpenDJ rejects unindexed searches when the number of candidate entries goes beyond the search or look-though limit.

When you first install OpenDJ directory server and import your data from LDIF, the following indexes are configured.

When you create a JE backend using the dsconfig command, OpenDJ creates the aci presence, ds-sync-conflict equality, ds-sync-hist ordering, entryUUID equality, and objectClass equality indexes automatically.

You can set up replication during installation by choosing to configure replication through the setup wizard.

In the Topology Options screen for the first server you set up, select This server will be part of a replication topology. If you also choose Configure as Secure, then replication traffic is protected by SSL.

In the Topology Options screen for subsequent servers, also select There is already a server in the topology, providing the Host Name, Administration Connector Port number, Admin User, and Admin Password for the first replica you set up.

You also set up a global administrator account, stored under cn=admin data across replicas, used to manage replication in the topology.

You further set up what to replicate.

Once replication is set up, it works for all the replicas. You can monitor the replication connection and status through the OpenDJ Control Panel.

Before you take replication further than setting up replication in the setup wizard, read this section to learn more about how OpenDJ replication works.

9.2.2. Replication Per Suffix

The primary unit of replication is the suffix, specified by a base DN such as dc=example,dc=com.^[7] Replication also depends on the directory schema, defined on cn=schema, and the cn=admin data suffix with administrative identities and certificates for protecting communications. Thus that content gets replicated as well.

The set of OpenDJ servers replicating data for a given suffix is called a replication topology. You can have more than one replication topology. For example, one topology could be devoted to dc=example,dc=com, and another to dc=example,dc=org. OpenDJ servers are capable of serving more than one suffix. They are also capable of participating in more than one replication topology.

Within a replication topology, the suffixes being replicated are identified to the replication servers by their DN. As all the replication servers are fully connected in a topology, a consequence is that it is impossible to have multiple "sub-topologies" within the overall set of servers as illustrated in the following diagram.

This section shows how to configure replication with command-line tools.

$ dsreplication
 enable
 --adminUID admin
 --adminPassword password
 --baseDN dc=example,dc=com
 --host1 opendj.example.com
 --port1 4444
 --bindDN1 "cn=Directory Manager"
 --bindPassword1 password
 --replicationPort1 8989
 --host2 opendj2.example.com
 --port2 4444
 --bindDN2 "cn=Directory Manager"
 --bindPassword2 password
 --replicationPort2 8989
 --trustAll
 --no-prompt

Establishing connections ..... Done.
Checking registration information ..... Done.
Updating remote references on server opendj.example.com:4444 ..... Done.
Configuring Replication port on server opendj2.example.com:4444 ..... Done.
Updating replication configuration for baseDN dc=example,dc=com on server
 opendj.example.com:4444 ..... Done.
Updating replication configuration for baseDN dc=example,dc=com on server
 opendj2.example.com:4444 ..... Done.
Updating registration configuration on server
 opendj.example.com:4444 ..... Done.
Updating registration configuration on server
 opendj2.example.com:4444 ..... Done.
Updating replication configuration for baseDN cn=schema on server
 opendj.example.com:4444 ..... Done.
Updating replication configuration for baseDN cn=schema on server
 opendj2.example.com:4444 ..... Done.
Initializing registration information on server opendj2.example.com:4444 with
 the contents of server opendj.example.com:4444 ..... Done.
Initializing schema on server opendj2.example.com:4444 with the contents of
 server opendj.example.com:4444 ..... Done.

Replication has been successfully enabled.  Note that for replication to
 work you must initialize the contents of the base DN's that are being
  replicated (use dsreplication initialize to do so).

See
/var/.../opends-replication-7958637258600693490.log
for a detailed log of this operation.

9.3.4. Stand-alone Replication Servers

Replication in OpenDJ is designed to be both easy to implement in environments with a few servers, and also scalable in environments with many servers. You can enable the replication service on each OpenDJ directory server in your deployment, for example, to limit the number of servers you deploy. Yet in a large deployment, you can use stand-alone replication servers — OpenDJ servers that do nothing but relay replication messages — to configure (and troubleshoot) the replication service separately from the directory service. You only need a few stand-alone replication servers publishing changes to serve many directory servers subscribed to the changes. Furthermore, replication is designed such that you need only connect a directory server to the nearest replication server for the directory server to replicate with all others in your topology. Yet only the stand-alone replication servers participate in fully-meshed replication.

All replication servers in a topology are connected to all other replication servers. Directory servers are connected only to one replication server at a time, and their connections should be to replication servers on the same LAN. Therefore the total number of replication connections, Total_conn is expressed as follows.

Equation 9.1. 

Total_conn = (N_RS * N_RS-1)/2 + N_DS

Here, N_RS is the number of replication servers, and N_DS is the number of stand-alone directory servers. In other words, if you have only 3 servers, then Total_conn is 3 with no stand-alone servers. However, if you have two data centers, and need 12 directory servers, then with no stand-alone directory servers Total_conn is (12 * 11)/2 or 66. Yet, with 4 stand-alone replication servers, and 12 stand-alone directory servers, Total_conn is (4 * 3)/2 + 12, or 18, with only four of those connections needing to go over the WAN. (By running four directory servers that also run replication servers and eight stand-alone directory servers, you reduce the number of replication connections to 14 for 12 replicas.)

Tip

If you set up OpenDJ directory server to replicate by using the Quick Setup wizard, then the wizard activated the replication service for that server. You can turn off the replication service on OpenDJ directory server, and then configure the server to work with a separate, stand-alone replication server instead. Start by using the dsreplication disable --disableReplicationServer command to turn off the replication service on the server.

Procedure 9.6. To Set Up a Stand-alone Replication Server

This example sets up a stand-alone replication server to handle the replication traffic between two directory servers that do not handle replication themselves.

Here the replication server is rs.example.com. The directory servers are opendj.example.com and opendj2.example.com.

In a real deployment, you would have more replication servers to avoid a single point of failure.

1. Setup the replication server as a directory server that has no database.

2. Setup the directory servers as stand-alone directory servers.

3. Enable replication with the appropriate --noReplicationServer and --onlyReplicationServer options.

   $ dsreplication
    enable
    --adminUID admin
    --adminPassword password
    --baseDN dc=example,dc=com
    --host1 opendj.example.com
    --port1 4444
    --bindDN1 "cn=Directory Manager"
    --bindPassword1 password
    --noReplicationServer1
    --host2 rs.example.com
    --port2 4444
    --bindDN2 "cn=Directory Manager"
    --bindPassword2 password
    --replicationPort2 8989
    --onlyReplicationServer2
    --trustAll
    --no-prompt
   Establishing connections ..... Done.
   Only one replication server will be defined for the following base DN's:
   dc=example,dc=com
   It is recommended to have at least two replication servers (two changelogs) to
   avoid a single point of failure in the replication topology.
   
   Checking registration information ..... Done.
   Configuring Replication port on server rs.example.com:4444 ..... Done.
   Updating replication configuration for baseDN dc=example,dc=com on server
    opendj.example.com:4444 ..... Done.
   Updating registration configuration on server
    opendj.example.com:4444 ..... Done.
   Updating registration configuration on server
    rs.example.com:4444 ..... Done.
   Updating replication configuration for baseDN cn=schema on server
    opendj.example.com:4444 ..... Done.
   Initializing registration information on server rs.example.com:4444 with
    the contents of server opendj.example.com:4444 ..... Done.
   
   Replication has been successfully enabled.  Note that for replication to work
    you must initialize the contents of the base DN's that are being
    replicated (use dsreplication initialize to do so).
   
   See
   /var/.../opends-replication-1720959352638609971.log
   for a detailed log of this operation.
   
   $ dsreplication
    enable
    --adminUID admin
    --adminPassword password
    --baseDN dc=example,dc=com
    --host1 opendj2.example.com
    --port1 4444
    --bindDN1 "cn=Directory Manager"
    --bindPassword1 password
    --noReplicationServer1
    --host2 rs.example.com
    --port2 4444
    --bindDN2 "cn=Directory Manager"
    --bindPassword2 password
    --replicationPort2 8989
    --onlyReplicationServer2
    --trustAll
    --no-prompt
   
   Establishing connections ..... Done.
   Only one replication server will be defined for the following base DN's:
   dc=example,dc=com
   It is recommended to have at least two replication servers (two changelogs) to
   avoid a single point of failure in the replication topology.
   
   Checking registration information ..... Done.
   Updating remote references on server rs.example.com:4444 ..... Done.
   Updating replication configuration for baseDN dc=example,dc=com on server
    opendj2.example.com:4444 ..... Done.
   Updating replication configuration for baseDN dc=example,dc=com on server
    opendj.example.com:4444 ..... Done.
   Updating registration configuration on server
    opendj2.example.com:4444 ..... Done.
   Updating registration configuration on server
    rs.example.com:4444 ..... Done.
   Updating registration configuration on server
    opendj.example.com:4444 ..... Done.
   Updating replication configuration for baseDN cn=schema on server
    opendj2.example.com:4444 ..... Done.
   Updating replication configuration for baseDN cn=schema on server
    opendj.example.com:4444 ..... Done.
   Initializing registration information on server opendj2.example.com:4444 with
    the contents of server rs.example.com:4444 ..... Done.
   
   Replication has been successfully enabled.  Note that for replication to work
    you must initialize the contents of the base DN's that are being
    replicated (use dsreplication initialize to do so).
   
   See
   /var/folders/.../opends-replication-5893037538856033562.log
   for a detailed log of this operation.

4. Initialize replication from one of the directory servers.

   $ dsreplication
    initialize-all
    --adminUID admin
    --adminPassword password
    --baseDN dc=example,dc=com
    --hostname opendj.example.com
    --port 4444
    --trustAll
    --no-prompt
   
   Initializing base DN dc=example,dc=com with the contents from
    opendj.example.com:4444: 160 entries processed (100 % complete).
   Base DN initialized successfully.
   
   See
   /var/.../opends-replication-7677303986403997574.log
   for a detailed log of this operation.

$ dsconfig
 set-global-configuration-prop
 --port 4444
 --hostname opendj2.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --set writability-mode:internal-only
 --trustAll
 --no-prompt

$ dsconfig
 set-replication-domain-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --provider-name "Multimaster Synchronization"
 --domain-name "dc=example,dc=com"
 --trustAll
 --no-prompt
 --set
 fractional-include:inetorgperson:cn,givenname,mail,mobile,sn,telephonenumber

$ dsconfig
 set-replication-domain-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --provider-name "Multimaster Synchronization"
 --domain-name "dc=example,dc=com"
 --set fractional-exclude:*:sessionToken
 --trustAll
 --no-prompt

Some applications require notification when directory data updates occur. For example, an application might need to sync directory data with another database, or the application might need to kick off other processing when certain updates occur.

In addition to supporting persistent search operations, OpenDJ provides an external change log mechanism to allow applications to be notified of changes to directory data.

The external change log can also work for applications that follow the Internet-Draft: Definition of an Object Class to Hold LDAP Change Records. Nothing special is required to get the objects specified for this legacy format. Such applications cannot however use the change log cookies that are shared across the replication topology, and therefore can continue to be used after failover to another replica in a multi-master replication environment.

A bak/ directory is provided when you install OpenDJ, as a location to save binary backups. When you create a backup, the bak/backup.info contains information about the archive.

Archives produced by the backup command contain backups only of the directory data. Backups of server configuration are found in config/archived-configs/.

When you restore data, the procedure to follow depends on whether the OpenDJ directory server is replicated.

OpenDJ password policies govern not only passwords, but also account lockout, and how OpenDJ provides notification about account status.

OpenDJ supports password policies as part of the server configuration, and also subentry password policies as part of the (replicated) user data.

$ dsconfig
 get-password-policy-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --policy-name "Default Password Policy"
 --advanced
Property                                  : Value(s)
------------------------------------------:--------------------------
account-status-notification-handler       : -
allow-expired-password-changes            : false
allow-multiple-password-values            : false
allow-pre-encoded-passwords               : false
allow-user-password-changes               : true
default-password-storage-scheme           : Salted SHA-1
deprecated-password-storage-scheme        : -
expire-passwords-without-warning          : false
force-change-on-add                       : false
force-change-on-reset                     : false
grace-login-count                         : 0
idle-lockout-interval                     : 0 s
last-login-time-attribute                 : -
last-login-time-format                    : -
lockout-duration                          : 0 s
lockout-failure-count                     : 0
lockout-failure-expiration-interval       : 0 s
max-password-age                          : 0 s
max-password-reset-age                    : 0 s
min-password-age                          : 0 s
password-attribute                        : userpassword
password-change-requires-current-password : false
password-expiration-warning-interval      : 5 d
password-generator                        : Random Password Generator
password-history-count                    : 0
password-history-duration                 : 0 s
password-validator                        : -
previous-last-login-time-format           : -
require-change-by-time                    : -
require-secure-authentication             : false
require-secure-password-changes           : false
skip-validation-for-administrators        : false
state-update-failure-policy               : reactive

$ ldapsearch
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --baseDN dc=example,dc=com
 uid=bjensen
 userpassword
dn: uid=bjensen,ou=People,dc=example,dc=com
userpassword: {SSHA}QWAtw8ch/9850HNFRRqLNMIQc1YhxCnOoGmk1g==

$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen pwdPolicySubentry
dn: uid=bjensen,ou=People,dc=example,dc=com
pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config

You configure server based password policies using the dsconfig command. Notice that server based password policies are part of the server configuration, and therefore not replicated. Alternatively, you can configure a subset of password policy features using subentry based password policies that are stored with the replicated server data. This section covers both server based and subentry based password policies.

You assign subentry based password policies for a subtree of the DIT by adding the policy to an LDAP subentry whose immediate superior is the root of the subtree. In other words you can add the subtree based password policy under ou=People,dc=example,dc=com, to have it apply to all entries under ou=People,dc=example,dc=com. You can further use the capabilities of LDAP subentries to refine the scope of application.

You assign server based password policies by using the ds-pwp-password-policy-dn attribute.

Password generators are used by OpenDJ during the LDAP password modify extended operation to construct a new password for the user. In other words, a directory administrator resetting a user's password can have OpenDJ directory server generate the new password.

$ ldappasswordmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --authzID "u:bjensen"
The LDAP password modify operation was successful
Generated Password:  eak77qdi

The default password policy shown in Procedure 11.1, "To Adjust the Default Password Policy" uses the Random Password Generator.

$ dsconfig
 get-password-policy-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --policy-name "Default Password Policy"
 --property password-generator
Property           : Value(s)
-------------------:--------------------------
password-generator : Random Password Generator
$ dsconfig
 get-password-generator-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --generator-name "Random Password Generator"
 --property password-generator
 Property               : Value(s)
-----------------------:-----------------------------------------------------
enabled                : true
password-character-set : alpha:abcdefghijklmnopqrstuvwxyz, numeric:0123456789
password-format        : "alpha:3,numeric:2,alpha:3"

Notice that the default configuration for the Random Password Generator defines two password-character-set values, and then uses those definitions in the password-format so that generated passwords have eight characters: three from the alpha set, followed by two from the numeric set, followed by three from the alpha set. The password-character-set name must be ASCII.

To set the password generator that OpenDJ employs when constructing a new password for a user, set the password-generator property for the password policy that applies to the user.

The following example does not change the password policy, but instead changes the Random Password Generator configuration, and then demonstrates a password being generated upon reset.

$ dsconfig
 set-password-generator-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --generator-name "Random Password Generator"
 --remove password-character-set:alpha:abcdefghijklmnopqrstuvwxyz
 --add
  password-character-set:alpha:ABCDEFGHIJKLMNOPQRSTUVWabcdefghijklmnopqrstuvwxyz
 --add password-character-set:punct:,./\`!@#\$%^&*:\;[]\"\'\(\)+=-_~\\
 --set
  password-format:alpha:3,punct:1,numeric:2,punct:2,numeric:3,alpha:3,punct:2
 --no-prompt
$ ldappasswordmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --authzID "u:bjensen"
The LDAP password modify operation was successful
Generated Password:  pld^06:)529HTq$'

If you also set up a password validator in the password policy as shown in Procedure 11.1, "To Adjust the Default Password Policy" and further described in Section 11.6, "Configuring Password Validation", make sure the generated passwords are acceptable to the validator.

Password storage schemes encode new passwords provided by users so that they are stored in an encoded manner. This makes it difficult or impossible for someone to determine the clear-text passwords from the encoded values. Password storage schemes also determine whether a clear-text password provided by a client matches the encoded value stored in the server.

OpenDJ offers a variety of both reversible and one-way password storage schemes. Some schemes make it easy to recover the clear-text password, whereas others aim to make it computationally hard to do so.

$ dsconfig
 list-password-storage-schemes
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password

Password Storage Scheme : Type          : enabled
------------------------:---------------:--------
3DES                    : triple-des    : true
AES                     : aes           : true
Base64                  : base64        : true
Blowfish                : blowfish      : true
Clear                   : clear         : true
CRYPT                   : crypt         : true
MD5                     : md5           : true
PBKDF2                  : pbkdf2        : true
RC4                     : rc4           : true
Salted MD5              : salted-md5    : true
Salted SHA-1            : salted-sha1   : true
Salted SHA-256          : salted-sha256 : true
Salted SHA-384          : salted-sha384 : true
Salted SHA-512          : salted-sha512 : true
SHA-1                   : sha1          : true

As shown in Procedure 11.1, "To Adjust the Default Password Policy", the default password storage scheme for users in Salted SHA-1. When you add users or import user entries with userPassword values in clear text, OpenDJ hashes them with the default password storage scheme. Root DN users have a different password policy by default, shown in Procedure 11.5, "To Assign a Password Policy to a Group". The Root Password Policy uses Salted SHA-512 by default.

You change the default password policy storage scheme for users by changing the applicable password policy, as shown in the following example.

$ dsconfig
 set-password-policy-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --policy-name "Default Password Policy"
 --set default-password-storage-scheme:pbkdf2
 --no-prompt

Notice that the change in default password storage scheme does not cause OpenDJ to update any stored password values. By default, OpenDJ only stores a password with the new storage scheme the next time that the password is changed.

OpenDJ prefixes passwords with the scheme used to encode them, which means it is straightforward to see which password storage scheme is in use. After the default password storage scheme is changed to PBKDF2, old user passwords remain encoded with Salted SHA-1.

$ ldapsearch
 --port 1389
 --bindDN uid=bjensen,ou=people,dc=example,dc=com
 --bindPassword hifalutin
 --baseDN dc=example,dc=com
 "(uid=bjensen)" userPassword
dn: uid=bjensen,ou=People,dc=example,dc=com
userPassword: {SSHA}Rc3tkAj1qP5zGiRkwDIWDFxrxpGgO8Fwh3aibg==

When the password is changed, the new default password storage scheme takes effect, as shown in the following example.

$ ldappasswordmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --authzID "u:bjensen"
 --newPassword changeit
The LDAP password modify operation was successful
$ ldapsearch
 --port 1389
 --bindDN uid=bjensen,ou=people,dc=example,dc=com
 --bindPassword changeit
 --baseDN dc=example,dc=com
 "(uid=bjensen)" userPassword
dn: uid=bjensen,ou=People,dc=example,dc=com
userPassword: {PBKDF2}10000:O3V6G7y7n7AefOkRGNKQ5ukrMuO5uf+iEQ9ZLg==

When you change the password storage scheme for users, realize that the user passwords must change in order for OpenDJ to encode them with the chosen storage scheme. If you are changing the storage scheme because the old scheme was too weak, then you no doubt want users to change their passwords anyway.

If however the storage scheme change is not related to vulnerability, you can use the deprecated-password-storage-scheme property of the password policy to have OpenDJ store the password in the new format after successful authentication. This makes it possible to do password migration for active users without forcing users to change their passwords.

$ ldapsearch
 --port 1389
 --bindDN uid=kvaughan,ou=people,dc=example,dc=com
 --bindPassword bribery
 --baseDN dc=example,dc=com
 "(uid=kvaughan)" userPassword
dn: uid=kvaughan,ou=People,dc=example,dc=com
userPassword: {SSHA}hDgK44F2GhIIZj913b+29Ak7phb9oU3Lz4ogkg==

$ dsconfig
 set-password-policy-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --policy-name "Default Password Policy"
 --set deprecated-password-storage-scheme:"Salted SHA-1"
 --no-prompt
$ ldapsearch
 --port 1389
 --bindDN uid=kvaughan,ou=people,dc=example,dc=com
 --bindPassword bribery
 --baseDN dc=example,dc=com
 "(uid=kvaughan)" userPassword
dn: uid=kvaughan,ou=People,dc=example,dc=com
userPassword: {PBKDF2}10000:L4dCYqSsNnf47YZ3a6aC8K2E3DChhHHhpcoUzg==

Notice that with deprecated-password-storage-scheme set appropriately, Kirsten Vaughan's password was hashed again after she authenticated successfully.

Password validators are responsible for determining whether a proposed password is acceptable for use and can run checks like ensuring the password meets minimum length requirements, that it has an appropriate range of characters, or that it is not in the history. OpenDJ directory server provides a variety of password validators.

$ dsconfig
 list-password-validators
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password


Password Validator                  : Type                : enabled
------------------------------------:---------------------:--------
Attribute Value                     : attribute-value     : true
Character Set                       : character-set       : true
Dictionary                          : dictionary          : false
Length-Based Password Validator     : length-based        : true
Repeated Characters                 : repeated-characters : true
Similarity-Based Password Validator : similarity-based    : true
Unique Characters                   : unique-characters   : true

The password policy for a user specifies the set of password validators that should be used whenever that user provides a new password. By default no password validators are configured. You can see an example setting the Default Password Policy to use the Dictionary validator in Procedure 11.1, "To Adjust the Default Password Policy". The following example shows how to set up a custom password validator and assign it to the default password policy.

Notice how the character-set values are constructed. The initial 0: means the set is optional, whereas 1: would mean the set is required.

$ dsconfig
 create-password-validator
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --validator-name "Custom Character Set Password Validator"
 --set allow-unclassified-characters:true
 --set enabled:true
 --set character-set:0:abcdefghijklmnopqrstuvwxyz
 --set character-set:0:ABCDEFGHIJKLMNOPQRSTUVWXYZ
 --set character-set:0:0123456789
 --set character-set:0:!\"#\$%&\'\(\)*+,-./:\;\\<=\>?@[\\]^_\`{\|}~
 --set min-character-sets:3
 --type character-set
 --no-prompt

$ dsconfig
 set-password-policy-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --policy-name "Default Password Policy"
 --set password-validator:"Custom Character Set Password Validator"
 --no-prompt

$ ldappasswordmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --authzID "u:bjensen"
 --newPassword '!ABcd$%^'

In the preceding example, the character set of ASCII punctuation, !\"#\$%&\'\(\)*+,-./:\;\\<=\>?@[\\]^_\`{\|}~, is hard to read because of all the escape characters. In practice it can be easier to enter sequences like that by using dsconfig in interactive mode, and letting it do the escaping for you. You can also use the --commandFilePath {path} option to save the result of your interactive session to a file for use in scripts later.

An attempt to set an invalid password fails as shown in the following example.

$ ldappasswordmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --authzID "u:bjensen"
 --newPassword hifalutin
 The LDAP password modify operation failed with result code 19
Error Message:  The provided new password failed the validation checks defined
in the server:  The provided password did not contain characters from at least
3 of the following character sets or ranges: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ',
'!"#$%&'()*+,-./:;<=\>?@[\]^_`{|}~', '0123456789', 'abcdefghijklmnopqrstuvwxyz'

Validation does not affect existing passwords, but only takes effect when the password is updated.

Account lockout is configured as part of password policy. This section demonstrates configuring account lockout as part of the default password policy. Users are allowed three consecutive failures before being locked out for five minutes. Failures themselves also expire after five minutes.

Change the default password policy to activate lockout using the dsconfig command. As the password policy is part of the server configuration, you must manually apply the changes to each replica in a replication topology.

$ dsconfig
 set-password-policy-prop
 --port 4444
 --hostname `hostname`
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --policy-name "Default Password Policy" 
 --set lockout-failure-count:3
 --set lockout-duration:5m 
 --set lockout-failure-expiration-interval:5m
 --trustAll
 --no-prompt

Users having the default password policy are then locked out after three failed attempts in succession.

$ ldapsearch
 --port 1389
 --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
 --bindPassword hifalutin
 --baseDN dc=example,dc=com
 uid=bjensen
 mail
dn: uid=bjensen,ou=People,dc=example,dc=com
mail: bjensen@example.com

$ ldapsearch
 --port 1389
 --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
 --bindPassword fatfngrs
 --baseDN dc=example,dc=com
 uid=bjensen
 mail
The simple bind attempt failed
Result Code:  49 (Invalid Credentials)
$ ldapsearch
 --port 1389
 --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
 --bindPassword fatfngrs
 --baseDN dc=example,dc=com
 uid=bjensen
 mail
The simple bind attempt failed
Result Code:  49 (Invalid Credentials)
$ ldapsearch
 --port 1389
 --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
 --bindPassword fatfngrs
 --baseDN dc=example,dc=com
 uid=bjensen
 mail
The simple bind attempt failed
Result Code:  49 (Invalid Credentials)
$ ldapsearch
 --port 1389
 --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
 --bindPassword hifalutin
 --baseDN dc=example,dc=com
 uid=bjensen
 mail
The simple bind attempt failed
Result Code:  49 (Invalid Credentials)

This section covers disabling and enabling accounts by using the manage-account command. Password reset is covered in the chapter on performing LDAP operations.

For the following examples, the directory admin user, Kirsten Vaughan, has ds-privilege-name: password-reset, and the following ACI on ou=People,dc=example,dc=com.

(target="ldap:///ou=People,dc=example,dc=com") (targetattr ="*||+")(
version 3.0;acl "Admins can run amok"; allow(all) groupdn =
"ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)

OpenDJ can send mail about account status changes. OpenDJ needs an SMTP server to send messages, and needs templates for the mail it sends. By default, message templates are in English, under /path/to/opendj/config/messages/.

OpenDJ generates notifications only when OpenDJ writes to an entry or evaluates a user entry for authentication. OpenDJ generates account enabled and account disabled notifications when the user account is enabled or disabled with the manage-account command, which writes to the entry. OpenDJ generates password expiration notifications when a user tries to bind.

For example, if you set up OpenDJ to send a notification about password expiration, that notification gets triggered when the user authenticates during the password expiration warning interval. OpenDJ does not automatically scan entries to send password expiry notifications. OpenDJ does implement controls that you can pass in an LDAP search to determine whether a user's password is about to expire. See the appendix on LDAP Controls for a list. You can send notifications then based on the results of your search.

Well-written directory client applications limit the scope of their searches with filters that narrow the number of results returned. By default, OpenDJ also only allows users with appropriate privileges to perform unindexed searches.

You can further adjust additional limits on search operations, such as the following.

If you have applications that leave connections open for long periods, OpenDJ can end up devoting resources to maintaining connections that are no longer used. If your network does not drop such connections eventually, you can configure OpenDJ to drop them by setting the global configuration property, idle-time-limit. By default, no idle time limit is set.

$ dsconfig
 set-global-configuration-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --set idle-time-limit:24h
 --trustAll
 --no-prompt

The example shown sets the idle time limit to 24 hours.

The default maximum request size of 5 MB, set using the advanced connection handler property max-request-size, is sufficient to satisfy most client requests. Yet, there are some cases where you might need to raise the request size limit. For example, if clients add groups with large numbers of members, those add requests can go beyond the 5 MB limit.

$ dsconfig
 set-connection-handler-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name "LDAP Connection Handler"
 --set max-request-size:20mb
 --trustAll
 --no-prompt

The example shown sets the maximum request size on the LDAP connection handler to 20 MB.

A static group is expressed as an entry that enumerates all the entries that belong to the group. Static group entries grow as their membership increases.

Static group entries can take the standard object class groupOfNames where each member attribute value is a distinguished name of an entry, or groupOfUniqueNames where each uniqueMember attribute value has Name and Optional UID syntax.^[8] Like other LDAP attributes, member and uniqueMember attributes take sets of unique values.

Static group entries can also have the object class groupOfEntries, which is like groupOfNames except that it is designed to allow groups not to have members.

When creating a group entry, use groupOfNames or groupOfEntries where possible.

To create a static group, add a group entry such as the following to the directory.

$ cat static.ldif 
dn: cn=My Static Group,ou=Groups,dc=example,dc=com
cn: My Static Group
objectClass: groupOfNames
objectClass: top
ou: Groups
member: uid=ahunter,ou=People,dc=example,dc=com
member: uid=bjensen,ou=People,dc=example,dc=com
member: uid=tmorris,ou=People,dc=example,dc=com

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --defaultAdd
 --filename static.ldif 
Processing ADD request for cn=My Static Group,ou=Groups,dc=example,dc=com
ADD operation successful for DN cn=My Static Group,ou=Groups,dc=example,dc=com

To change group membership, modify the values of the membership attribute.

$ cat add2grp.ldif 
dn: cn=My Static Group,ou=Groups,dc=example,dc=com
changetype: modify
add: member
member: uid=scarter,ou=People,dc=example,dc=com

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --filename add2grp.ldif 
Processing MODIFY request for cn=My Static Group,ou=Groups,dc=example,dc=com
MODIFY operation successful for DN
 cn=My Static Group,ou=Groups,dc=example,dc=com
$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 "(cn=My Static Group)"
dn: cn=My Static Group,ou=Groups,dc=example,dc=com
ou: Groups
objectClass: groupOfNames
objectClass: top
member: uid=ahunter,ou=People,dc=example,dc=com
member: uid=bjensen,ou=People,dc=example,dc=com
member: uid=tmorris,ou=People,dc=example,dc=com
member: uid=scarter,ou=People,dc=example,dc=com
cn: My Static Group

RFC 4519 says a groupOfNames entry must have at least one member. Although OpenDJ allows you to create a groupOfNames without members, strictly speaking that behavior is not standard. Alternatively, you can use the groupOfEntries object class as shown in the following example.

$ cat group-of-entries.ldif
dn: cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
cn: Initially Empty Static Group
objectClass: groupOfEntries
objectClass: top
ou: Groups

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --defaultAdd
 --filename group-of-entries.ldif
Processing ADD request for
 cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
ADD operation successful for DN
 cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
$ cat add-members.ldif
# Now add some members to the group.
dn: cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
changetype: modify
add: member
member: uid=ahunter,ou=People,dc=example,dc=com
member: uid=bjensen,ou=People,dc=example,dc=com
member: uid=tmorris,ou=People,dc=example,dc=com
member: uid=scarter,ou=People,dc=example,dc=com

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --filename add-members.ldif
Processing MODIFY request for
 cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
MODIFY operation successful for DN
 cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com

A dynamic group specifies members using LDAP URLs. Dynamic groups entries can stay small even as their membership increases.

Dynamic group entries take the groupOfURLs object class, with one or more memberURL values specifying LDAP URLs to identify group members.

To create a dynamic group, add a group entry such as the following to the directory.

The following example builds a dynamic group of entries effectively matching the filter "(l=Cupertino)" (users whose location is Cupertino). Change the filter if your data is different, and so no entries have l: Cupertino.

$ cat dynamic.ldif
dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com
cn: My Dynamic Group
objectClass: top
objectClass: groupOfURLs
ou: Groups
memberURL: ldap:///ou=People,dc=example,dc=com??sub?l=Cupertino

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --defaultAdd
 --filename dynamic.ldif 
Processing ADD request for cn=My Dynamic Group,ou=Groups,dc=example,dc=com
ADD operation successful for DN cn=My Dynamic Group,ou=Groups,dc=example,dc=com

Group membership changes dynamically as entries change to match the memberURL values.

$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 "(&(uid=*jensen)(isMemberOf=cn=My Dynamic Group,ou=Groups,dc=example,dc=com))"
 mail
dn: uid=bjensen,ou=People,dc=example,dc=com
mail: bjensen@example.com

dn: uid=rjensen,ou=People,dc=example,dc=com
mail: rjensen@example.com

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
dn: uid=ajensen,ou=People,dc=example,dc=com
changetype: modify
replace: l
l: Cupertino

Processing MODIFY request for uid=ajensen,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=ajensen,ou=People,dc=example,dc=com
^D
$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 "(&(uid=*jensen)(isMemberOf=cn=My Dynamic Group,ou=Groups,dc=example,dc=com))"
 mail
dn: uid=ajensen,ou=People,dc=example,dc=com
mail: ajensen@example.com

dn: uid=bjensen,ou=People,dc=example,dc=com
mail: bjensen@example.com

dn: uid=rjensen,ou=People,dc=example,dc=com
mail: rjensen@example.com

OpenDJ lets you create virtual static groups, which let applications see dynamic groups as what appear to be static groups.

The virtual static group takes auxiliary object class ds-virtual-static-group. Virtual static groups also take either the object class groupOfNames, or groupOfUniqueNames, but instead of having member or uniqueMember attributes, have ds-target-group-dn attributes pointing to other groups.

Generating the list of members can be resource intensive for large groups, so by default you cannot retrieve the list of members. You can change this with the dsconfig command by setting the Virtual Static member or Virtual Static uniqueMember property.

$ dsconfig
 set-virtual-attribute-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --name "Virtual Static member"
 --set allow-retrieving-membership:true
 --trustAll
 --no-prompt

The following example creates a virtual static group, and reads the group entry with all members.

$ cat virtual.ldif 
dn: cn=Virtual Static,ou=Groups,dc=example,dc=com
cn: Virtual Static
objectclass: top
objectclass: groupOfNames
objectclass: ds-virtual-static-group
ds-target-group-dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --defaultAdd
 --filename virtual.ldif
Processing ADD request for cn=Virtual Static,ou=Groups,dc=example,dc=com
ADD operation successful for DN cn=Virtual Static,ou=Groups,dc=example,dc=com
$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=Virtual Static)"
dn: cn=Virtual Static,ou=Groups,dc=example,dc=com
objectClass: groupOfNames
objectClass: ds-virtual-static-group
objectClass: top
member: uid=jwalker,ou=People,dc=example,dc=com
member: uid=jmuffly,ou=People,dc=example,dc=com
member: uid=tlabonte,ou=People,dc=example,dc=com
member: uid=dakers,ou=People,dc=example,dc=com
member: uid=jreuter,ou=People,dc=example,dc=com
member: uid=rfisher,ou=People,dc=example,dc=com
member: uid=pshelton,ou=People,dc=example,dc=com
member: uid=rjensen,ou=People,dc=example,dc=com
member: uid=jcampaig,ou=People,dc=example,dc=com
member: uid=mjablons,ou=People,dc=example,dc=com
member: uid=mlangdon,ou=People,dc=example,dc=com
member: uid=aknutson,ou=People,dc=example,dc=com
member: uid=bplante,ou=People,dc=example,dc=com
member: uid=awalker,ou=People,dc=example,dc=com
member: uid=smason,ou=People,dc=example,dc=com
member: uid=ewalker,ou=People,dc=example,dc=com
member: uid=dthorud,ou=People,dc=example,dc=com
member: uid=btalbot,ou=People,dc=example,dc=com
member: uid=tcruse,ou=People,dc=example,dc=com
member: uid=kcarter,ou=People,dc=example,dc=com
member: uid=aworrell,ou=People,dc=example,dc=com
member: uid=bjensen,ou=People,dc=example,dc=com
member: uid=ajensen,ou=People,dc=example,dc=com
member: uid=cwallace,ou=People,dc=example,dc=com
member: uid=mwhite,ou=People,dc=example,dc=com
member: uid=kschmith,ou=People,dc=example,dc=com
member: uid=mtalbot,ou=People,dc=example,dc=com
member: uid=tschmith,ou=People,dc=example,dc=com
member: uid=gfarmer,ou=People,dc=example,dc=com
member: uid=speterso,ou=People,dc=example,dc=com
member: uid=prose,ou=People,dc=example,dc=com
member: uid=jbourke,ou=People,dc=example,dc=com
member: uid=mtyler,ou=People,dc=example,dc=com
member: uid=abergin,ou=People,dc=example,dc=com
member: uid=mschneid,ou=People,dc=example,dc=com
cn: Virtual Static
ds-target-group-dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com

OpenDJ lets you look up which groups a user belongs to by using the isMemberOf attribute.

$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 uid=bjensen
 isMemberOf
dn: uid=bjensen,ou=People,dc=example,dc=com
isMemberOf: cn=My Static Group,ou=Groups,dc=example,dc=com
isMemberOf: cn=Virtual Static,ou=Groups,dc=example,dc=com
isMemberOf: cn=My Dynamic Group,ou=Groups,dc=example,dc=com

You must request isMemberOf explicitly.

When you delete or rename an entry that belongs to static groups, that entry's DN must be removed or changed in the list of each group to which it belongs. You can configure OpenDJ to resolve membership on your behalf after the change operation succeeds by enabling referential integrity.

Referential integrity functionality is implemented as a plugin. The referential integrity plugin is disabled by default. To enable the plugin, use the dsconfig command.

$ dsconfig
 set-plugin-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --plugin-name "Referential Integrity"
 --set enabled:true
 --trustAll --no-prompt

With the plugin enabled, you can see OpenDJ referential integrity resolving group membership automatically.

$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=My Static Group)"
dn: cn=My Static Group,ou=Groups,dc=example,dc=com
ou: Groups
objectClass: groupOfNames
objectClass: top
member: uid=ahunter,ou=People,dc=example,dc=com
member: uid=bjensen,ou=People,dc=example,dc=com
member: uid=tmorris,ou=People,dc=example,dc=com
member: uid=scarter,ou=People,dc=example,dc=com
cn: My Static Group

$ ldapdelete
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 uid=scarter,ou=People,dc=example,dc=com
Processing DELETE request for uid=scarter,ou=People,dc=example,dc=com
DELETE operation successful for DN uid=scarter,ou=People,dc=example,dc=com
$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=My Static Group)"
dn: cn=My Static Group,ou=Groups,dc=example,dc=com
ou: Groups
objectClass: groupOfNames
objectClass: top
cn: My Static Group
member: uid=ahunter,ou=People,dc=example,dc=com
member: uid=bjensen,ou=People,dc=example,dc=com
member: uid=tmorris,ou=People,dc=example,dc=com

By default the referential integrity plugin is configured to manage member and uniqueMember attributes. These attributes take values that are DNs, and are indexed for equality by default. Before you add an additional attribute to manage, make sure that it has DN syntax and that it is indexed for equality. OpenDJ requires that the attribute be indexed because an unindexed search for integrity would potentially consume too many of the server's resources. Attribute syntax is explained in the chapter on Managing Schema. For instructions on indexing attributes, see the section on Configuring & Rebuilding Indexes.

You can also configure the referential integrity plugin to check that new entries added to groups actually exist in the directory by setting the check-references property to true. You can specify additional criteria once you have activated the check. To ensure that entries added must match a filter, set the check-references-filter-criteria to identify the attribute and the filter. For example, you can specify that group members must be person entries by setting check-references-filter-criteria to member:(objectclass=person). To ensure that entries must be located in the same naming context, set check-references-scope-criteria to naming-context.

Directory schema, described in RFC 4512, define the kinds of information you find in the directory, and can define how the information are related. This chapter focuses primarily on two types of directory schema definitions.

OpenDJ exposes schema over protocol through the cn=schema entry. OpenDJ stores the schema definitions corresponding to the entry in LDIF under the config/schema/ directory. Many standard definitions and definitions pertaining to the server configuration are included at installation time.

OpenDJ directory server is designed to permit updating the list of directory schema definitions while the server is running. As a result you can add support for new applications that require new attributes or new kinds of entries without interrupting the directory service. OpenDJ also replicates schema definitions, so the schema you add on one replica are propagated to other replicas without you having to intervene manually.

As it is easy to introduce typos into schema definitions, the best way to start defining your own schema is with the OpenDJ Control Panel. Open the Control Panel > Schema > Manage Schema window to get started creating your custom object classes and attribute types.

As object classes reference attribute types, you first create custom attribute types, and then create the object class that references the attribute types.

Create a custom attribute type through the New Attribute window.

Using the New Object Class window, create an auxiliary object class that allows your new custom attribute type. You set the type to Auxiliary under Extra Options.

When you finish, the schema changes show up by default in the file config/schema/99-user.ldif. Notice that the file name starts with a number, 99. This number is larger than the numbers prefixing other schema file names. In fact, OpenDJ reads the schema files in sorted order, reading schema definitions as they occur. If OpenDJ reads a schema definition for an object class before it has read the definitions of the attribute types mentioned in the object class definition, then it displays an error. Therefore, when naming your schema file, make sure the name appears in the sorted list of file names after all the schema files containing definitions that your schema definitions depends on. The default file name for your schema, 99-user.ldif, ensures that your definitions load only after all of the schema files installed by default.

You can create this file in the lab using the Control Panel, and then apply the definitions in production by adapting the content for use with the ldapmodify command, for example.

$ cat config/schema/99-user.ldif 
dn: cn=schema
objectClass: top
objectClass: ldapSubentry
objectClass: subschema
cn: schema
attributeTypes: ( temporary-fake-attr-id NAME 'myCustomAttribute' EQUALITY case
 IgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstrings
 Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE userApplications )
objectClasses: ( temporary-fake-oc-id NAME 'myCustomObjClass
 ' SUP top AUXILIARY MAY myCustomAttribute )
modifiersName: cn=Directory Manager,cn=Root DNs,cn=config
modifyTimestamp: 20110620095948Z

To test your schema definition, add the object class and attribute to an entry.

$ cat custom-attr.ldif 
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
add: objectClass
objectClass: myCustomObjClass
-
add: myCustomAttribute
myCustomAttribute: Testing 1, 2, 3...

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --filename custom-attr.ldif
Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=bjensen,ou=People,dc=example,dc=com
$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 uid=bjensen
 myCustomAttribute
dn: uid=bjensen,ou=People,dc=example,dc=com
myCustomAttribute: Testing 1, 2, 3...

In addition to supporting the standard schema definitions that are described in RFC 4512, section 4.1, OpenDJ also supports the following extensions that you can use when adding your own definitions.

By default, OpenDJ accepts data that follows the standards in terms of what is allowed and what is rejected. You might have legacy data from a directory service that is more lenient, allowing non-standard constructions such as multiple structural object classes per entry, not checking attribute value syntax, or even not respecting schema definitions.

For example, when importing data with multiple structural object classes defined per entry, you can relax schema checking to warn rather than reject entries having this issue.

$ dsconfig
 set-global-configuration-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --set single-structural-objectclass-behavior:warn
 --trustAll
 --no-prompt

You can allow attribute values that do not respect the defined syntax with the dsconfig command as well.

$ dsconfig
 set-global-configuration-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --set invalid-attribute-syntax-behavior:warn
 --trustAll
 --no-prompt

You can even turn off schema checking altogether, although turning off schema checking only really makes sense when you are absolutely sure that the entries and attribute values respect the schema definitions, and you simply want to turn off schema checking temporarily to speed up import processing.

$ dsconfig
 set-global-configuration-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --set check-schema:false
 --trustAll
 --no-prompt

The following files under config/schema/ contain schema definitions out of the box.

Referrals are implemented as entries with LDAP URL ref attribute values that point elsewhere. The ref attribute type is required by the referral object class. The referral object class is structural, however, and therefore cannot by default be added to an entry that already has a structural object class defined. When adding a ref attribute type to an existing entry, you can use the extensibleObject auxiliary object class.

When a referral is set, OpenDJ returns the referral to client applications requesting the entry or child entries affected. Client applications must be capable of following the referral returned. When the directory server responds for example to your search with referrals to one or more LDAP URLs, your client then constructs new searches from the LDAP URLs returned, and tries again.

To create an LDAP referral either you create a referral entry, or you add the extensibleObject object class and the ref attribute with an LDAP URL to an existing entry. This section demonstrates use of the latter approach.

$ cat referral.ldif 
dn: ou=People,dc=example,dc=com
changetype: modify
add: objectClass
objectClass: extensibleObject
-
add: ref
ref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --filename referral.ldif
Processing MODIFY request for ou=People,dc=example,dc=com
MODIFY operation successful for DN ou=People,dc=example,dc=com

The example above adds a referral to ou=People,dc=example,dc=com. OpenDJ can now return a referral for operations under the People organizational unit.

$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen description

SearchReference(referralURLs=
 {ldap://opendj.example.com:2389/ou=People,dc=example,dc=com??sub?})

$ ldapsearch --port 1389 --baseDN dc=example,dc=com ou=people

SearchReference(referralURLs=
 {ldap://opendj.example.com:2389/ou=People,dc=example,dc=com??sub?})

To access the entry instead of the referral, use the Manage DSAIT control.

$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 --control ManageDSAIT:true
 ou=people
 ref
dn: ou=People,dc=example,dc=com
ref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com

$ cat people.ldif 
dn: ou=People,dc=example,dc=com
changetype: modify
delete: ref
ref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --filename people.ldif 
Processing MODIFY request for ou=People,dc=example,dc=com
MODIFY operation successful for DN ou=People,dc=example,dc=com
A referral entry ou=People,dc=example,dc=com indicates that the operation must
 be processed at a different server
[ldap://opendj.example.com:2389/ou=People,dc=example,dc=com]
$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --control ManageDSAIT
 --filename people.ldif
Processing MODIFY request for ou=People,dc=example,dc=com
MODIFY operation successful for DN ou=People,dc=example,dc=com
$ ldapsearch --port 1389 --baseDN dc=example,dc=com ou=people
dn: ou=People,dc=example,dc=com
ou: People
objectClass: organizationalunit
objectClass: extensibleObject
objectClass: top

The example above shows how to remove the referral using the Manage DSAIT control with the ldapmodify command.

OpenDJ defines a number of virtual attributes by default.

These virtual attributes are typically operational, so you get them back from a search only when you request them.

$ ldapsearch --port 1389 --baseDN dc=example,dc=com dc=example
dn: dc=example,dc=com
dc: example
objectClass: domain
objectClass: top

$ ldapsearch --port 1389 --baseDN dc=example,dc=com dc=example numSubordinates
dn: dc=example,dc=com
numSubordinates: 4

You can use the existing virtual attribute types to create your own virtual attributes, and you can also use the user-defined type to create your own. The virtual attribute is defined by the server configuration, which is not replicated.

$ dsconfig
 create-virtual-attribute
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --name "Served By Description"
 --type user-defined
 --set enabled:true
 --set attribute-type:description
 --set base-dn:dc=example,dc=com
 --set value:"Served by OpenDJ.Example.com"
 --trustAll
 --no-prompt
$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen description
dn: uid=bjensen,ou=People,dc=example,dc=com
description: Served by OpenDJ.Example.com

Collective attributes cover many use cases better than virtual attributes.

Collective attributes provide a standard mechanism for defining attributes that appear on all the entries in a subtree potentially filtered by object class. Standard collective attribute type names have the prefix c-.

OpenDJ extends collective attributes to make them easier to use. You can define any OpenDJ attribute as collective using the ;collective attribute option. You can use LDAP filters in your subtree specification for fine-grained control over which entries have the collective attributes.

You can have entries inherit attributes from other entries using collective attributes. You establish the relationship between entries either by specifying another attribute of the entry that specifies the DN of the entry from which to inherit the attributes, or by specifying how to construct the RDN of the entry from which to inherit the attributes.

$ cat quotas.ldif 
dn: cn=schema
changetype: modify
add: attributeTypes
attributeTypes: ( example-class-of-service-attribute-type NAME 'classOfService
 ' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnore
 SubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE USAGE user
 Applications X-ORIGIN 'OpenDJ Documentation Examples' )
-
add: attributeTypes
attributeTypes: ( example-class-of-service-disk-quota NAME 'diskQuota
 ' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR case
 IgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE user
 Applications X-ORIGIN 'OpenDJ Documentation Examples' )
-
add: attributeTypes
attributeTypes: ( example-class-of-service-mail-quota NAME 'mailQuota
 ' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR case
 IgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE user
 Applications X-ORIGIN 'OpenDJ Documentation Examples' )
-
add: objectClasses
objectClasses: ( example-class-of-service-object-class NAME 'cos' SUP top AUX
 ILIARY MAY ( classOfService $ diskQuota $ mailQuota ) X-ORIGIN 'OpenDJ Doc
 umentation Examples' )

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --filename quotas.ldif
Processing MODIFY request for cn=schema
MODIFY operation successful for DN cn=schema

# cos.ldif: quotas by class of service
dn: cn=Bronze Class of Service,dc=example,dc=com
objectClass: collectiveAttributeSubentry
objectClass: extensibleObject
objectClass: subentry
objectClass: top
cn: Bronze Class of Service
diskQuota;collective: 10 GB
mailQuota;collective: 1 GB
subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
 bronze)" }

dn: cn=Silver Class of Service,dc=example,dc=com
objectClass: collectiveAttributeSubentry
objectClass: extensibleObject
objectClass: subentry
objectClass: top
cn: Silver Class of Service
diskQuota;collective: 50 GB
mailQuota;collective: 5 GB
subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
 silver)" }

dn: cn=Gold Class of Service,dc=example,dc=com
objectClass: collectiveAttributeSubentry
objectClass: extensibleObject
objectClass: subentry
objectClass: top
cn: Gold Class of Service
diskQuota;collective: 100 GB
mailQuota;collective: 10 GB
subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
 gold)" }

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --defaultAdd
 --filename cos.ldif
Processing ADD request for cn=Bronze Class of Service,dc=example,dc=com
ADD operation successful for DN cn=Bronze Class of Service,dc=example,dc=com
Processing ADD request for cn=Silver Class of Service,dc=example,dc=com
ADD operation successful for DN cn=Silver Class of Service,dc=example,dc=com
Processing ADD request for cn=Gold Class of Service,dc=example,dc=com
ADD operation successful for DN cn=Gold Class of Service,dc=example,dc=com

$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 uid=bjensen
 classOfService mailQuota diskQuota
dn: uid=bjensen,ou=People,dc=example,dc=com
mailQuota: 1 GB
classOfService: bronze
diskQuota: 10 GB

$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 uid=kvaughan
 classOfService mailQuota diskQuota
dn: uid=kvaughan,ou=People,dc=example,dc=com
mailQuota: 5 GB
classOfService: silver
diskQuota: 50 GB

$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 uid=scarter
 classOfService mailQuota diskQuota
dn: uid=scarter,ou=People,dc=example,dc=com
mailQuota: 10 GB
classOfService: gold
diskQuota: 100 GB

dn: cn=Inherit Department Number From Manager,dc=example,dc=com
objectClass: top
objectClass: subentry
objectClass: inheritedCollectiveAttributeSubentry
objectClass: inheritedFromDNCollectiveAttributeSubentry
cn: Inherit Department Number From Manager
subtreeSpecification: { base "ou=People" }
inheritFromDNAttribute: manager
inheritAttribute: departmentNumber

dn: uid=bjensen,ou=People,dc=example,dc=com
manager: uid=trigden, ou=People, dc=example,dc=com

dn: uid=trigden,ou=People,dc=example,dc=com
departmentNumber: 3001

$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen
 departmentNumber
dn: uid=bjensen,ou=People,dc=example,dc=com
departmentNumber: 3001

dn: cn=Inherit From Locality,dc=example,dc=com
objectClass: top
objectClass: subentry
objectClass: inheritedCollectiveAttributeSubentry
objectClass: inheritedFromRDNCollectiveAttributeSubentry
cn: Inherit From Locality
subtreeSpecification: { base "ou=People" }
inheritFromBaseRDN: ou=Locations
inheritFromRDNAttribute: l
inheritFromRDNType: l
inheritAttribute: preferredLanguage
inheritAttribute: street
collectiveConflictBehavior: real-overrides-virtual

dn: l=Bristol,ou=Locations,dc=example,dc=com
objectClass: top
objectClass: locality
objectClass: extensibleObject
l: Bristol
street: 60 Queen Square
preferredLanguage: en-gb

collectiveConflictBehavior: real-overrides-virtual

dn: uid=scarter,ou=People,dc=example,dc=com
l: Bristol

$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=scarter
 preferredLanguage street
dn: uid=scarter,ou=People,dc=example,dc=com
preferredLanguage: en-gb
street: 60 Queen Square

dn: uid=bjensen,ou=People,dc=example,dc=com
preferredLanguage: en, ko;q=0.8
l: San Francisco

$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen
 preferredLanguage street
dn: uid=bjensen,ou=People,dc=example,dc=com
preferredLanguage: en, ko;q=0.8
street: 500 3rd Street

You use LDAP pass through authentication when the credentials for authenticating are stored not in OpenDJ, but instead in a remote directory service. In effect OpenDJ redirects the bind operation against a remote LDAP server.

Exactly how OpenDJ redirects the bind depends on how the user entry in OpenDJ maps to the corresponding user entry in the remote directory.

You configure pass through authentication as an authentication policy that you associate with a user's entry in the same way that you associate a password policy with a user's entry. Either a user has an authentication policy for pass through authentication, or the user has a local password policy.

When setting up pass through authentication, you need to know to which remote server or servers to redirect binds, and you need to know how you map user entries in OpenDJ to user entries in the remote directory.

$ ldapsearch
 --hostname opendj.example.com
 --baseDN dc=example,dc=com
 uid=ldapptauser
 cn
dn: uid=ldapptauser,ou=People,dc=example,dc=com
cn: LDAP PTA User

$ ldapsearch
 --hostname ad.example.com
 --baseDN "CN=Users,DC=internal,DC=forgerock,DC=com"
 --bindDN "cn=administrator,cn=Users,DC=internal,DC=forgerock,DC=com"
 --bindPassword password
 "(cn=LDAP PTA User)"
 cn
dn: CN=LDAP PTA User,CN=Users,DC=internal,DC=forgerock,DC=com
cn: LDAP PTA User

You assign authentication policies in the same way as you assign password policies, by using the ds-pwp-password-policy-dn attribute.

$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 uid=user.0
 pwdPolicySubentry
dn: uid=user.0,ou=People,dc=example,dc=com

dn: uid=user.0,ou=People,dc=example,dc=com
cn: Aaccf Amar
description: This is the description for Aaccf Amar.
employeeNumber: 0
givenName: Aaccf
homePhone: +1 225 216 5900
initials: ASA
l: Panama City
mail: user.0@maildomain.net
mobile: +1 010 154 3228
objectClass: person
objectClass: inetorgperson
objectClass: organizationalperson
objectClass: top
pager: +1 779 041 6341
postalAddress: Aaccf Amar$01251 Chestnut Street$Panama City, DE  50369
postalCode: 50369
sn: Amar
st: DE
street: 01251 Chestnut Street
telephoneNumber: +1 685 622 6202
uid: user.0

OpenDJ exposes monitoring information over LDAP under the entry cn=monitor. Many different types of information are exposed. The following example shows monitoring information about the userRoot backend holding Example.com data.

Interface stability: Evolving

$ ldapsearch --port 1389 --baseDN cn=monitor "(cn=userRoot backend)"
dn: cn=userRoot backend,cn=Disk Space Monitor,cn=monitor
disk-state: normal
objectClass: top
objectClass: ds-monitor-entry
objectClass: extensibleObject
disk-dir: /path/to/opendj/db/userRoot
disk-free: 343039315968
cn: userRoot backend

dn: cn=userRoot Backend,cn=monitor
objectClass: top
objectClass: ds-monitor-entry
objectClass: ds-backend-monitor-entry
ds-backend-is-private: FALSE
ds-backend-writability-mode: enabled
cn: userRoot Backend
ds-backend-entry-count: 163
ds-backend-id: userRoot
ds-base-dn-entry-count: 163 dc=example,dc=com
ds-backend-base-dn: dc=example,dc=com

You can set global ACIs on the Access Control Handler if you want to limit read access under cn=monitor.

OpenDJ lets you monitor the server over the Simple Network Management Protocol (SNMP), with support for the Management Information Base described in RFC 2605: Directory Server Monitoring MIB.

OpenDJ SNMP-based monitoring depends on OpenDMK, which you must download separately. Install the Full Binary Bundle by using the graphical installer, which requires that you accept the Binary License for Project OpenDMK. OpenDJ directory server that you download from ForgeRock is built with OpenDMK, but due to licensing OpenDMK is not part of OpenDJ. SNMP is therefore not enabled by default.

To run the OpenDMK installer, use the self-extracting .jar.

$ java -jar ~/Downloads/opendmk-1.0-b02-*.jar

If you install under /path/to, then the runtime library needed for SNMP is /path/to/OpenDMK-bin/lib/jdmkrt.jar.

Once you have installed OpenDMK, you can set up a connection handler for SNMP by enabling the connection handler, and pointing OpenDJ to your installation of the OpenDMK jdmkrt.jar library.

$ dsconfig
 set-connection-handler-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name "SNMP Connection Handler"
 --set enabled:true
 --set opendmk-jarfile:/path/to/OpenDMK-bin/lib/jdmkrt.jar
 --trustAll
 --no-prompt

By default, the SNMP Connection Handler listens on port 161 and uses port 162 for traps. On UNIX and Linux systems, only root can normally open these ports. Therefore if you install as a normal user, you might want to change the listen and trap ports.

$ dsconfig
 set-connection-handler-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name "SNMP Connection Handler"
 --set listen-port:11161
 --set trap-port:11162
 --trustAll
 --no-prompt

Restart the SNMP Connection Handler to take the port number changes into account.

To restart the connection handler, you disable it, then enable it again.

$ dsconfig
 set-connection-handler-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name "SNMP Connection Handler"
 --set enabled:false
 --trustAll
 --no-prompt
$ dsconfig
 set-connection-handler-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name "SNMP Connection Handler"
 --set enabled:true
 --trustAll
 --no-prompt

Use a command such as snmpwalk to check that the SNMP listen port works.

$ snmpwalk -v 2c -c OpenDJ@OpenDJ localhost:11161
SNMPv2-SMI::mib-2.66.1.1.1.1 = STRING: "OpenDJ 2.6.0..."
SNMPv2-SMI::mib-2.66.1.1.2.1 = STRING: "/path/to/opendj"
...

OpenDJ provides Java Management eXtensions (JMX) based monitoring. A number of tools support JMX, including jconsole and jvisualvm, which are bundled with the Sun/Oracle Java platform. JMX is not configured by default. Use the dsconfig command to configure the JMX connection handler.

Interface stability: Evolving

$ dsconfig
 set-connection-handler-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name "JMX Connection Handler"
 --set enabled:true
 --trustAll
 --no-prompt

By default, no users have privileges to access the JMX connection. The following command adds JMX privileges for Directory Manager.

$ dsconfig
 set-root-dn-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --add default-root-privilege-name:jmx-notify
 --add default-root-privilege-name:jmx-read
 --add default-root-privilege-name:jmx-write
 --trustAll
 --no-prompt

You must also configure security to login remotely. See the section on Using SSL in Monitoring and Management Using JMX for hints.

Alternatively, you can connect to a local server process by using the server process identifier.

$ cat ../logs/server.pid
3363
$ jvisualvm --openpid 3363 &

OpenDJ comes with two commands for monitoring server processes and tasks. The status command displays basic information about the local server, similar to what is seen in the default window of the Control Panel. The manage-tasks command lets you manage tasks scheduled on a server, such as nightly backup.

The status command takes administrative credentials to read the configuration, as does the Control Panel.

$ status --bindDN "cn=Directory Manager" --bindPassword password

          --- Server Status ---
Server Run Status:        Started
Open Connections:         1

          --- Server Details ---
Host Name:                localhost
Administrative Users:     cn=Directory Manager
Installation Path:        /path/to/opendj
Version:                  OpenDJ 2.6.0
Java Version:             1.6.0_24
Administration Connector: Port 4444 (LDAPS)

          --- Connection Handlers ---
Address:Port : Protocol : State
-------------:----------:---------
--           : LDIF     : Disabled
0.0.0.0:636  : LDAPS    : Disabled
0.0.0.0:1389 : LDAP     : Enabled
0.0.0.0:1689 : JMX      : Disabled

          --- Data Sources ---
Base DN:     dc=example,dc=com
Backend ID:  userRoot
Entries:     163
Replication: Disabled

The manage-tasks command connects over the administration port, and so can connect to both local and remote servers.

$ manage-tasks
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --trustAll
 --no-prompt

ID                         Type    Status
--------------------------------------------------------
example                    Backup  Recurring
example-20110623030000000  Backup  Waiting on start time

By default OpenDJ stores access and errors logs as well as a server process ID file under the logs/ directory. For the replication service, OpenDJ also keeps a replication log there. You can also configure a debug log. Furthermore, you can configure policies about how logs are rotated, and how they are retained. You configure logging using the dsconfig command.

Each log depends on a log publisher, whose type corresponds to the type of log. OpenDJ uses file-based log publishers. The design allows for custom log publishers, however, which could publish the logs elsewhere besides a file.

For debug logging, you also set a debug target to control what gets logged.

$ dsconfig
 list-log-rotation-policies
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password


Log Rotation Policy                 : Type       : file-size-limit : rotation-interval : time-of-day
------------------------------------:------------:-----------------:-------------------:------------
24 Hours Time Limit Rotation Policy : time-limit : -               : 1 d               : -
7 Days Time Limit Rotation Policy   : time-limit : -               : 1 w               : -
Fixed Time Rotation Policy          : fixed-time : -               : -                 : 2359
Size Limit Rotation Policy          : size-limit : 100 mb          : -                 : -

$ dsconfig
 list-log-retention-policies
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password


Log Retention Policy             : Type            : disk-space-used : free-disk-space : number-of-files
---------------------------------:-----------------:-----------------:-----------------:----------------
File Count Retention Policy      : file-count      : -               : -               : 10
Free Disk Space Retention Policy : free-disk-space : -               : 500 mb          : -
Size Limit Retention Policy      : size-limit      : 500 mb          : -               : -

$ dsconfig
 get-log-publisher-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --publisher-name "File-Based Access Logger"
 --property retention-policy
 --property rotation-policy
Property         : Value(s)
-----------------:-------------------------------------------------------------
retention-policy : File Count Retention Policy
rotation-policy  : 24 Hours Time Limit Rotation Policy, Size Limit Rotation
                 : Policy

$ tail -f /path/to/opendj/logs/access

$ dsconfig
 create-access-log-filtering-criteria
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --publisher-name "File-Based Access Logger"
 --criteria-name "Exclude LDAPS on 1636 and 4444"
 --type generic
 --set connection-port-equal-to:1636
 --set connection-port-equal-to:4444
 --set connection-protocol-equal-to:ldaps
 --trustAll
 --no-prompt

$ dsconfig
 set-log-publisher-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --publisher-name "File-Based Access Logger"
 --set filtering-policy:exclusive
 --trustAll
 --no-prompt

$ tail -f /path/to/opendj/logs/access
[19/Oct/2011:16:37:16 +0200] CONNECT conn=8 from=127.0.0.1:54165
 to=127.0.0.1:1389 protocol=LDAP
[19/Oct/2011:16:37:16 +0200] SEARCH REQ conn=8 op=0 msgID=1
 base="dc=example,dc=com" scope=wholeSubtree filter="(uid=bjensen)" attrs="cn"
[19/Oct/2011:16:37:16 +0200] SEARCH RES conn=8 op=0 msgID=1 result=0 nentries=1
 etime=14
[19/Oct/2011:16:37:16 +0200] UNBIND REQ conn=8 op=1 msgID=2
[19/Oct/2011:16:37:16 +0200] DISCONNECT conn=8 reason="Client Unbind"

OpenDJ can send alerts to provide notifications of significant server events. Yet alert notifications are not enabled by default. You can use the dsconfig command to enable alert notifications.

$ dsconfig
 set-alert-handler-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name "JMX Alert Handler"
 --set enabled:true
 --trustAll
 --no-prompt

OpenDJ can also send mail over SMTP instead of JMX notifications. Before you set up the SMTP-based alert handler, you must identify an SMTP server to which OpenDJ sends messages.

$ dsconfig
 set-global-configuration-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --set smtp-server:smtp.example.com
 --trustAll
 --no-prompt
$ dsconfig
 create-alert-handler
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name "SMTP Alert Handler"
 --type smtp
 --set enabled:true
 --set message-subject:"OpenDJ Alert, Type: %%alert-type%%, ID: %%alert-id%%"
 --set message-body:"%%alert-message%%"
 --set recipient-address:kvaughan@example.com
 --set sender-address:opendj@example.com
 --trustAll
 --no-prompt

Your key performance requirement is most likely to satisfy your users or customers with the resources available to you. Before you can solve potential performance problems, define what those users or customers expect, and determine what resources you will have to satisfy their expectations.

Even if you do not need high availability, you still need two of everything, because your test environment needs to mimic your production environment as closely as possible if you want to avoid nasty surprises.

In your test environment, you set up OpenDJ as you will later in production, and then conduct experiments to determine how best to meet the requirements defined in the SLA.

Use make-ldif to generate sample data that match what you expect to find in production.

The OpenDJ LDAP Toolkit provides three command-line tools to help with basic performance testing.

All three commands show you information about the response time distributions, and allow you to perform tests at specific levels of throughput.

If you need additional precision when evaluating response times, use the global configuration setting etime-resolution to change elapsed processing time resolution from milliseconds (default) to nanoseconds.

$ dsconfig
 set-global-configuration-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --set etime-resolution:nanoseconds
 --no-prompt

For more extensive testing, try the SLAMD Distributed Load Generation Engine. SLAMD is built to test more than just directory, but is particularly well suited to test directory service performance, is well documented, and is available under the Sun Public License. SLAMD is designed both to offer an easy to used web-based interface, and also to allow you to customize jobs to match the access patterns you expect from client applications.

When your tests show that OpenDJ performance is lacking even though you have the right underlying network, hardware, storage, and system resources in place, you can tweak OpenDJ performance in a number of ways. This section mentions the most common tweaks.

$ dsconfig
 set-backend-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --set entries-compressed:true
 --trustAll
 --no-prompt
$ import-ldif
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --ldifFile /path/to/Example.ldif
 --backendID userRoot
 --includeBranch dc=example,dc=com
 --start 0
Import task 20120917100628767 scheduled to start Sep 17, 2012 10:06:28 AM CEST

$ dsconfig
 set-backend-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --set preload-time-limit:30m
 --trustAll
 --no-prompt

$ dsconfig
 create-entry-cache
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --cache-name "Large Group Entry Cache"
 --type fifo
 --set cache-level:1
 --set include-filter:"(ou=Large Static Groups)"
 --set max-entries:10
 --set enabled:true
 --trustAll
 --no-prompt

$ dsconfig
 set-global-configuration-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --set entry-cache-preload:true
 --no-prompt

$ dsconfig
 set-log-publisher-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --publisher-name "File-Based Access Logger"
 --set enabled:false
 --trustAll
 --no-prompt

From time to time you might change server hardware, file system layout, or host names. At those times you move the services running on the system. You can move OpenDJ data between servers and operating systems. Most of the configuration is also portable.

Take a moment to determine whether you find it quicker and easier to move your server, or instead to recreate a copy. To recreate a copy, install a new server, set up the new server configuration to match the old, and then copy only the data from the old server to the new server, initializing replication from existing data, or even from LDIF if your database is not too large.

After you decide to move a server, start by taking it out of service. Taking it out of service means directing client applications elsewhere, and then preventing updates from client applications, and finally disabling replication, too. Directing client applications elsewhere depends on your network configuration and possibly on your client application configuration. The other two steps can be completed with the dsconfig and dsreplication commands.

Now that you have decided to move your server, and prepared for the move, you must not only move the files but also fix the configuration and the server certificates, and then enable replication.

In order to solve your problem methodically, save time by defining the problem clearly up front. In a replicated environment with multiple directory servers and many client applications, it can be particularly important to pin down not only the problem (difference in observed behavior compared to expected behavior), but also the circumstances and steps that lead to the problem occurring.

Pinpointing the problem can sometimes indicate where you should start looking for solutions.

Installation and upgrade procedures result in a log file tracing the operation. The log location differs by operating system, but look for lines in the command output of the following form.

See /var/....log for a detailed log of this operation.

When trying to launch ControlPanel.app on Mac OS X, the system shows a message window indicating an error:

"ControlPanel" is damaged and can't be opened.
You should move it to the Trash.
  

This is related to the application signing and security settings. To work around the problem, try one of the following solutions:

The OpenDJ Mac OS X .app wrapper applications require Java 6.

This section describes what to do if you forgot the password for Directory Manager or for the global (replication) administrator.

OpenDJ can write debug information and stack traces to the server debug log. What is logged depends both on debug targets that you create, and also on the debug level that you choose.

Misconfiguration can potentially put OpenDJ in a state where you must intervene, and where you need to prevent users and applications from accessing the directory until you are done fixing the problem.

OpenDJ provides a lockdown mode that allows connections only on the loopback address, and allows only operations requested by root users, such as cn=Directory Manager. You can use lockdown mode to prevent all but administrative access to OpenDJ in order to repair the server.

To put OpenDJ into lockdown mode, the server must be running. You cause the server to enter lockdown mode by using a task. Notice that the modify operation is performed over the loopback address (accessing OpenDJ on the local host).

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --defaultAdd
dn: ds-task-id=Enter Lockdown Mode,cn=Scheduled Tasks,cn=tasks
objectClass: top
objectClass: ds-task
ds-task-id: Enter Lockdown Mode
ds-task-class-name: org.opends.server.tasks.EnterLockdownModeTask

Processing ADD request for
 ds-task-id=Enter Lockdown Mode,cn=Scheduled Tasks,cn=tasks
ADD operation successful for DN
 ds-task-id=Enter Lockdown Mode,cn=Scheduled Tasks,cn=tasks

OpenDJ logs a notice message in logs/errors when lockdown mode takes effect.

[30/Jan/2012:17:04:32 +0100] category=BACKEND severity=NOTICE msgID=9896350
 msg=Lockdown task Enter Lockdown Mode finished execution

Client applications that request operations get a message concerning lockdown mode.

$ ldapsearch --port 1389 --baseDN "" --searchScope base "(objectclass=*)" +
SEARCH operation failed
Result Code:  53 (Unwilling to Perform)
Additional Information:  Rejecting the requested operation because the server
 is in lockdown mode and will only accept requests from root users over
 loopback connections

You also leave lockdown mode by using a task.

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --defaultAdd
dn: ds-task-id=Leave Lockdown Mode,cn=Scheduled Tasks,cn=tasks
objectClass: top
objectClass: ds-task
ds-task-id: Leave Lockdown Mode
ds-task-class-name: org.opends.server.tasks.LeaveLockdownModeTask

Processing ADD request for
 ds-task-id=Leave Lockdown Mode,cn=Scheduled Tasks,cn=tasks
ADD operation successful for DN
 ds-task-id=Leave Lockdown Mode,cn=Scheduled Tasks,cn=tasks

OpenDJ also logs a notice message when leaving lockdown.

[30/Jan/2012:17:13:05 +0100] category=BACKEND severity=NOTICE msgID=9896350
 msg=Leave Lockdown task Leave Lockdown Mode finished execution

By default OpenDJ requires that LDIF data you import respect standards. In particular, OpenDJ is set to check that entries to import match the schema defined for the server. You can temporarily bypass this check by using the --skipSchemaValidation with the import-ldif command.

OpenDJ also ensures by default that entries have only one structural object class. You can relax this behavior by using the advanced global configuration property, single-structural-objectclass-behavior. This can be useful when importing data exported from Sun Directory Server. For example, to warn when entries have more than one structural object class instead of reject such entries being added, set single-structural-objectclass-behavior:warn as follows.

$ dsconfig
 set-global-configuration-prop
 --port 4444
 --hostname `hostname`
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --set single-structural-objectclass-behavior:warn
 --trustAll
 --no-prompt

By default, OpenDJ also checks syntax for a number of attribute types. You can relax this behavior as well by using the dsconfig set-attribute-syntax-prop command. See the list of attribute syntaxes and use the --help option for further information.

When running import-ldif, you can use the -R rejectFile option to capture entries that could not be imported, and the --countRejects option to return the number of rejected entries as the import-ldif exit code.

Once you work through the issues with your LDIF data, reinstate the default behavior to ensure automated checking.

In order to trust the server certificate, client applications usually compare the signature on certificates with those of the Certificate Authorities (CAs) whose certificates are distributed with the client software. For example, the Java environment is distributed with a key store holding many CA certificates.

$ keytool -list -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit
 | wc -l
     334

The self-signed server certificates that can be configured during OpenDJ setup are not recognized as being signed by any CAs. Your software therefore is configured not to trust the self-signed certificates by default. You must either configure the client applications to accept the self-signed certificates, or else use certificates signed by recognized CAs.

You can further debug the network traffic by collecting debug traces. To see the traffic going over TLS/SSL in debug mode, configure OpenDJ to dump debug traces from javax.net.debug into the logs/server.out file.

OPENDJ_JAVA_ARGS="-Djavax.net.debug=all" start-ds

[21/Nov/2011:13:03:20 -0600] category=SYNC severity=NOTICE
 msgID=15138921 msg=SSL connection attempt from myserver (123.456.789.012)
 failed: Remote host closed connection during handshake

$ grep ds-cfg-replication-server: config/config.ldif |sort | uniq
ds-cfg-replication-server: opendj.example.com:8989
ds-cfg-replication-server: opendj.example.com:9989

$ keytool -list -v -keystore config/admin-truststore
-storepass `cat config/admin-keystore.pin` | grep "^Owner:"
Owner: CN=opendj.example.com, O=Administration Connector Self-Signed Certificate

$ keytool -list -v -keystore config/ads-truststore
 -storepass `cat config/ads-truststore.pin`| grep "^Owner:"
Owner: CN=opendj.example.com, O=OpenDJ Certificate
Owner: CN=opendj.example.com, O=OpenDJ Certificate
Owner: CN=opendj.example.com, O=OpenDJ Certificate

By default OpenDJ logs information about all LDAP client operations in logs/access, and all HTTP client operations in logs/http-access. The following lines are wrapped for readability, showing a search for the entry with uid=bjensen as traced in the LDAP access log. In the access log itself, each line starts with a time stamp.

[27/Jun/2011:17:23:00 +0200] CONNECT conn=19 from=127.0.0.1:56641
 to=127.0.0.1:1389 protocol=LDAP
[27/Jun/2011:17:23:00 +0200] SEARCH REQ conn=19 op=0 msgID=1
 base="dc=example,dc=com" scope=wholeSubtree filter="(uid=bjensen)" attrs="ALL"
[27/Jun/2011:17:23:00 +0200] SEARCH RES conn=19 op=0 msgID=1
 result=0 nentries=1 etime=3
[27/Jun/2011:17:23:00 +0200] UNBIND REQ conn=19 op=1 msgID=2
[27/Jun/2011:17:23:00 +0200] DISCONNECT conn=19 reason="Client Unbind"

As you see, each client connection and set of LDAP operations are traced, starting with a time stamp and information about the operation performed, then including information about the connection, the operation number for the sequence of operations performed by the client, a message identification number, and additional information about the operation.

To match HTTP client operations with related internal server operations, first prevent OpenDJ from suppressing internal operations from the LDAP access log by using the dsconfig command to set the LDAP access log publisher suppress-internal-operations advanced property to false. Then match the values of the x-connection-id field in the HTTP access log with conn=id values in the LDAP access log.

For example, consider an HTTP GET request for the _id field of the user newuser, which is handled by connection 4 as shown in logs/http-access.

-  192.168.0.12  bjensen  22/May/2013:16:27:52 +0200
  GET  /users/newuser?_fields=_id  HTTP/1.1  200
  curl/7.21.4  4  12

With internal operations logged in logs/access, log lines for the related operations have conn=4.

[22/May/2013:16:27:52 +0200] CONNECT conn=4
  from=192.168.0.12:63593 to=192.168.0.12:8080 protocol=HTTP/1.1
[22/May/2013:16:27:52 +0200] SEARCH REQ conn=4
  op=0 msgID=0 base="ou=people,dc=example,dc=com" scope=wholeSubtree
   filter="(&(objectClass=inetOrgPerson)(uid=bjensen))" attrs="1.1"
[22/May/2013:16:27:52 +0200] SEARCH RES conn=4
  op=0 msgID=0 result=0 nentries=1 etime=5
[22/May/2013:16:27:52 +0200] BIND REQ conn=4
  op=1 msgID=1 version=3 type=SIMPLE
   dn="uid=bjensen,ou=People,dc=example,dc=com"
[22/May/2013:16:27:52 +0200] BIND RES conn=4
  op=1 msgID=1 result=0 authDN="uid=bjensen,ou=People,dc=example,dc=com"
   etime=3
[22/May/2013:16:27:52 +0200] SEARCH REQ conn=4
  op=2 msgID=2 base="uid=newuser,ou=people,dc=example,dc=com" scope=baseObject
   filter="(objectClass=*)" attrs="uid,etag"
[22/May/2013:16:27:52 +0200] SEARCH RES conn=4
   op=2 msgID=2 result=0 nentries=1 etime=4
[22/May/2013:16:27:52 +0200] UNBIND REQ conn=4
   op=3 msgID=3
[22/May/2013:16:27:52 +0200] DISCONNECT conn=4
   reason="Client Unbind"

To help diagnose errors due to access permissions, OpenDJ supports the get effective rights control. The control OID, 1.3.6.1.4.1.42.2.27.9.5.2, is not allowed by the default global ACIs. You must therefore add access to use the get effective rights control when not using it as Directory Manager.

The request control with Object Identifier (OID) "1.2.840.113556.1.4.319"
cannot be used due to insufficient access rights

$ dsconfig
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword "password"
 get-access-control-handler-prop

Property   : Value(s)
-----------:-------------------------------------------------------------------
enabled    : true
global-aci : (extop="1.3.6.1.4.1.26027.1.6.1 || 1.3.6.1.4.1.26027.1.6.3 ||
...
           : (targetcontrol="1.3.6.1.1.12 || 1.3.6.1.1.13.1 || 1.3.6.1.1.13.2
           : || 1.2.840.113556.1.4.319 || 1.2.826.0.1.3344810.2.3 ||
           : 2.16.840.1.113730.3.4.18 || 2.16.840.1.113730.3.4.9 ||
           : 1.2.840.113556.1.4.473 || 1.3.6.1.4.1.42.2.27.9.5.9") (version
           : 3.0; acl "Authenticated users control access"; allow(read)
           : userdn="ldap:///all";), (targetcontrol="2.16.840.1.113730.3.4.2 ||
           : 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 ||
           : 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 ||
           : 2.16.840.1.113730.3.4.16") (version 3.0; acl "Anonymous control
           : access"; allow(read) userdn="ldap:///anyone";)

$ dsconfig
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword "password"
 set-access-control-handler-prop
 --remove global-aci:"(targetcontrol=\"2.16.840.1.113730.3.4.2 ||
 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 ||
 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 ||
 2.16.840.1.113730.3.4.16\") (version 3.0; acl \"Anonymous control access\";
 allow(read) userdn=\"ldap:///anyone\";)"
 --add global-aci:"(targetcontrol=\"2.16.840.1.113730.3.4.2 ||
 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 ||
 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 ||
 2.16.840.1.113730.3.4.16 || 1.2.840.113556.1.4.319\")
 (version 3.0; acl \"Anonymous control access\"; allow(read)
 userdn=\"ldap:///anyone\";)"
 --no-prompt

Replication can generally recover from conflicts and transient issues. Replication does, however, require that update operations be copied from server to server. It is therefore possible to experience temporary delays while replicas converge, especially when the write operation load is heavy. OpenDJ's tolerance for temporary divergence between replicas is what allows OpenDJ to remain available to serve client applications even when networks linking the replicas go down.

In other words, the fact that directory services are loosely convergent rather than transactional is a feature, not a bug.

That said, you may encounter errors. Replication uses its own error log file, logs/replication. Error messages in the log file have category=SYNC. The messages have the following form. Here the line is folded for readability.

[27/Jun/2011:14:37:48 +0200] category=SYNC severity=INFORMATION msgID=14680169
 msg=Replication server accepted a connection from 10.10.0.10/10.10.0.10:52859
 to local address 0.0.0.0/0.0.0.0:8989 but the SSL handshake failed. This is
 probably benign, but may indicate a transient network outage or a
 misconfigured client application connecting to this replication server.
 The error was: Remote host closed connection during handshake

OpenDJ maintains historical information about changes in order to bring replicas up to date, and to resolve replication conflicts. To prevent historical information from growing without limit, OpenDJ purges historical information after a configurable delay (replication-purge-delay, default: 3 days). A replica can become irrevocably out of sync if you restore it from a backup archive older than the purge delay, or if you stop it for longer than the purge delay. If this happens to you, disable the replica, and then reinitialize it from a recent backup or from a server that is up to date.

When you cannot resolve a problem yourself, and want to ask for help, clearly identify the problem and how you reproduce it, and also the version of OpenDJ you use to reproduce the problem. The version includes both a version number and also a build time stamp.

$ dsconfig --version
OpenDJ 2.6.0
Build yyyymmddhhmmssZ