1. (Optional) If you are stopping a replicated server permanently, for example, before decommissioning the underlying system or virtual machine, first remove the server from the replication topology:

   $ dsreplication \
    unconfigure \
    --unconfigureAll \
    --port 4444 \
    --hostname opendj.example.com \
    --adminUID admin \
    --adminPassword password \
    --trustAll \
    --no-prompt
       

   This step unregisters the server from the replication topology, effectively removing its replication configuration from other servers. This step must be performed before you decommission the system, because the server must connect to its peers in the replication topology.

2. Before shutting down the system where OpenDJ server is running, and before detaching any storage used for directory data, cleanly stop the server using one of the following techniques:

   • Use the stop-ds command, described in stop-ds(1) in the Reference:

     $ stop-ds
           

   • (Linux) If an OpenDJ server was installed from a .deb or .rpm package, then service management scripts were created at setup time.

     Use the service opendj stop command:

     centos# service opendj stop
     Stopping opendj (via systemctl):                           [  OK  ]
           

     ubuntu$ sudo service opendj stop
     $Stopping opendj: ... > SUCCESS.
           

   • (UNIX) Create an RC script, and then use the script to stop the server:

     $ sudo create-rc-script \
      --outputFile /etc/init.d/opendj \
      --userName opendj
     
     $ sudo /etc/init.d/opendj stop
           

   • (Windows) Register OpenDJ as a Windows Service, and then manage the service through Windows administration tools:

     C:\path\to\opendj\bat> windows-service.bat --enableService
           

   Do not intentionally kill the OpenDJ server process unless the server is completely unresponsive.

   When stopping cleanly, the server writes state information to database backends, and releases locks that it holds on database files.

The makeldif command uses templates to provide sample data. Default templates are located in the /path/to/opendj/config/MakeLDIF/ directory. The example.template file can be used to create a suffix with entries of the type inetOrgPerson. You can do the equivalent in the control panel (Directory Data > New Base DN... > Import Automatically Generated Example Data).

1. Write a file to act as the template for your generated LDIF.

   The resulting test data template depends on what data you expect to encounter in production. Base your work on your knowledge of the production data, and on the sample template, /path/to/opendj/config/MakeLDIF/example.template, and associated data.

   See makeldif.template(5) in the Reference for reference information about template files.

2. Create additional data files for the content in your template to be selected randomly from a file, rather than generated by an expression.

   Additional data files are located in the same directory as your template file.

3. Decide whether you want to generate the same test data each time you run the makeldif command with your template.

   If so, provide the same randomSeed integer each time you run the command.

4. Before generating a very large LDIF file, make sure you have enough space on disk.

5. Run the makeldif command to generate your LDIF file.

   The following command demonstrates use of the example MakeLDIF template:

   $ makeldif \
    --outputLDIF generated.ldif \
    --randomSeed 42 \
    /path/to/opendj/config/MakeLDIF/example.template
   ...LDIF processing complete....
       

The most efficient method of importing LDIF data is to take the OpenDJ server offline. Alternatively, you can schedule a task to import the data while the server is online.

1. (Optional) If you do not want to use the default userRoot backend, create a new backend for your data.

   See "Creating a New Database Backend" for details.

2. The following example imports dc=example,dc=com data into the userRoot backend, overwriting existing data:

   • If you want to speed up the process—for example because you have millions of directory entries to import—first shut down the server, and then run the import-ldif command:

     $ stop-ds --quiet
     $ import-ldif \
      --offline \
      --backendID userRoot \
      --includeBranch dc=example,dc=com \
      --ldifFile generated.ldif
           

   • If not, schedule a task to import the data while online:

     $ start-ds --quiet
     $ import-ldif \
      --hostname opendj.example.com \
      --port 4444 \
      --bindDN "cn=Directory Manager" \
      --bindPassword password \
      --backendID userRoot \
      --includeBranch dc=example,dc=com \
      --ldifFile generated.ldif \
      --trustAll
           

     The import task is scheduled through a secure connection to the administration port, by default 4444. You can schedule the import task to start at a particular time using the --start option.

     The --trustAll option trusts all SSL certificates, such as a self-signed OpenDJ server certificate.

3. If the server is replicated with other servers, initialize replication again after the successful import.

   For details see "Initializing Replicas".

   Initializing replication overwrites data in the remote servers in the same way that import overwrites existing data with LDIF data.

The following examples export dc=example,dc=com data from the userRoot backend:

1. To expedite export, shut down the server and then use the export-ldif command:

   $ stop-ds --quiet
   $ export-ldif \
    --offline \
    --backendID userRoot \
    --includeBranch dc=example,dc=com \
    --ldifFile backup.ldif
       

2. To export the data while online, leave the server running and schedule a task:

   $ export-ldif \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --backendID userRoot \
    --includeBranch dc=example,dc=com \
    --ldifFile backup.ldif \
    --start 0 \
    --trustAll
       

   The --start 0 option tells OpenDJ directory server to start the export task immediately.

   You can specify a time for the task to start using the format yyyymmddHHMMSS. For example, 20250101043000 specifies a start time of 4:30 AM on January 1, 2025.

   If the server is not running at the time specified, it attempts to perform the task after it restarts.

1. Change the port number using the dsconfig command.

   The following example changes the LDAP port number to 11389:

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

2. Restart the connection handler so the change takes effect.

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

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

1. Make sure you have a server certificate installed:

   $ keytool \
    -list \
    -alias server-cert \
    -keystore /path/to/opendj/config/keystore \
    -storepass:file /path/to/opendj/config/keystore.pin \
    -storetype PKCS12
   ...
   server-cert, <date>, PrivateKeyEntry
   ...
       

2. Activate StartTLS on the current LDAP port:

   $ dsconfig \
    set-connection-handler-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --handler-name "LDAP Connection Handler" \
    --set allow-start-tls:true \
    --set key-manager-provider:"Default Key Manager" \
    --set trust-manager-provider:"JVM Trust Manager" \
    --trustAll \
    --no-prompt
       

   The change takes effect. No need to restart the server.

If LDAPS access was not configured at during setup, follow these steps:

1. Make sure a server certificate and associated private key are available:

   $ keytool \
    -list \
    -alias server-cert \
    -keystore /path/to/opendj/config/keystore \
    -storepass:file /path/to/opendj/config/keystore.pin \
    -storetype PKCS12
   server-cert, <date>, PrivateKeyEntry
     

2. Configure the server to activate LDAPS access:

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

3. (Optional) If the deployment requires SSL client authentication, set the properties ssl-client-auth-policy and trust-manager-provider appropriately.

1. Change the port number using the dsconfig command.

   The following example changes the LDAPS port number to 11636:

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

2. Restart the connection handler so the change takes effect.

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

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

• To list the protocols and cipher suites that an OpenDJ server supports, read the supportedTLSProtocols and supportedTLSCiphers attributes of the root DSE:

  $ ldapsearch \
   --port 1389 \
   --baseDN "" \
   --searchScope base \
   "(objectclass=*)" \
   supportedTLSCiphers supportedTLSProtocols
     

  A supportedTLSCiphers name, such as TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, identifies the key attributes of the cipher suite:

  TLS

  Specifies the protocol, in this case TLS.

  ECDHE_RSA

  Specifies the key exchange algorithm used to determine how the client and server authenticate during the handshake phase.

  In this example, an elliptic curve variant of the Diffie-Hellman key exchange is used, where a random value chosen by the client is encrypted with the server's RSA public key.

  WITH_AES_256_GCM

  Specifies the bulk encryption algorithm, including the key size or initialization vectors.

  This example specifies the Advanced Encryption Standard (AES) with 256-bit key size and Galois/Counter Mode (GCM) block cipher mode.

  SHA384

  Specifies the message authentication code algorithm used to create the message digest, which is a cryptographic hash of each block in the message stream.

  In this example, the SHA-2 hash function, SHA-384, is used.

  A supportedTLSProtocols name identifies the protocol and version, such as TLSv1.2.

Choosing which protocol versions and cipher suites to allow for negotiating secure connections depends on known vulnerabilities, estimations of what is secure, and what peers support.

The default support is backward-compatible with old clients, meaning that if you do nothing it is possible for a client to use a protocol version that is known to have vulnerabilities, or to negotiate an insecure or very weakly secure connection. To avoid this, limit the protocols and cipher suites that you allow.

You can limit supported protocols and cipher suites by setting the properties, ssl-protocol and ssl-cipher-suite. These are available on connection handlers, and on components that connect to remote services including the global Crypto Manager component used for replication.

This procedure is based on server-side TLS recommendations from the Mozilla Operations Security team taken at the time of this writing. Recommendations evolve. Make sure you use current recommendations when configuring security settings.

The examples in this procedure assume you have installed an unlimited encryption strength policy:

1. For each cipher suite key algorithm to support, create a key pair using the supported key algorithm.

   The following example adds two key pairs to the default PKCS#12 keystore, with one key using RSA and the other key using elliptic curve.

   $ keytool \
    -genkeypair \
    -alias server-cert-rsa \
    -keyalg RSA \
    -ext "san=dns:opendj.example.com" \
    -dname "CN=opendj.example.com,O=Example Corp,C=FR" \
    -keystore /path/to/opendj/config/keystore \
    -storetype PKCS12 \
    -storepass:file /path/to/opendj/config/keystore.pin \
    -keypass:file /path/to/opendj/config/keystore.pin
   $ keytool \
    -genkeypair \
    -alias server-cert-ec \
    -keyalg EC \
    -ext "san=dns:opendj.example.com" \
    -dname "CN=opendj.example.com,O=Example Corp,C=FR" \
    -keystore /path/to/opendj/config/keystore \
    -storetype PKCS12 \
    -storepass:file /path/to/opendj/config/keystore.pin \
    -keypass:file /path/to/opendj/config/keystore.pin
      

2. On the components you use, explicitly set the supported protocols and cipher suites.

   The following example adjusts settings for the LDAP and LDAPS connection handlers:

   $ dsconfig \
    set-connection-handler-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --handler-name "LDAP Connection Handler" \
    --add ssl-protocol:TLSv1.2 \
    --add ssl-cipher-suite:TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 \
    --add ssl-cipher-suite:TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 \
    --add ssl-cipher-suite:TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 \
    --add ssl-cipher-suite:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 \
    --add ssl-cipher-suite:TLS_EMPTY_RENEGOTIATION_INFO_SCSV \
    --no-prompt \
    --trustAll
   $ dsconfig \
    set-connection-handler-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --handler-name "LDAPS Connection Handler" \
    --add ssl-protocol:TLSv1.2 \
    --add ssl-cipher-suite:TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 \
    --add ssl-cipher-suite:TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 \
    --add ssl-cipher-suite:TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 \
    --add ssl-cipher-suite:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 \
    --add ssl-cipher-suite:TLS_EMPTY_RENEGOTIATION_INFO_SCSV \
    --no-prompt \
    --trustAll
      

   The TLS_ECDHE_EC* cipher suites call for a server certificate with an elliptic curve key algorithm. The TLS_ECDHE_RSA* cipher suites call for a server certificate with an RSA key algorithm.

   The TLS_EMPTY_RENEGOTIATION_INFO_SCSV cipher suite is a renegotiation information extension with a special Signaling Cipher Suite Value (SCSV) to help older clients properly complete a handshake.

3. On the components you use, set the multivalued property, ssl-cert-nickname, to identify each certificate alias:

   $ dsconfig \
    set-connection-handler-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --handler-name "LDAP Connection Handler" \
    --set enabled:true \
    --set listen-port:1389 \
    --set allow-start-tls:true \
    --set ssl-cert-nickname:server-cert-ec \
    --set ssl-cert-nickname:server-cert-rsa \
    --set key-manager-provider:"Default Key Manager" \
    --set trust-manager-provider:"JVM Trust Manager" \
    --trustAll \
    --no-prompt
   $ dsconfig \
    set-connection-handler-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --handler-name "LDAPS Connection Handler" \
    --set listen-port:1636 \
    --set enabled:true \
    --set use-ssl:true \
    --set ssl-cert-nickname:server-cert-ec \
    --set ssl-cert-nickname:server-cert-rsa \
    --trustAll \
    --no-prompt
      

   When negotiating a secure connection, the server can now use either key.

You can specify which protocol versions to allow when command-line tools negotiate secure connections with LDAP servers.

The command-line tools depend on a system property, org.opends.ldaps.protocols. This property takes a comma-separated list of protocols. The default is constructed from the list of all protocols the JVM supports, removing protocol names starting with SSL. For example, if support is enabled in the JVM for versions 1.0, 1.1, and 1.2 of the TLS protocol, then the default is "TLSv1,TLSv1.1,TLSv1.2".

• Restrict the protocols to use by setting the property in one of the following ways:

  • Set the property by editing the java-args for the command in config/java.properties.

    For example, to restrict the protocol to TLS v1.2 when the status command negotiates a secure administrative connection, edit the corresponding line in config/java.properties:

    status.java-args=-Xms8m -client -Dorg.opends.ldaps.protocols=TLSv1.2

  • Set the property at runtime when running the command.

    The following example restricts the protocol to TLS v1.2 when the status command negotiates a secure administrative connection:

    $ export OPENDJ_JAVA_ARGS="-Dorg.opends.ldaps.protocols=TLSv1.2"
    $ status \
     --bindDN "cn=Directory Manager" \
     --bindPassword password \
     --trustAll
         

OpenDJ servers have a handler for HTTP connections. This handler exposes directory data over HTTP, including the RESTful API demonstrated in "Performing RESTful Operations" in the Developer's Guide. The HTTP connection handler can be enabled during the setup process.

This procedure shows you how to enable the HTTP connection handler if you did not enable the connection handler during the setup process.

The HTTP connection handler exposes directory data at HTTP endpoints. After you set up the HTTP connection handler, make sure that at least one HTTP endpoint is enabled, for example by following the steps described in "To Set Up REST Access to User Data", or the steps described in "To Set Up REST Access to Administrative Data". It is possible to enable multiple HTTP endpoints, as long as their base paths are different.

1. If you did not enable the HTTP connection handler during the setup process with the --httpPort or --httpsPort option, create the connection handler configuration:

   $ dsconfig \
    create-connection-handler \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --handler-name "HTTP Connection Handler" \
    --type http \
    --set enabled:true \
    --set listen-port:8080 \
    --no-prompt \
    --trustAll
       

2. (Optional) Enable an HTTP access log.

   • The following command enables JSON-based HTTP access logging as described in "Configuring JSON Access Logs":

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

   • The following command enables HTTP access logging as described in "Standard HTTP Access Logs":

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

3. (Optional) If necessary, change the connection handler configuration using the dsconfig command.

The following steps demonstrate how to change the default HTTP connection handler configuration to use only HTTPS:

1. Make sure a server certificate and associated private key are available:

   $ keytool \
    -list \
    -alias server-cert \
    -keystore /path/to/opendj/config/keystore \
    -storepass:file /path/to/opendj/config/keystore.pin \
    -storetype PKCS12
   ...
   server-cert, <date>, PrivateKeyEntry
   ...
       

2. Disable the HTTP connection handler to prevent (cleartext) HTTP access:

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

3. Configure the HTTP connection handler to use HTTPS access.

   The following example shows how to set the port to 8443 and perform TLS using the default server certificate:

   $ dsconfig \
    set-connection-handler-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --handler-name "HTTP Connection Handler" \
    --set enabled:true \
    --set listen-port:8443 \
    --set use-ssl:true \
    --set key-manager-provider:"Default Key Manager" \
    --set trust-manager-provider:"JVM Trust Manager" \
    --trustAll \
    --no-prompt
     

4. (Optional) Enable the HTTP access log.

   • The following command enables JSON-based HTTP access logging as described in "Configuring JSON Access Logs":

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

   • The following command enables HTTP access logging as described in "Standard HTTP Access Logs":

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

5. (Optional) If the deployment requires SSL client authentication, set the properties ssl-client-auth-policy and trust-manager-provider appropriately.

6. After you set up the HTTP connection handler, make sure that at least one HTTP endpoint configuration object is enabled.

   For details, see "To Set Up REST Access to User Data" or "To Set Up REST Access to Administrative Data".

The way directory data appears to client applications is configurable. You can configure one or more Rest2ldap endpoints to expose user directory data over HTTP. The mapping defined for the Rest2ldap endpoint defines a mapping between JSON resources and LDAP entries. The mapping is expressed in a configuration file, by default /path/to/opendj/config/rest2ldap/endpoints/api/example-v1.json. The configuration is described in "REST to LDAP Configuration" in the Reference.

The default Rest2ldap endpoint exposes the RESTful API demonstrated in "Performing RESTful Operations" in the Developer's Guide. The default mapping works out of the box with Example.com data generated as part of the setup process and with example data imported from Example.ldif:

1. (Optional) If necessary, change the properties of the default Rest2ldap endpoint, or create a new endpoint.

   A Rest2ldap HTTP endpoint named /api after its base-path is provided by default. The base-path must be the same as the name, and is read-only after creation. By default, the /api endpoint requires authentication.

   The following example enables the /api endpoint using the default mapping and HTTP Basic authorization. Adjust these settings as necessary:

   $ dsconfig \
    set-http-endpoint-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --endpoint-name /api \
    --set authorization-mechanism:"HTTP Basic" \
    --set config-directory:config/rest2ldap/endpoints/api \
    --set enabled:true \
    --no-prompt \
    --trustAll
       

   Alternatively, you can create another Rest2ldap endpoint to expose a different view of the directory data, or to publish data under an alternative base path, such as /rest:

   $ dsconfig \
    create-http-endpoint \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --endpoint-name /rest \
    --type rest2ldap-endpoint \
    --set authorization-mechanism:"HTTP Basic" \
    --set config-directory:config/rest2ldap/endpoints/api \
    --set enabled:true \
    --no-prompt \
    --trustAll
       

2. (Optional) If necessary, adjust the endpoint configuration to use an alternative HTTP authorization mechanism.

   By default, the Rest2ldap endpoint maps HTTP Basic authentication to LDAP authentication to set the authorization identity for operations. You can change the authorization-mechanism setting to use a different HTTP authorization mechanism as described in "To Set Up HTTP Authorization".

3. (Optional) Try reading a resource.

   The following example demonstrates reading the resource that corresponds to Barbara Jensen's entry as a JSON resource:

   $ curl http://bjensen:hifalutin@opendj.example.com:8080/api/users/bjensen?_prettyPrint=true
   {
     "_id" : "bjensen",
     "_rev" : "<revision>",
     "_schema" : "frapi:opendj:rest2ldap:posixUser:1.0",
     "_meta" : { },
     "userName" : "bjensen@example.com",
     "displayName" : [ "Barbara Jensen", "Babs Jensen" ],
     "name" : {
       "givenName" : "Barbara",
       "familyName" : "Jensen"
     },
     "description" : "Original description",
     "contactInformation" : {
       "telephoneNumber" : "+1 408 555 1862",
       "emailAddress" : "bjensen@example.com"
     },
     "uidNumber" : 1076,
     "gidNumber" : 1000,
     "homeDirectory" : "/home/bjensen",
     "manager" : {
       "_id" : "trigden",
       "displayName" : "Torrey Rigden"
     }
   }
       

4. (Optional) If the HTTP connection handler is configured to use HTTPS, try reading an entry over HTTPS.

   The following example writes the (self-signed) server certificate into a trust store file, and uses the file to trust the server when setting up the HTTPS connection:

   $ keytool \
    -export \
    -rfc \
    -alias server-cert \
    -keystore /path/to/opendj/config/keystore \
    -storepass:file /path/to/opendj/config/keystore.pin \
    -storetype PKCS12 \
    -file server-cert.pem
   Certificate stored in file <server-cert.pem>
   
   $ curl \
    --cacert server-cert.pem \
    --user bjensen:hifalutin \
    https://opendj.example.com:8443/api/users/bjensen?_prettyPrint=true
   {
     "_id" : "bjensen",
     "_rev" : "<revision>",
     "_schema" : "frapi:opendj:rest2ldap:posixUser:1.0",
     "_meta" : { },
     "userName" : "bjensen@example.com",
     "displayName" : [ "Barbara Jensen", "Babs Jensen" ],
     "name" : {
       "givenName" : "Barbara",
       "familyName" : "Jensen"
     },
     "description" : "Original description",
     "contactInformation" : {
       "telephoneNumber" : "+1 408 555 1862",
       "emailAddress" : "bjensen@example.com"
     },
     "uidNumber" : 1076,
     "gidNumber" : 1000,
     "homeDirectory" : "/home/bjensen",
     "manager" : {
       "_id" : "trigden",
       "displayName" : "Torrey Rigden"
     }
   }
       

   Notice the --cacert server-cert.pem option used with the curl command. This is the way to specify a self-signed server certificate when using HTTPS.

HTTP authorization mechanisms define how OpenDJ servers authorize client HTTP requests to directory data. Authorization mechanisms map credentials from an HTTP-based protocol, such as HTTP Basic authentication or OAuth 2.0, to LDAP credentials.

Multiple HTTP authorization mechanisms can be enabled simultaneously, and assigned to HTTP endpoints, such as Rest2ldap endpoints described in "To Set Up REST Access to User Data" or the Admin endpoint described in "To Set Up REST Access to Administrative Data".

There are many possibilities when configuring HTTP authorization mechanisms. This procedure shows only one OAuth 2.0 example.

The example that follows demonstrates a server configured for tests (insecure connections) to request OAuth 2.0 token information from AM. It uses settings as listed in "Settings for OAuth 2.0 Example With AM".

Download ForgeRock Access Management software from https://backstage.forgerock.com/downloads.

Read the ForgeRock Access Management documentation if necessary to install and configure AM. Then follow these steps to try the demonstration:

1. Update the default HTTP OAuth2 OpenAM configuration:

   $ dsconfig \
    set-http-authorization-mechanism-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --mechanism-name "HTTP OAuth2 OpenAM" \
    --set enabled:true \
    --set token-info-url:http://openam.example.com:8088/openam/oauth2/tokeninfo \
    --no-prompt \
    --trustAll
       

2. Update the default Rest2ldap endpoint configuration to use HTTP OAuth2 OpenAM as the authorization mechanism:

   $ dsconfig \
    set-http-endpoint-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --endpoint-name "/api" \
    --set authorization-mechanism:"HTTP OAuth2 OpenAM" \
    --no-prompt \
    --trustAll
       

3. Obtain an access token with the appropriate scopes:

   $ curl \
    --request POST \
    --user "myClientID:password" \
    --data "grant_type=password&username=bjensen&password=hifalutin&scope=read%20uid%20write" \
    http://openam.example.com:8088/openam/oauth2/access_token
   {
    "access_token": "token-string",
    "scope": "uid read write",
    "token_type": "Bearer",
    "expires_in": 3599
   }
       

   In production systems, make sure you use HTTPS when obtaining access tokens.

4. Request a resource at the Rest2ldap endpoint using HTTP Bearer authentication with the access token:

   $ curl \
    --header "Authorization: Bearer token-string" \
    http://opendj.example.com:8080/api/users/bjensen?_prettyPrint=true
   {
     "_id": "bjensen",
     "_rev": "<revision>",
     "_schema": "frapi:opendj:rest2ldap:posixUser:1.0",
     "_meta": {},
     "userName": "bjensen@example.com",
     "displayName": ["Barbara Jensen", "Babs Jensen"],
     "name": {
       "givenName": "Barbara",
       "familyName": "Jensen"
     },
     "description": "Original description",
     "contactInformation": {
       "telephoneNumber": "+1 408 555 1862",
       "emailAddress": "bjensen@example.com"
     },
     "uidNumber": 1076,
     "gidNumber": 1000,
     "homeDirectory": "/home/bjensen",
     "manager": {
       "_id": "trigden",
       "displayName": "Torrey Rigden"
     }
   }
       

   In production systems, make sure you use HTTPS when presenting access tokens.

To use the Admin endpoint APIs, follow these steps:

1. Grant users access to the endpoints as appropriate:

   • For access to /admin/config, assign config-read or config-write privileges.

     The following example assigns the config-read privilege to Kirsten Vaughan:

     $ cat config-read.ldif
     dn: uid=kvaughan,ou=People,dc=example,dc=com
     changetype: modify
     add: ds-privilege-name
     ds-privilege-name: config-read
     
     $ ldapmodify \
      --port 1389 \
      --bindDN "cn=Directory Manager" \
      --bindPassword password \
      config-read.ldif
           

     For more detail, see "Configuring Privileges".

   • For access to /admin/monitor, authenticated users can read information.

2. (Optional) If necessary, adjust the authorization-mechanism setting for the Admin endpoint.

   By default, the Admin endpoint uses the HTTP Basic authorization mechanism. The HTTP Basic authorization mechanism default configuration resolves the user identity extracted from the HTTP request to an LDAP user identity as follows:

   1. If the request has an Authorization: Basic header for HTTP Basic authentication, the server extracts the username and password.

   2. If the request has X-OpenIDM-Username and X-OpenIDM-Password headers, the server extracts the username and password.

   3. The server uses the default Exact Match identity mapper to search for a unique match between the username and the UID attribute value of an entry in the public naming contexts of the OpenDJ server.

      In other words, in LDAP terms, it searches under all user data base DNs for (uid=http-username). The username kvaughan maps to the example entry with DN uid=kvaughan,ou=People,dc=example,dc=com.

   For details on configuring HTTP authorization mechanisms, see "To Set Up HTTP Authorization".

3. (Optional) Consider protecting traffic to the Admin endpoint by using HTTPS as described in "To Set Up HTTP Access".

4. Test access to the endpoint as an authorized user.

   The examples below use the (self-signed) server certificate which the following command writes into file named server-cert.pem:

   $ keytool \
    -export \
    -rfc \
    -alias server-cert \
    -keystore /path/to/opendj/config/keystore \
    -storepass:file /path/to/opendj/config/keystore.pin \
    -storetype PKCS12 \
    -file server-cert.pem
   Certificate stored in file <server-cert.pem>
       

   The following example demonstrates reading the Admin endpoint resource under /admin/config:

   $ curl \
    --cacert server-cert.pem \
    --user kvaughan:bribery \
    https://opendj.example.com:8443/admin/config/http-endpoints/%2Fadmin?_prettyPrint=true
   {
     "_id" : "/admin",
     "_rev" : "<revision>",
     "_schema" : "admin-endpoint",
     "java-class" : "org.opends.server.protocols.http.rest2ldap.AdminEndpoint",
     "base-path" : "/admin",
     "enabled" : true,
     "authorization-mechanism" : "HTTP Basic"
   }
       

   Notice how the path to the resource in the example above, /admin/config/http-endpoints/%2Fadmin, corresponds to the DN of the entry under cn=config, which is ds-cfg-base-path=/admin,cn=HTTP Endpoints,cn=config.

   The following example demonstrates reading everything under /admin/monitor:

   $ curl \
    --cacert server-cert.pem \
    --user kvaughan:bribery \
    https://opendj.example.com:8443/admin/monitor?_queryFilter=true
       

Follow these steps to set up OpenDJ REST to LDAP gateway Servlet to access your directory service.

1. Download and install the gateway as described in "To Install the REST to LDAP Gateway" in the Installation Guide.

2. Adjust the configuration for your directory service as described in "REST to LDAP Configuration" in the Reference.

• Configure the server to activate JMX access.

  The following example uses the reserved port number, 1689:

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

  The change takes effect immediately.

After you set up an OpenDJ server to listen for JMX connections, you must assign privileges in order to allow a user to connect over JMX:

1. Assign the privileges, jmx-notify, jmx-read, and jmx-write as necessary to the user who connects over JMX.

   For details see "Configuring Privileges".

2. Connect using the service URI, user name, and password:

   Service URI

   Full URI to the service including the hostname or IP address and port number for JMX where the OpenDJ server listens for connections.

   For example, if the server hostname is opendj.example.com, and the OpenDJ server listens for JMX connections on port 1689, then the service URI is service:jmx:rmi:///jndi/rmi://opendj.example.com:1689/org.opends.server.protocols.jmx.client-unknown.

   User name

   The full DN of the user with privileges to connect over JMX, such as cn=My App,ou=Apps,dc=example,dc=com.

   Password

   The bind password for the user.

1. Add the directory where you put LDIF to be processed:

   $ mkdir /path/to/opendj/config/auto-process-ldif
       

   This example uses the default value of the ldif-directory property for the LDIF connection handler.

2. Activate LDIF file access:

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

   The change takes effect immediately.

Follow these steps to change default privileges for all Root DN administrators, whose entries are under cn=Root DNs,cn=config.

1. Start dsconfig in interactive mode:

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

2. Select the Root DN menu.

3. Select View and edit the Root DN.

4. Edit the default-root-privilege-name.

5. Make sure you apply the changes when finished.

Privileges are specified using the ds-privilege-name operational attribute, which you can change using the ldapmodify command.

1. Determine the privileges to add:

   $ cat privileges.ldif
   dn: uid=kvaughan,ou=People,dc=example,dc=com
   changetype: modify
   add: ds-privilege-name
   ds-privilege-name: config-read
   ds-privilege-name: password-reset
   
      

   This example lets the user read the server configuration, and reset user passwords. In order for the user to be able to change a user password, you must also allow the modification using ACIs.

   For this example, Kirsten Vaughan is a member of the Directory Administrators group for Example.com, and already has access to modify user entries.

   Prior to having the privileges, Kirsten gets messages about insufficient access when trying to read the server configuration, or trying to reset a user password:

   $ ldapsearch \
    --port 1389 \
    --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
    --bindPassword bribery \
    --baseDN cn=config \
    "(objectclass=*)"
   # The LDAP search request failed: 50 (Insufficient Access Rights)
   # Additional Information:  You do not have sufficient privileges to perform search operations in the Directory Server configuration
   $ ldappasswordmodify \
    --port 1389 \
    --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
    --bindPassword bribery \
    --authzID "dn:uid=scarter,ou=People,dc=example,dc=com" \
    --newPassword changeit
   The LDAP password modify operation failed: 50 (Insufficient Access Rights)
   Additional Information:  You do not have sufficient privileges to perform
   password reset operations
      

2. Apply the change as a user with the privilege-change privilege:

   $ ldapmodify \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    privileges.ldif
      

   At this point, Kirsten can perform the operations requiring privileges:

   $ ldapsearch \
    --port 1389 \
    --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
    --bindPassword bribery \
    --baseDN cn=config \
    "(objectclass=*)"
   dn: cn=config
   …
   $ ldappasswordmodify \
    --port 1389 \
    --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
    --bindPassword bribery \
    --authzID "dn:uid=scarter,ou=People,dc=example,dc=com" \
    --newPassword changeit
   The LDAP password modify operation was successful
      

For deployments with more than one administrator, use groups to define administrative rights.

You can use a collective attribute subentry to specify privileges for the administrator group.

Collective attributes provide a standard mechanism for defining attributes that appear on all the entries in a particular subtree. For details, see "Collective Attributes" in the Developer's Guide. An OpenDJ server extends collective attributes to give you fine-grained control over which entries are in scope. In addition, an OpenDJ server lets you use virtual attributes, such as isMemberOf to construct the filter for targeting entries in scope. This allows you, for example, to define administrative privileges that apply to all users who belong to an administrator group:

1. Create an LDAP subentry that specifies the collective attributes:

   $ cat collective.ldif
   dn: cn=Administrator Privileges,dc=example,dc=com
   objectClass: collectiveAttributeSubentry
   objectClass: extensibleObject
   objectClass: subentry
   objectClass: top
   cn: Administrator Privileges
   ds-privilege-name;collective: config-read
   ds-privilege-name;collective: config-write
   ds-privilege-name;collective: ldif-export
   ds-privilege-name;collective: modify-acl
   ds-privilege-name;collective: password-reset
   ds-privilege-name;collective: proxied-auth
   subtreeSpecification: {base "ou=people", specificationFilter
     "(isMemberOf=cn=Directory Administrators,ou=Groups,dc=example,dc=com)" }
   
   $ ldapmodify \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    collective.ldif
      

   The Directory Administrators group for Example.com includes members like Harry Miller.

   The base entry identifies the branch that holds administrator entries. For details on how subentries apply, see "Understanding Subentry Scope".

2. Observe that the change takes effect immediately:

   $ ldappasswordmodify \
    --port 1389 \
    --bindDN "uid=hmiller,ou=people,dc=example,dc=com" \
    --bindPassword hillock \
    --authzID "dn:uid=scarter,ou=People,dc=example,dc=com"
   The LDAP password modify operation was successful
   Generated Password:  <password>
      

When privileges are set as described in "To Add Privileges for a Group of Administrators", the same list of privileges is applied to every target account. An OpenDJ server also assigns default directory root DN privileges as described in "To Change Default Root DN Privileges".

In some cases, the list of inherited privileges can be too broad. OpenDJ servers have a mechanism to limit effective privileges by preceding the privilege attribute value with a -.

The following steps show how to prevent Kirsten Vaughan from resetting passwords when the privilege is assigned as described in "To Add Privileges for a Group of Administrators":

1. Check the privilege settings for the account:

   $ ldapsearch \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --baseDN dc=example,dc=com \
    "(uid=kvaughan)" \
    ds-privilege-name
   dn: uid=kvaughan,ou=People,dc=example,dc=com
   ds-privilege-name: config-read
   ds-privilege-name: password-reset
      

2. Set the privilege attribute for the account to deny the privilege:

   $ cat restrict-privileges.ldif
   dn: uid=kvaughan,ou=people,dc=example,dc=com
   changetype: modify
   add: ds-privilege-name
   ds-privilege-name: -password-reset
   
   $ ldapmodify \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    restrict-privileges.ldif
      

3. Observe that the privilege is no longer in effect:

   $ ldappasswordmodify \
    --port 1389 \
    --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
    --bindPassword bribery \
    --authzID "dn:uid=scarter,ou=People,dc=example,dc=com"
   The LDAP password modify operation failed: 50 (Insufficient Access Rights)
   Additional Information:  You do not have sufficient privileges to perform
   password reset operations
      

OpenDJ directory servers that are not replicated do not publish an external change log. A directory server that publishes a change log must function as both a directory server, and a replication server for the suffix whose changes you want logged.

• Configure replication without using the --noReplicationServer or --onlyReplicationServer option.

  With replication configured, the data is under cn=changelog. The user reading the changelog must have appropriate access, and must have the changelog-read privilege. Directory Manager is not subject to access control, and has the privilege. The following example shows that Directory Manager can read the changelog:

  $ ldapsearch \
   --hostname opendj.example.com \
   --port 1389 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   --baseDN cn=changelog \
   --searchScope base \
   "(&)"
  dn: cn=changelog
  objectClass: top
  objectClass: container
  cn: changelog
      

  If the user reading the changelog is not Directory Manager, see "To Allow a User to Read the Change Log".

OpenDJ servers do not encrypt external change log data by default. This means that any user with system access to read directory files can potentially access external change log data in cleartext.

In addition to preventing read access by other users as described in "Setting Up a System Account for an OpenDJ Server", you can configure confidentiality for external change log data. When confidentiality is enabled, the server encrypts change log records before storing them.

OpenDJ servers encrypt data using a symmetric key that is stored with the server configuration. The symmetric key is encrypted in turn with the server's public key that is also stored with the server configuration. When multiple servers are configured to replicate data as described in "Configuring Replication Settings", the servers replicate the keys as well, allowing any server replica to decrypt the data.

Encrypting and decrypting data comes with costs in terms of cryptographic processing that reduces throughput and of extra space for larger encrypted values. In general, tests with default settings show that the cost of enabling confidentiality can be quite modest, but your results can vary based on your systems and on the settings used for cipher-transformation and cipher-key-length. Make sure you test your deployment to qualify the impact of confidentiality before enabling it in production.

Follow this procedure to enable confidentiality:

1. Before you enable confidentiality on a replication server for the external change log data, first enable confidentiality for data stored in directory backends.

   For details, see "Encrypting Directory Data".

2. Enable backend confidentiality with the default encryption settings as shown in the following example:

   $ dsconfig \
    set-replication-server-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --provider-name "Multimaster Synchronization" \
    --set confidentiality-enabled:true \
    --no-prompt \
    --trustAll
       

   Encryption applies to the entire change log regardless of the confidentiality settings for each domain.

   After confidentiality is enabled, new change log records are encrypted. OpenDJ servers do not rewrite old records in encrypted form.

3. (Optional) If necessary, adjust additional confidentiality settings.

   Use the same cipher suite for external change log confidentiality as was used to configure data confidentiality.

   The default settings for confidentiality are cipher-transformation: AES/CBC/PKCS5Padding and cipher-key-length: 128. This means the algorithm is the Advanced Encryption Standard (AES), the cipher mode is Cipher Block Chaining (CBC), and the padding is PKCS#5 padding as described in RFC 2898: PKCS #5: Password-Based Cryptography Specification. The syntax for the cipher-transformation is algorithm/mode/padding, and all three must be specified. When the algorithm does not require a mode, use NONE. When the algorithm does not require padding, use NoPadding. Use of larger cipher-key-length values can require that you install JCE policy files such as those for unlimited strength, as described in "Using Unlimited Strength Cryptography" in the Security Guide.

You read the external change log over LDAP. In addition, when you poll the change log periodically, you can get the list of updates that happened since your last request.

The external change log mechanism uses an LDAP control with OID 1.3.6.1.4.1.26027.1.5.4 to allow the exchange of cookies for the client application to bookmark the last changes seen, and then start reading the next set of changes from where it left off on the previous request.

This procedure shows the client reading the change log as cn=Directory Manager. Make sure your client application reads the changes with sufficient access and privileges to view all the changes it needs to see.

1. Send an initial search request using the LDAP control with no cookie value:

   In this example, two changes appear in the changelog:

   $ ldapsearch \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --baseDN cn=changelog \
    --control "1.3.6.1.4.1.26027.1.5.4:false" \
    "(&)" \
    changes changeLogCookie targetDN
   # Public changelog exchange control(1.3.6.1.4.1.26027.1.5.4): <COOKIE1>
   dn: replicationCSN=<CSN1>,dc=example,dc=com,cn=changelog
   changes:: cmVwbGFjZTogZGVzY3JpcHRpb24KZGVzY3JpcHRpb246IE5ldyBkZXNjcmlwdGlvbgotCnJlcGxhY2U6IG1vZGlmaWVyc05hbWUKbW9kaWZpZXJzTmFtZTogdWlkPWJqZW5zZW4sb3U9UGVvcGxlLGRjPWV4YW1wbGUsZGM9Y29tCi0KcmVwbGFjZTogbW9kaWZ5VGltZXN0YW1wCm1vZGlmeVRpbWVzdGFtcDogMjAxNjEwMTQxNTA5MTJaCi0K
   targetDN: uid=bjensen,ou=People,dc=example,dc=com
   changeLogCookie: <COOKIE1>
   
   # Public changelog exchange control(1.3.6.1.4.1.26027.1.5.4): <COOKIE2>
   dn: replicationCSN=<CSN2>,dc=example,dc=com,cn=changelog
   changes:: cmVwbGFjZTogZGVzY3JpcHRpb24KZGVzY3JpcHRpb246IE5ldywgaW1wcm92ZWQgZGVzY3JpcHRpb24KLQpyZXBsYWNlOiBtb2RpZmllcnNOYW1lCm1vZGlmaWVyc05hbWU6IHVpZD1iamVuc2VuLG91PVBlb3BsZSxkYz1leGFtcGxlLGRjPWNvbQotCnJlcGxhY2U6IG1vZGlmeVRpbWVzdGFtcAptb2RpZnlUaW1lc3RhbXA6IDIwMTYxMDE0MTUwOTE5WgotCg==
   targetDN: uid=bjensen,ou=People,dc=example,dc=com
   changeLogCookie: <COOKIE2>
       

   The changes are base64-encoded. You can decode them using the base64 command. The following example decodes the first change:

   $ base64 decode --encodedData cmVwbGFjZTogZGVzY3JpcHRpb24KZGVzY3JpcHRpb246IE5ldyBkZXNjcmlwdGlvbgotCnJlcGxhY2U6IG1vZGlmaWVyc05hbWUKbW9kaWZpZXJzTmFtZTogdWlkPWJqZW5zZW4sb3U9UGVvcGxlLGRjPWV4YW1wbGUsZGM9Y29tCi0KcmVwbGFjZTogbW9kaWZ5VGltZXN0YW1wCm1vZGlmeVRpbWVzdGFtcDogMjAxNjEwMTQxNTA5MTJaCi0K
   replace: description
   description: New description
   -
   replace: modifiersName
   modifiersName: uid=bjensen,ou=People,dc=example,dc=com
   -
   replace: modifyTimestamp
   modifyTimestamp: <timestamp>
   -
       

   Notice the changeLogCookie value, which has the form base-dn:CSN.

2. To start reading a particular change in the changelog, provide the cookie with the control:

   $ ldapsearch \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --baseDN cn=changelog \
    --control "1.3.6.1.4.1.26027.1.5.4:false:$COOKIE1" \
    "(&)" \
    changes changeLogCookie targetDN
   # Public changelog exchange control(1.3.6.1.4.1.26027.1.5.4): <COOKIE2>
   dn: replicationCSN=<CSN2>,dc=example,dc=com,cn=changelog
   changes:: cmVwbGFjZTogZGVzY3JpcHRpb24KZGVzY3JpcHRpb246IE5ldywgaW1wcm92ZWQgZGVzY3JpcHRpb24KLQpyZXBsYWNlOiBtb2RpZmllcnNOYW1lCm1vZGlmaWVyc05hbWU6IHVpZD1iamVuc2VuLG91PVBlb3BsZSxkYz1leGFtcGxlLGRjPWNvbQotCnJlcGxhY2U6IG1vZGlmeVRpbWVzdGFtcAptb2RpZnlUaW1lc3RhbXA6IDIwMTYxMDE0MTUwOTE5WgotCg==
   targetDN: uid=bjensen,ou=People,dc=example,dc=com
   changeLogCookie: <COOKIE2>
       

   The following command decodes the changes:

   $ base64 decode --encodedData cmVwbGFjZTogZGVzY3JpcHRpb24KZGVzY3JpcHRpb246IE5ldywgaW1wcm92ZWQgZGVzY3JpcHRpb24KLQpyZXBsYWNlOiBtb2RpZmllcnNOYW1lCm1vZGlmaWVyc05hbWU6IHVpZD1iamVuc2VuLG91PVBlb3BsZSxkYz1leGFtcGxlLGRjPWNvbQotCnJlcGxhY2U6IG1vZGlmeVRpbWVzdGFtcAptb2RpZnlUaW1lc3RhbXA6IDIwMTYxMDE0MTUwOTE5WgotCg==
   replace: description
   description: New, improved description
   -
   replace: modifiersName
   modifiersName: uid=bjensen,ou=People,dc=example,dc=com
   -
   replace: modifyTimestamp
   modifyTimestamp: <timestamp>
   -
       

3. If you lose the cookie, start over from the earliest available change by sending a search request with no value for the cookie.

For a user to read the changelog, the user must have access to read, search, and compare changelog attributes, might have access to use the control to read the external changelog, and must have the changelog-read privilege.

1. Give the user access to read and search the changelog.

   The following example adds a global ACI to give My App access to the changelog:

   $ dsconfig \
    set-access-control-handler-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --add global-aci:"(target=\"ldap:///cn=changelog\")(targetattr=\"*||+\")\
   (version 3.0; acl \"My App can access cn=changelog\"; \
   allow (read,search,compare) \
   userdn=\"ldap:///cn=My App,ou=Apps,dc=example,dc=com\";)" \
    --trustAll \
    --no-prompt
       

2. Give the user access to use the control.

   The following example adds a global ACI to give My App access to use the control:

   $ dsconfig \
    set-access-control-handler-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --add global-aci:"(targetcontrol=\"1.3.6.1.4.1.26027.1.5.4\")\
   (version 3.0; acl \"My App control access\"; \
   allow (read) \
   userdn=\"ldap:///cn=My App,ou=Apps,dc=example,dc=com\";)" \
    --trustAll \
    --no-prompt
       

3. Give the user the changelog-read privilege:

   $ cat changelog-read.ldif
   dn: cn=My App,ou=Apps,dc=example,dc=com
   changetype: modify
   add: ds-privilege-name
   ds-privilege-name: changelog-read
   
   $ ldapmodify \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    changelog-read.ldif
       

4. Check that the user can read the changelog:

   $ ldapsearch \
    --hostname opendj.example.com \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --baseDN cn=changelog \
    --control "1.3.6.1.4.1.26027.1.5.4:false" \
    "(&)" \
    changes changeLogCookie targetDN
       

As shown above, the changes returned from a search on the external change log include only what was actually changed. If you have applications that need additional attributes published with every change log entry, regardless of whether or not the attribute itself has changed, then specify those using ecl-include and ecl-include-for-deletes.

1. Set the attributes to include for all update operations with ecl-include:

   $ dsconfig \
    set-external-changelog-domain-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --provider-name "Multimaster Synchronization" \
    --domain-name dc=example,dc=com \
    --set ecl-include:"@person" \
    --trustAll \
    --no-prompt
       

2. Set the attributes to include for deletes with ecl-include-for-deletes:

   $ dsconfig \
    set-external-changelog-domain-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --provider-name "Multimaster Synchronization" \
    --domain-name dc=example,dc=com \
    --add ecl-include-for-deletes:"*" \
    --add ecl-include-for-deletes:"+" \
    --trustAll \
    --no-prompt
       

The external change log can be used by applications that follow the Internet-Draft: Definition of an Object Class to Hold LDAP Change Records, and that cannot use change log cookies shared across the replication topology. Nothing special is required to get the objects specified for this legacy format, but there are steps you must perform to align change numbers across replicas.

Change numbers described in the Internet-Draft are simple numbers, not cookies. When change log numbers are aligned across replicas, applications fail over from one replica to another when necessary.

If you do not align the change numbers, each server keeps its own count. The same change numbers can refer to different changes on different replicas.

For example, if you install a new replica and initialize replication from an existing server, the last change numbers are likely to differ. The following example shows different last change numbers for an existing server and for a new replica that has just been initialized from the existing replica:

$ ldapsearch \
 --hostname existing.example.com \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --baseDN "" \
 --searchScope base \
 "(&)" lastChangeNumber
dn:
lastChangeNumber: 285924


Result Code:  0 (Success)

$ ldapsearch \
 --hostname new.example.com \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --baseDN "" \
 --searchScope base \
 "(&)" lastChangeNumber
dn:
lastChangeNumber: 198643


Result Code:  0 (Success)
   

When you add a new replica to an existing topology, follow these steps to align the change numbers with those of an existing server.

These steps can also be used at any time to align the change numbers:

1. Make sure that the new replica has the same replication configuration as the existing replica.

   Specifically, both replicas must replicate the same suffixes in order for the change number calculations to be the same on both replicas. If the suffix configurations differ, the change numbers cannot be aligned.

2. (Optional) If you must start the new replica's change numbering from a specific change, determine the changeNumber to use.

   The changeNumber must be from a change that has not yet been purged according to the replication purge delay, which by default is three days.

3. Using the dsreplication command installed with the new replica, reset the change number on the new replica to the change number from the existing replica.

   The following example does not specify the change number to use. By default, the new replica uses the last change number from the existing replica:

   $ dsreplication \
    reset-change-number \
    --adminUID admin \
    --adminPassword password \
    --hostSource existing.example.com \
    --portSource 4444 \
    --hostDestination new.example.com \
    --portDestination 4444 \
    --trustAll \
    --no-prompt
   Change-log change number reset task has finished successfully.
   ...
       

   At this point, the new replica's change log starts with the last change number from the existing replica. Earlier change numbers are no longer present in the new replica's change log.

In development and test environments, you can enable the external change log on a single server, without actually replicating directory data. If you use replication and replicated servers, follow the instructions in "To Enable the External Change Log" instead.

Follow these steps to enable the external change log on a single standalone directory server:

1. Create a replication server configuration entry as in the following example:

   $ dsconfig \
    create-replication-server \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --provider-name "Multimaster Synchronization" \
    --set replication-port:8989 \
    --set replication-server-id:2 \
    --trustAll \
    --no-prompt
       

2. Create a replication domain configuration entry as in the following example:

   $ dsconfig \
    create-replication-domain \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --provider-name "Multimaster Synchronization" \
    --domain-name "Example.com" \
    --set base-dn:dc=example,dc=com \
    --set replication-server:opendj.example.com:8989 \
    --set server-id:3 \
    --trustAll \
    --no-prompt
       

   At this point, you can begin using the external change log under cn=changelog.

By default, a replication server indexes change numbers for replicated user data. This allows legacy applications to get update notifications by change number, as described in "To Align Draft Change Numbers". Indexing change numbers requires additional CPU, disk accesses and storage, so it should not be used unless change number-based browsing is required.

Disable change number indexing if it is not needed:

• If no applications need change number-based notifications, set compute-change-number:false in the Configuration Reference on each server after enabling replication.

To perform online backup, you start backup as a task by connecting to the administrative port and authenticating as a user with the backend-backup privilege, and also setting a start time for the task by using the --start option.

To perform offline backup when an OpenDJ directory server is stopped, you run the backup command, described in backup(1) in the Reference, without connecting to the server, authenticating, or requesting a backup task.

• Use one of the following alternatives:

  • Back up only the database for Example.com, where the data is stored in the backend named userRoot.

    The following example requests an online backup task that starts immediately, backing up only the userRoot backend:

    $ backup \
     --hostname opendj.example.com \
     --port 4444 \
     --bindDN "cn=Directory Manager" \
     --bindPassword password \
     --backendID userRoot \
     --backupDirectory /path/to/opendj/bak/userRoot \
     --start 0 \
     --trustAll
          

  • Stop the server to back up Example.com data offline.

    The following example stops the OpenDJ server, runs offline backup, and starts the server after backup has completed:

    $ stop-ds --quiet
    $ backup --offline --backendID userRoot --backupDirectory /path/to/opendj/bak/userRoot
    $ start-ds --quiet
          

  • Back up all user data on the server.

    The following example requests an online backup task that starts immediately, backing up all backends:

    $ backup \
     --hostname opendj.example.com \
     --port 4444 \
     --bindDN "cn=Directory Manager" \
     --bindPassword password \
     --backUpAll \
     --backupDirectory /path/to/opendj/bak \
     --start 0 \
     --trustAll
          

You can schedule online data backup using crontab format.

• Back up all user data every night at 2 AM, and notify diradmin@example.com when finished, or on error:

  $ backup \
   --hostname opendj.example.com \
   --port 4444 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   --backUpAll \
   --backupDirectory /path/to/opendj/bak \
   --recurringTask "00 02 * * *" \
   --completionNotify diradmin@example.com \
   --errorNotify diradmin@example.com \
   --trustAll
      

You can schedule an incremental backup by using the --incremental option. If you do not set the --incrementalBaseID option, then the server increments based on the last backup taken.

• Back up userRoot backend data incrementally every night at 3 AM, and notify diradmin@example.com when finished, or on error:

  $ backup \
   --hostname opendj.example.com \
   --port 4444 \
   --bindDN "cn=Directory Manager" \
   --bindPassword password \
   --backupDirectory /path/to/opendj/bak/userRoot \
   --backendID userRoot \
   --incremental \
   --recurringTask "00 03 * * *" \
   --completionNotify diradmin@example.com \
   --errorNotify diradmin@example.com \
   --trustAll
      

To restore directory data when the server is online, you start a restore task by connecting to the administrative port and authenticating as a user with the backend-restore privilege. You set a start time for the task with the --start option.

To restore data when the server is offline, you run the restore command, described in restore(1) in the Reference, without connecting to the server, authenticating, or requesting a restore task.

• Use one of the following alternatives:

  • Stop the server to restore data for Example.com.

    The following example stops the server, restores data offline from one of the available backups, and starts the server after the restore is complete:

    $ stop-ds --quiet
    $ restore --offline --backupDirectory /path/to/opendj/bak/userRoot --listBackups
    Backup ID:          <BACKUP_ID1>
    Backup Date:        <DATESTAMP1>
    Is Incremental:     false
    Is Compressed:      false
    Is Encrypted:       false
    Has Unsigned Hash:  false
    Has Signed Hash:    false
    Dependent Upon:     none
    
    Backup ID:          <BACKUP_ID2>
    Backup Date:        <DATESTAMP2>
    Is Incremental:     false
    Is Compressed:      false
    Is Encrypted:       false
    Has Unsigned Hash:  false
    Has Signed Hash:    false
    Dependent Upon:     none
    $ restore --offline --backupDirectory /path/to/opendj/bak/userRoot --backupID ${BACKUP_ID1}
    $ start-ds --quiet
          

  • Schedule the restore as a task to begin immediately.

    The following example requests an online restore task, scheduled to start immediately:

    $ restore \
     --hostname opendj.example.com \
     --port 4444 \
     --bindDN "cn=Directory Manager" \
     --bindPassword password \
     --backupDirectory /path/to/opendj/bak/userRoot \
     --backupID ${BACKUP_ID1} \
     --start 0 \
     --trustAll
          

After you restore a replica from backup, replication brings the replica up to date with changes that happened after you created the backup. In order to bring the replica up to date, replication must apply changes that happened after the backup was made. Replication uses internal change log records to determine what changes to apply.

Internal change log records are not kept forever, though. Replication is configured to purge the change log of old changes, preventing the log from growing indefinitely. Yet, for replication to determine what changes to apply to a restored replica, it must find change log records dating back at least to the last change in the backup. In other words, replication can bring the restored replica up to date as long as the change log records used to determine which changes to apply have not been purged.

Therefore, when you restore a replicated server from backup, make sure the backup you use is newer than the last purge of the replication change log (default: 3 days). If all your backups are older than the replication purge delay, do not restore from a backup, but instead initialize a new replica as described in "Initializing Replicas".

1. (Optional) When restoring data from encrypted backup, configure replication between the new replica server and a server from the existing topology as described in "Configuring Replication".

   If the backup is not encrypted, you can skip this step.

   This step initiates the OpenDJ server's key distribution capability, which makes it possible for the replica to obtain secret keys for decrypting backup data from existing replicas. Without the secret key for decryption, the new server cannot read the encrypted backup to restore.

   Important

   After a disaster leading to the loss of all servers in the replication topology, you must first restore a server from file system backup as described in "Backing Up Directory Data".

   When the restored server is running, configure replication between the new replica server and the restored server.

   It is not necessary to initialize replication in this step, as you will restore the data in the next step.

2. Restore the server database from the backup archive that you are sure is newer than the last purge of the replication change log.

   For examples of restoring from backup, see "To Restore a Standalone Server".

You can reconfigure the default password policy, for example, to check that passwords do not contain complete attribute values, and to prevent password reuse. The default policy is a server-based password policy.

1. Apply the changes to the default password policy:

   $ dsconfig \
    set-password-policy-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --policy-name "Default Password Policy" \
    --set password-history-count:7 \
    --set password-validator:Attribute\ Value \
    --trustAll \
    --no-prompt
      

2. Check your work:

   $ dsconfig \
    get-password-policy-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --policy-name "Default Password Policy" \
    --trustAll
   Property                                  : Value(s)
   ------------------------------------------:--------------------------
   account-status-notification-handler       : -
   allow-expired-password-changes            : false
   allow-user-password-changes               : true
   default-password-storage-scheme           : Salted SHA-512
   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                    : 7
   password-history-duration                 : 0 s
   password-validator                        : Attribute Value
   previous-last-login-time-format           : -
   require-change-by-time                    : -
   require-secure-authentication             : false
   require-secure-password-changes           : false
      

3. Test changes to the default password policy.

   For example, the following tests demonstrate how the attribute value password validator works. The attribute value password validator rejects a new password when the password is contained in attribute values on the user's entry.

   By default, the attribute value password validator checks all attributes, checks whether portions of the password string match attribute values, where the portions are strings of length 5, and checks the reverse of the password as well:

   $ dsconfig \
    get-password-validator-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --validator-name Attribute\ Value \
    --trustAll \
    --no-prompt
   Property               : Value(s)
   -----------------------:---------
   check-substrings       : true
   enabled                : true
   match-attribute        : -
   min-substring-length   : 5
   test-reversed-password : true
      

   Consider the attributes present on Babs Jensen's entry:

   $ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=bjensen)"
   dn: uid=bjensen,ou=People,dc=example,dc=com
   objectClass: top
   objectClass: inetOrgPerson
   objectClass: posixAccount
   objectClass: organizationalPerson
   objectClass: person
   mail: bjensen@example.com
   roomNumber: 0209
   preferredLanguage: en, ko;q=0.8
   manager: uid=trigden, ou=People, dc=example,dc=com
   ou: Product Development
   ou: People
   givenName: Barbara
   telephoneNumber: +1 408 555 1862
   sn: Jensen
   cn: Barbara Jensen
   cn: Babs Jensen
   homeDirectory: /home/bjensen
   facsimileTelephoneNumber: +1 408 555 1992
   gidNumber: 1000
   uidNumber: 1076
   description: Original description
   uid: bjensen
   l: San Francisco
   departmentNumber: 3001
   street: 201 Mission Street Suite 2900
      

   Using the attribute value password validator, passwords like bjensen12 and babsjensenspwd are not valid because substrings of the password match complete attribute values:

   $ ldappasswordmodify \
    --port 1389 \
    --authzID "dn:uid=bjensen,ou=people,dc=example,dc=com" \
    --currentPassword hifalutin \
    --newPassword bjensen12
   The LDAP password modify operation failed: 19 (Constraint Violation)
   Additional Information:  The provided new password failed the validation
   checks defined in the server: The provided password was found in another
   attribute in the user entry
   
   $ ldappasswordmodify \
    --port 1389 \
    --authzID "dn:uid=bjensen,ou=people,dc=example,dc=com" \
    --currentPassword hifalutin \
    --newPassword babsjensenspwd
   The LDAP password modify operation failed: 19 (Constraint Violation)
   Additional Information:  The provided new password failed the validation
   checks defined in the server: The provided password was found in another
   attribute in the user entry
      

   The attribute value password validator does not check, however, whether the password contains substrings of attribute values:

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

   To avoid the problem of the latter example, you could use a dictionary password validator where the dictionary includes example.com. For an example using a dictionary password validator, see "To Configure the Default Policy to Meet NIST Requirements".

As described in "To Adjust the Default Password Policy", the default policy is a server-based password policy.

Follow these steps to make this the default password policy:

1. Create a password validator for a minimum length of 8 characters:

   $ dsconfig \
    create-password-validator \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --validator-name "At least 8 characters" \
    --type length-based \
    --set enabled:true\
    --set min-password-length:8 \
    --trustAll \
    --no-prompt
      

2. Create a password validator for checking common compromised passwords:

   # Obtain a copy of a dictionary list of common passwords:
   $ cp 10k_most_common.txt /path/to/opendj/config/
   $ dsconfig \
    create-password-validator \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --validator-name "Common passwords" \
    --type dictionary \
    --set enabled:true \
    --set dictionary-file:config/10k_most_common.txt \
    --trustAll \
    --no-prompt
      

3. Configure the password policy as the default:

   $ 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 \
    --set password-validator:"At least 8 characters" \
    --set password-validator:"Common passwords" \
    --trustAll \
    --no-prompt
      

4. Check that the default password policy works appropriately.

   The following example shows a rejected password modification:

   $ ldappasswordmodify \
    --port 1389 \
    --authzID "dn:uid=bjensen,ou=people,dc=example,dc=com" \
    --currentPassword hifalutin \
    --newPassword secret12
   The LDAP password modify operation failed: 19 (Constraint Violation)
   Additional Information:  The provided new password failed the validation
   checks defined in the server: The provided password was found in another
   attribute in the user entry
      

   The following example shows an accepted password modification:

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

You can add a password policy, for example, for new users who have not yet used their credentials to bind.

1. Create the new password policy:

   $ dsconfig \
    create-password-policy \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --policy-name "New Account Password Policy" \
    --set default-password-storage-scheme:"Salted SHA-512" \
    --set force-change-on-add:true \
    --set password-attribute:userPassword \
    --type password-policy \
    --trustAll \
    --no-prompt
      

2. Check your work:

   $ dsconfig \
    get-password-policy-prop \
    --hostname opendj.example.com \
    --port 4444 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    --policy-name "New Account Password Policy" \
    --trustAll
   Property                                  : Value(s)
   ------------------------------------------:---------------
   account-status-notification-handler       : -
   allow-expired-password-changes            : false
   allow-user-password-changes               : true
   default-password-storage-scheme           : Salted SHA-512
   deprecated-password-storage-scheme        : -
   expire-passwords-without-warning          : false
   force-change-on-add                       : true
   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                        : -
   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
      

   If you use a password policy like this, then you will want to change the user's policy again when the new user successfully updates the password. For instructions on assigning a server-based password policy, see "To Assign a Password Policy to a User".