Reference for ForgeRock® Directory Services, including bundled tools.

Preface

ForgeRock Identity Platform™ serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

The ForgeRock Common REST API works across the platform to provide common ways to access web resources and collections of resources.

This reference covers Directory Services configuration, tools, and other topics such as supported languages and standards. For the dsconfig command, also see Configuration Reference. For API specifications suitable for Directory Services developers, see the appropriate Javadoc.

Chapter 1. REST to LDAP Configuration

DS software offers two alternatives for access to directory data over HTTP:

DS servers have an HTTP connection handler that exposes RESTful APIs to directory data over HTTP (or HTTPS). You configure an HTTP connection handler, and the HTTP endpoints that it serves, by using the dsconfig command. For each HTTP endpoint served by an HTTP connection handler that exposes your directory data, you configure mappings between JSON resources and LDAP entries.
The DS REST to LDAP gateway runs in a Servlet container independent from the directory service. You configure the gateway to access the directory service by editing configuration files for the gateway web application.

The files for configuring the gateway and the JSON resource to LDAP entry mappings are in JSON format.

In DS server installations, the default location for the configuration files is under /path/to/opendj/config.

In a REST to LDAP gateway Servlet, the configuration files are under WEB-INF/classes.

The format and relative locations of the mapping files are the same for DS servers and the DS REST to LDAP gateway. Only DS REST to LDAP gateway, however, has files for configuring how the gateway connects to LDAP servers, how user identities extracted from HTTP requests map to LDAP user identities, and what LDAP features the gateway uses. In DS servers these capabilities are part of the server configuration.

The parser for REST to LDAP configuration files is lenient. It lets you include comments in the JSON, although the JSON standard does not allow comments.

The following list describes the configuration files, indicated by relative location under the configuration directory:

config.json (gateway only)

This file defines how the gateway connects to LDAP servers, and how user identities extracted from HTTP requests map to LDAP user identities.

For details, see "Gateway Configuration File".

rest2ldap/rest2ldap.json (gateway only)

This file defines which LDAP features the gateway uses.

For details, see "Gateway REST2LDAP Configuration File".

rest2ldap/endpoints/base-path/root-resource.json

These files define JSON resource to LDAP entry mappings.

For details about the configuration fields, see "Mapping Configuration File".

1.1. Gateway Configuration File

The config.json file for the REST to LDAP gateway can hold the configuration objects described in this section.

The order of the settings in the JSON file is not meaningful. Here, the order shown is that of the default configuration file:

security

Configures security parameters for establishing secure connections between the gateway (as a client) and the servers it contacts, such as LDAP directory servers and OAuth 2.0 authorization servers.

This field has the following properties:

trustManager (optional)

This setting configures how the servers are trusted. This setting is ignored for connections to LDAP servers if connectionSecurity is set to none:

file means trust server certificates signed by a CA that is trusted according to the file-based truststore configured with fileBasedTrustManager* settings described below.
jvm (default) means trust server certificates signed by a CA trusted by the Java environment.
trustAll means blindly trust all server certificates.
Caution
This setting is not secure and makes man-in-the-middle attacks possible.

fileBasedTrustManagerType (optional)

If trustManager is set to file, then this setting configures the format for the data in the truststore file specified by the fileBasedTrustManagerFile setting. Formats include the following, though other implementations might be supported as well, depending on the Java environment:

JKS specifies Java Keystore format.
PKCS12 specifies Public-Key Cryptography Standards 12 format.

fileBasedTrustManagerFile

If trustManager is set to file, then this setting must specify the location of the truststore file.

Example: /path/to/truststore

fileBasedTrustManagerPasswordFile (optional)

If trustManager is set to file, then this setting specifies the file containing the truststore password.

Example: /path/to/pinfile

keyManager (optional)

This setting configures how the keys are managed for the gateway when the gateway is acting as a client of an LDAP server or OAuth 2.0 authorization server. The client keys are used to establish a secure connection to a server when the server requires client authentication.

This field can take the following values:

jvm (default) means look for client keys in the default keystore for the Java environment.
file means look for client keys in the specified keystore file, configured with the fileBasedKeyManager* settings.
pkcs11 means look for client keys in a PKCS #11 cryptographic token, where the PIN file is configured with the pkcs11KeyManagerPasswordFile setting described below.

fileBasedKeyManagerFile

If keyManager is set to file, then this setting must specify the keystore file.

Example: /path/to/keystore

fileBasedKeyManagerPasswordFile (optional)

If keyManager is set to file, then this setting specifies the file containing the keystore password.

Example: /path/to/pinfile

fileBasedKeyManagerType (optional)

If keyManager is set to file, then this setting specifies the format of the keystore specified by the fileBasedKeyManagerFile setting. Formats include the following, though other implementations might be supported as well, depending on the Java environment:

JKS specifies Java Keystore format.
PKCS12 specifies Public-Key Cryptography Standards 12 format.

pkcs11KeyManagerPasswordFile (optional)

If keyManager is set to pkcs11, then this setting specifies the file containing the PKCS #11 token password.

Example: /path/to/pinfile

ldapConnectionFactories

Configures how the gateway connects to LDAP servers. This entire configuration object applies only to the REST to LDAP gateway.

Configures at least a connection factory for unauthenticated connections that are used for bind requests. By default, also configures a factory for authenticated connections that are used for searches during authentication and for proxied authorization operations.

The default configuration is set to connect to a local directory server listening for LDAP connections on port 1389, authenticating as the directory superuser, cn=Directory Manager, with the password password:

bind

Configures the unauthenticated connection factory for bind operations:

connectionSecurity (optional)

Whether connections to LDAP servers should be secured by using SSL or StartTLS. The following values are supported:

none (default) means connections use plain LDAP and are not secured.
ssl means connections are secured using LDAPS.
startTLS means connections are secured using LDAP and StartTLS.

If you set connectionSecurity, also review the trustManager and fileBasedTrustManager* settings in the security field.

sslCertAlias (optional)

If secure connections to LDAP servers require client authentication, this identifies the alias of the certificate to use for client authentication when establishing a secure connection.

If you uses this setting because client authentication is required, make sure the keyManager settings in the security field are properly configured.

If this field is missing, then the certificate is chosen during the SSL handshake.

Example: client-cert

connectionPoolSize (optional)

The gateway creates connection pools to the primary and secondary LDAP servers. The connection pools maintain up to connectionPoolSize connections to the servers.

Default: 24

heartBeatIntervalSeconds (optional)

The gateway tests its connections every heartBeatIntervalSeconds to detect whether the connection is still alive. The first test is performed immediately when the gateway gets a connection. Subsequent tests follow every heartBeatIntervalSeconds.

Default: 30 (seconds)

heartBeatTimeoutMilliSeconds (optional)

When the gateway tests a connection, if the heartbeat does not come back after heartBeatTimeoutMilliSeconds the connection is marked as closed.

Default: 500 (milliseconds)

primaryLdapServers (required)

The gateway accesses this array of LDAP servers before failing over to the secondary LDAP servers. These might be LDAP servers in the same data center, for example:

{
    "primaryLdapServers": [
        {
            "hostname": "local1.example.com",
            "port": 1389
        },
        {
            "hostname": "local2.example.com",
            "port": 1389
        }
    ]
}

By default, the gateway connects to the server listening on port 1389 on the local host.

secondaryLdapServers (optional)

The gateway accesses this array of LDAP servers if primary LDAP servers cannot be contacted. These might be LDAP servers in the same remote data center, for example:

{
    "secondaryLdapServers": [
        {
            "hostname": "remote1.example.com",
            "port": 1389
        },
        {
            "hostname": "remote2.example.com",
            "port": 1389
        }
    ]
}

No secondary LDAP servers are configured by default.

root

Configures the authenticated connection factory:

inheritFrom (optional)

Identifies the unauthenticated connection factory to inherit the settings from. If this connection factory does not inherit from another configuration object, then you must specify the configuration here.

Default: bind

authentication (required)

The gateway authenticates by simple bind using the credentials specified:

{
    "authentication": {
        "bindDn": "cn=Directory Manager",
        "password": "password"
    }
}

If the OAuth 2.0 authorization policy is configured for the gateway, then the directory service must be configured to allow the user configured here to perform proxied authorization.

authorization

Configures how authorization is performed for REST operations. This entire configuration object applies only to the REST to LDAP gateway.

The default configuration handles authorization by mapping HTTP Basic authentication credentials to LDAP bind credentials. User entries are inetOrgPerson entries expected to have uid=username, and expected to be found under ou=people,dc=example,dc=com.

The default configuration also allows alternative, HTTP header-based authentication in the style of OpenIDM software.

To protect passwords, configure HTTPS for the container where the REST to LDAP gateway runs.

This object has the following configuration fields:

policies

Which authorization policies are allowed, where the supported policies include:

anonymous
basic (HTTP Basic)
oauth2

When more than one policy is specified, policies are applied in the following order:

If the client request has an Authorization header, and policies include oauth2, the server attempts to apply the OAuth 2.0 policy.
If the client request has an Authorization header, or has the custom credentials headers specified in the configuration, and policies includes basic, the server attempts to apply the Basic Auth policy.
Otherwise, if policies includes anonymous, and none of the previous policies apply, the server attempts to apply the policy for anonymous requests.

Default: [ "basic" ]

anonymous

Configuration for authorization when the HTTP connection to the gateway is not authenticated.

Operations are performed using connections from the specified factory:

ldapConnectionFactory

Factor providing LDAP connections to use for anonymous HTTP requests.

In effect, you add "anonymous" to the array of policies allowed without otherwise changing the default configuration, anonymous HTTP requests result in LDAP requests performed by Directory Manager. Take care to adjust this setting appropriately when allowing anonymous requests.

Default: root

basic

Configuration for authorization using HTTP Basic credentials.

The HTTP Basic credentials are mapped to LDAP credentials. The LDAP credentials are then used to bind to the directory service.

This object has the following configuration fields:

supportAltAuthentication

Whether to allow alternative, HTTP header-based authentication. If this is set to true, then the headers containing credentials are specified as the values for altAuthenticationUsernameHeader and altAuthenticationPasswordHeader, and the bind DN is resolved using a template.

Default: true

altAuthenticationUsernameHeader

The HTTP header containing the username for authentication when alternative, HTTP header-based authentication is allowed.

Default: X-OpenIDM-Username

altAuthenticationPasswordHeader

The HTTP header containing the password for authentication when alternative, HTTP header-based authentication is allowed.

Default: X-OpenIDM-Password

bind

How HTTP Basic credentials are mapped to LDAP credentials used to bind to the directory service.

The following values are supported:

search (default) means the gateway performs a search based on the HTTP Basic user name to obtain the bind DN.
sasl-plain means the gateway transforms the HTTP Basic user name to an authorization ID (authzid) using a template.
simple means the HTTP Basic user name is mapped to a component of the LDAP bind DN.

simple

How to reuse HTTP Basic credentials for an LDAP simple bind.

This object has the following configuration fields:

ldapConnectionFactory

The factory providing LDAP connections to the directory service.

Default: bind

bindDnTemplate

The template to produce the bind DN from the HTTP Basic user name.

A single occurrence of the string {username} is replaced in the template with the HTTP Basic user name.

Default: uid={username},ou=People,dc=example,dc=com (The HTTP Basic user name is the UID of the LDAP entry.)

sasl-plain

How to reuse HTTP Basic credentials for an LDAP SASL plain bind.

This object has the following configuration fields:

ldapConnectionFactory

The factory providing LDAP connections to the directory service.

Default: bind

authzIdTemplate

The template to produce the authorization ID from the HTTP Basic user name.

A single occurrence of the string {username} is replaced in the template with the HTTP Basic user name.

If the user name is also the authorization ID, use u:{username}.

If the user name is the LDAP bind DN, use dn:{username}.

search

How to reuse HTTP Basic credentials to find the bind DN for an LDAP simple bind.

This object has the following configuration fields:

searchLdapConnectionFactory

The factory providing LDAP connections to the directory service for the LDAP search operation.

Default: root

bindLdapConnectionFactory

The factory providing LDAP connections to the directory service for the LDAP bind operation that uses the bind DN returned by the search.

Default: bind

baseDn

The base DN for the LDAP search.

Example: ou=People,dc=example,dc=com.

scope

The scope for the LDAP search.

Use sub for a subtree search, one for a one-level search.

filterTemplate

The template for the filter of the LDAP search.

A single occurrence of the string {username} is replaced in the template with the HTTP Basic user name.

If the user name is also the UID, use (&(uid={username})(objectClass=inetOrgPerson)).

oauth2

Configuration for authorization based on OAuth 2.0, where the gateway plays the role of resource server.

This object has the following configuration fields:

realm

Realm associated with access tokens presented to the gateway.

requiredScopes

Array of OAuth 2.0 scopes that are required to allow access.

This array must not be empty.

Example: [ "read", "write", "uid" ]

resolver

How to resolve OAuth 2.0 access tokens presented to the gateway.

Supported values include the following:

cts to resolve tokens in a directory service acting as a Core Token Service (CTS) store for AM
openam to send requests for token resolution to an AM server
rfc7662 to send requests for token resolution to an RFC 7622-compliant server

Each access token resolution mechanism has its own configuration.

accessTokenCache

How to cache OAuth 2.0 token information to avoid repeating calls for access token resolution.

This object has the following configuration fields:

enabled

Whether to cache access token information obtained from the resolver.

Default: false

cacheExpiration

How long to cache information for a particular token if caching is enabled.

Default: 5 minutes

openam

Configuration for resolving OAuth 2.0 tokens by a request to AM.

This object has the following configuration fields:

endpointUrl

AM URL for requests for token information, which depends on AM's OAuth 2.0 authorization server configuration.

Example: https://openam.example.com:8443/openam/oauth2/tokeninfo

sslCertAlias (optional)

If secure connections to the authorization server require client authentication, this identifies the alias of the certificate to use for client authentication when establishing a secure connection.

If you uses this setting because client authentication is required, make sure the keyManager settings in the security field are properly configured.

If this field is missing, then the certificate is chosen during the SSL handshake.

Example: client-cert

authzIdTemplate

The template to produce the authorization ID from OAuth 2.0 token information.

A JSON pointer value in braces is replaced in the template with a field value from the JSON returned during token resolution.

This template must start with u: or dn:.

For example, if token resolution returns a JSON document where the value of the uid field is the UID of the user entry in the directory, you might use u:{uid} or dn:{uid},ou=People,dc=example,dc=com.

rfc7662

Configuration for resolving OAuth 2.0 tokens by a request to an RFC 7662-compliant authorization server.

RFC 7662, OAuth 2.0 Token Introspection, defines a standard method for resolving access tokens.

This object has the following configuration fields:

endpointUrl

Authorization server URL for requests for token information with HTTP Basic authentication for OAuth 2.0 clients.

Example: https://as.example.com/introspect

sslCertAlias (optional)

If secure connections to the authorization server require client authentication, this identifies the alias of the certificate to use for client authentication when establishing a secure connection.

If you uses this setting because client authentication is required, make sure the keyManager settings in the security field are properly configured.

If this field is missing, then the certificate is chosen during the SSL handshake.

Example: client-cert

clientId

OAuth 2.0 client identifier defined during registration with the authorization server.

clientSecret

OAuth 2.0 client secret defined during registration with the authorization server.

authzIdTemplate

The template to produce the authorization ID from OAuth 2.0 token information.

A JSON pointer value in braces is replaced in the template with a field value from the JSON returned during token resolution.

This template must start with u: or dn:.

For example, if token resolution returns a JSON document where the value of the username field is the UID of the user entry in the directory, you might use u:{username} or dn:{username},ou=People,dc=example,dc=com.

cts

Configuration for resolving OAuth 2.0 tokens when the directory service acts as AM's CTS store.

AM's CTS store is constrained to a specific layout. The authzIdTemplate must therefore use {userName/0} for the user identifier.

This mechanism makes it possible to resolve access tokens by making a request to the CTS directory service, without making a request to AM. This mechanism does not, however, ensure that the token requested will have already been replicated to the directory server where the request is routed.

This object has the following configuration fields:

ldapConnectionFactory

The factory providing LDAP connections used to obtain token information from the CTS directory service.

Default: root

baseDn

The base DN in the CTS directory service where tokens are found.

If the base DN configured for CTS in AM is dc=cts,dc=example,dc=com, then use ou=famrecords,ou=openam-session,ou=tokens,dc=cts,dc=example,dc=com.

authzIdTemplate

The template to produce the authorization ID from OAuth 2.0 token information.

A JSON pointer value in braces is replaced in the template with a field value from the JSON returned during token resolution.

This template must start with u: or dn:.

In AM CTS, the user name field is an array. For example, if the user name is the UID of the user entry, the use u:{userName/0} or dn:{userName/0},ou=People,dc=example,dc=com.

1.2. Gateway REST2LDAP Configuration File

The rest2ldap/rest2ldap.json for the REST to LDAP gateway can hold the configuration objects described in this section.

The order of the settings in the JSON file is not meaningful. Here, the order shown is that of the default configuration file:

localSortMaxEntries

The maximum number of entries supported by the local sort mechanism. The local sort mechanism is used when sort keys reference JSON attributes. See the description for useServerSideSortForJson below.

Default: 1000

When a request to the gateway includes a _sortKey parameter, the gateway does the following:

If the _sortKey parameter targets a normal LDAP attribute, the gateway includes a server-side sort request for the LDAP server to sort the results.
If the _sortKey parameter targets a JSON syntax LDAP attribute, the gateway's action depending on the setting for useServerSideSortForJson, described below.
If the _sortKey parameter targets an attribute that is in a referenced entry, the gateway sorts the results locally.

useMvcc

Whether the gateway supports multi-version concurrency control (MVCC). If true, also specify an mvccAttribute to use for MVCC.

Default: true

mvccAttribute

The LDAP attribute whose value is used for MVCC. Before performing a write operation, the client application can check, for example, whether it is modifying the correct version of a resource by matching the value of the header If-Match: value.

Default: etag

readOnUpdatePolicy

The policy used to read an entry before it is deleted, or to read an entry after it is added or modified. One of the following:

controls: (default) use RFC 4527 read-entry controls to reflect the state of the resource at the time the update was performed.
The directory service must support RFC 4527.
disabled: do not read the entry or return the resource on update.
search: perform an LDAP search to retrieve the entry before deletion or after it is added or modified.
The JSON resource returned might differ from the LDAP entry that was updated.

returnNullForMissingProperties

Whether missing (unmapped) JSON properties should be included in JSON resources.

By default, a REST to LDAP mapping omits JSON fields for LDAP attributes that have no values. For example, the following entry is missing a value for the optional description:

dn: uid=bjensen,ou=people,dc=example,dc=com
objectClass: person
uid: bjensen
cn: Babs Jensen
sn: Jensen

By default, a REST to LDAP mapping which maps the uid, cn, sn, and description attributes could return the following JSON:

{
  "id": "bjensen",
  "fullName": "Babs Jensen",
  "familyName": "Jensen"
}

With this setting, the mapping returns a JSON resource with a "description" field:

{
  "id": "bjensen",
  "fullName": "Babs Jensen",
  "familyName": "Jensen",
  "description": null
}

Default: false

useSubtreeDelete

Whether to use the LDAP Subtree Delete request control (OID: 1.2.840.113556.1.4.805) for LDAP delete operations resulting from delete operations on resources. Clients applications that request deletes for resources with children must have access to use the control.

If this setting is true, REST to LDAP attempts to use the control, but falls back to searching for and deleting children if the server rejects the request, because the control is not supported, for example.

Default: true

Set this to false if the LDAP server does not support the control.

usePermissiveModify

Whether to use the LDAP Permissive Modify request control (OID: 1.2.840.113556.1.4.1413) for LDAP modify operations resulting from patch and update operations on resources.

Default: true

Set this to false when using the gateway if the LDAP server does not support the control.

useServerSideSortForJson

Whether to use the LDAP Server-Side Sort request control (OID: 1.2.840.113556.1.4.473) to request that the server sort the results before returning them.

Default: true

When you set this to false, the gateway sorts search results locally. In this case, you can set localSortMaxEntries to limit the maximum number of results that the gateway sorts locally. The localSortMaxEntries setting then effectively limits the maximum _pageSize that the gateway accepts.

1.3. Mapping Configuration File

The rest2ldap/endpoints/base-path/root-resource.json files define how JSON resources map to LDAP entries.

For each base path exposing a REST API, a base-path directory holds one or more root-resource.json files. In the DS server configuration, the Rest2ldap endpoint base-path must match the base-path directory name.

Each root-resource.json file defines mappings for a specific version of the API. The root-resource in the file name must match the name of the root resource defined in the file.

If there is more than one version of the API, then client applications must select the version by setting a version header:

Accept-API-Version: resource=version

If more than one version of the API is available, and the client application does not select the version by setting a version header, then the latest version is returned.

Here, version is the value of the version field in the mapping configuration file.

The file rest2ldap/endpoints/api/example-v1.json is delivered as an example mapping. This file has the following basic structure:

{
  "version": "1.0",         // Version for this API.
  "resourceTypes": {        // Resources for this API.
    "example-v1": {         // Root resource type. Name matches file basename.
      "subResources": {     // The base resource, at /api, is not defined.
        "users": {},        // The subresources at /api/users/ and
        "groups": {}        // /api/groups are defined, however.
      }
    },

    // In addition to the root resource type,
    // the example defines a number of other resource type schemas.
    // These are used to describe the resources exposed under the root resource.
    // In the example file, you can see how these are used for inheritance.
    "frapi:opendj:rest2ldap:object:1.0": {},    // Parent type of all objects.
    "frapi:opendj:rest2ldap:user:1.0": {},      // Basic user type, parent of
    "frapi:opendj:rest2ldap:posixUser:1.0": {}, // user with uid, gid, home dir.
    "frapi:opendj:rest2ldap:group:1.0": {}      // Basic group type.
  }
}

The following list describes the individual fields in more detail.

The order of the settings in the JSON file is not meaningful. Here, the order shown is that of the default example configuration file:

version (optional)

The version string for the root resource of this API.

Valid values are *, integer, and integer.integer, where integer is a positive decimal integer.

If the version is set, and the client application sets the request header Accept-API-Version: resource=version, The mapping with the matching version value is selected.

If more than one version of the API is available, and the client application does not select the version by setting a version header, then the latest version is returned.

Default: * (no version specified)

resourceTypes (required)

The map of resource type names to resource type definitions for this API.

One of the resource type name must match the basename of the mapping file. This resource is referred to as the root resource for this version of the API.

The value of a resource type is an object whose properties are described in "Resource Type Properties".

Resource Type Properties

Property	Description
`resourceTypeProperty` (string, required for inheritance)	Name of the resource type property that specifies the type of this resource. REST to LDAP uses this to determine the resource subtype when creating a resource. This points the mapper to the type of the resource. The specified property must be of type `resourceType`.
`properties` (map, optional)	Map of property names to property definitions. Unlike LDAP entries, JSON resources are not necessarily flat. You can define nested properties of type `object` that have their own properties. For details on properties configuration, see "Properties of Resource Type Properties Objects".
`subResources` (map, optional)	Map of subresource names to subresource definitions. The subresource names are URL templates. A URL template sets the relative URL template beneath which the subresources are located. If empty, the subresources are located directly beneath the parent resource. URL templates can set variables in braces `{}`. Any URL template variables will be substituted into the DN template. For example, suppose LDAP entries for devices are located under the following base DNs: `ou=others,ou=devices,dc=example,dc=com` `ou=pcs,ou=devices,dc=example,dc=com` `ou=phones,ou=devices,dc=example,dc=com` `ou=tablets,ou=devices,dc=example,dc=com` The subresource name `/{type}` would be substituted in actual paths with `/others`, `/pcs`, `/phones`, and `/tablets`. The DN template for the subresource would specify `ou={type},ou=devices,dc=example,dc=com` in order to locate the entries in the correct LDAP organizational unit. In the example, REST to LDAP substitutes `{type}` in the DN template with the type defined in the request URL path. For details on subresource configuration, see "Sub-Resource Properties".
`isAbstract` (boolean, optional)	Whether this is an abstract resource type used only for inheritance. Default: `false`
`superType` (string, optional)	Name of the resource type that this resource type extends. Resource types that extend another type inherit properties of the extended type, and inherit subresource definitions. Default: none. This resource type does not extend another type.
`objectClasses` (array, optional)	Names of the LDAP object classes that this type corresponds to. When an object of this type is created, these object class names are added to the list of object classes on the LDAP entry. The LDAP object classes are not shown in the JSON resource. Default: none.
`supportedActions` (array, optional)	Names of the ForgeRock® Common REST actions that this resource type supports. The names must match actions allowed on the resource in the underlying implementation. Default: none.
`includeAllUserAttributesByDefault` (boolean, optional)	Whether to include all LDAP user attributes as properties of the JSON resource. If `true`, the property names in the JSON resource match the attribute names in the LDAP entries. Default: `false`
`excludedDefaultUserAttributes` (array, optional)	Names of the LDAP user attributes to exclude from the JSON resource when `includeAllUserAttributesByDefault` is `true`. Default: none.

Properties of Resource Type Properties Objects

Property	Description
`type` (string, required)	Determines the type of the mapping property, and therefore which other properties the object has. The type must be one of the following: `constant` The property maps the JSON resource property to a fixed value specified by the `value` property. `json` The property value maps the JSON resource property to a `Json` syntax LDAP attribute. When the type is `json`, the mapping must specify an `ldapAttribute` property that specifies the `Json` syntax LDAP attribute. The mapping may have the following optional properties: `defaultJsonValue` `extensibleJsonOrderingMatchingRule` `isMultiValued` `isRequired` `jsonQueryEqualityMatchingRule` `schema` `writability` `object` The property value is a JSON object with its own type and mapping specified by the object's `properties`. `reference` The property maps a JSON field to an LDAP entry found by reference. This is useful for LDAP attributes that reference other entries, such as `manager`, and (group) `member`. When the type is `reference`, the mapping must have the following required properties. `baseDn` `ldapAttribute` `mapper` `primaryKey` The mapping may have the following optional properties. `isMultiValued` `isRequired` `searchFilter` `writability` `resourceType` The property value is the name of a resource type defined in this mapping file. The name of the property with this type should match the `resourceTypeProperty` name. For example, if `"resourceTypeProperty": "_schema"` then the following should be specified or inherited: `"_schema": { "type": "resourceType" }`. `simple` The property maps a JSON property to an LDAP attribute. Use simple mappings where the correspondence between JSON properties and LDAP attributes is one-to-one. When the type is `simple`, the mapping must specify an `ldapAttribute` property. The mapping may have the following optional properties. `defaultJsonValue` `isBinary` `isMultiValued` `isRequired` `writability`
`baseDn`	Indicates the base LDAP DN under which to find entries referenced by the JSON resource. Base DN values can be literal values, such as `dc=example,dc=com`, and can also use the following notation: `{url-template}` The `{url-template}` used in the description of the URL to the resource is replaced with the literal value used in the request. For example, suppose the path defined for the resources is `/{tenant}/users` and the base DN is `ou=people,dc={tenant},dc=com`. For a request to `/example/users`, the base DN is `ou=people,dc=example,dc=com`. `..` The `..` refers to the relative parent RDN. This is like `..` in a file system path, where `..` refers to the parent directory. Keep in mind that file system paths are big endian, whereas DNs are little endian. You write `../../file-in-grandparent-directory`, but `cn=Child of Grandparent Entry,..,..`. The following excerpt from the default example configuration shows how this could be used to reference a manager's entry (the mapper configuration is not shown): { "manager": { "type": "reference", "ldapAttribute": "manager", "baseDn": "..", "primaryKey": "uid", "mapper": {} } } In this case, if the current LDAP entry for the resource `uid=bjensen,ou=people,dc=example,dc=com`, then the base DN is `ou=people,dc=example,dc=com`. Another excerpt from the default example configuration shows a reference to group member entries (again, the mapper configuration is not shown): { "members": { "type": "reference", "ldapAttribute": "uniqueMember", "baseDn": "ou=people,..,..", "primaryKey": "uid", "isMultiValued": true, "mapper": {} } } In this case, if the current LDAP entry for the resource `cn=Directory Administrators,ou=groups,dc=example,dc=com`, then the base DN is `ou=people,dc=example,dc=com`. Notice a limitation in this reference to group member entries: all group members must be people; the configuration does not handle nested groups and other types of members.
`defaultJsonValue`	Sets the JSON value if no corresponding LDAP attribute is present. No default is set if this is omitted.
`extensibleJsonOrderingMatchingRule`	Sets the JSON ordering matching rule to use when requesting an extensible server-side sort. The default rule will ignore case and whitespace when sorting values of JSON fields. For a description of the extended server-side sort syntax, see "Search: Server-Side Sort" in the Developer's Guide.
`isBinary`	Whether the underlying LDAP attribute holds a binary value, such as a JPEG photo or a digital certificate. If `true`, the JSON property takes the base64-encoded value. Binary values can also be handled directly as described in "Working With Alternative Content Types" in the Developer's Guide. Default: `false`.
`isMultiValued`	Whether the JSON resource property can take an array value. Most LDAP attributes can take multiple values. A literal-minded mapping from LDAP to JSON would therefore be full of array properties, many with only one value. To minimize inconvenience, REST to LDAP generally returns single value scalars, even when the underlying LDAP attribute is multi-valued. If this property is omitted or set to `false`, then the JSON resource contains the first value returned for multi-valued LDAP attributes with more than value. If this property is `true`, then if the LDAP attribute only has one value, it is returned as a scalar. If the LDAP attribute has more than one value, the values are returned in an array. Default: `false`
`isRequired`	`true` means the LDAP attribute is mandatory and must be provided to create the resource; `false` means it is optional. Default: `false`.
`jsonQueryEqualityMatchingRule`	When a query filter in the HTTP request uses a JSON path that points to a field in a JSON attribute value, it uses the matching rule specified by this property to compare the query filter with attribute values. You can set this to the following matching rule names: `caseExactJsonQueryMatch` means respect case when finding matches. `caseIgnoreJsonQueryMatch` means ignore case when finding matches. Default: `caseIgnoreJsonQueryMatch`.
`ldapAttribute`	Specifies the LDAP attribute in the entry underlying the JSON resource whose value points to the referenced entry. For example, a `manager` attribute value is the DN of the manager's entry. Default: use the name of the JSON property. For example, the JSON property `description` maps to the LDAP attribute `description` by default.
`mapper`	Describes how the referenced entry content maps to the content of this JSON property. A mapper object is a properties object of its own.
`primaryKey`	Indicates which LDAP attribute in the mapper holds the primary key to the referenced entry.
`schema`	Specifies a JSON Schema that applies values of type `json`. Default: No schema is specified; values may be arbitrary JSON.
`searchFilter`	Specifies the LDAP filter to use to search for the referenced entry. Default: `"(objectClass=*)"`
`value`	Use with `"type": "constant"` to specify the constant value.
`writability`	Indicates whether the mapping supports updates. The `writability` property takes one of the following values: `createOnly`: This attribute can be set only when the entry is created. Attempts to update this attribute thereafter result in errors. `createOnlyDiscardWrites`: This attribute can be set only when the entry is created. Attempts to update this attribute thereafter do not result in errors. Instead the update value is discarded. `readOnly`: This attribute cannot be written. Attempts to write this attribute result in errors. `readOnlyDiscardWrites`: This attribute cannot be written. Attempts to write this attribute do not result in errors. Instead the value to write is discarded. `readWrite`: (default) This attribute can be set at creation and updated thereafter.

Sub-Resource Properties

Property	Description
`type` (string, required)	The type of this subresource, either `collection` or `singleton`. A collection subresource is a container for other resources, which can be created, read, updated, deleted, patched, and queried. A collection definition has the following required properties: `namingStrategy` `resource` A collection definition has the following optional properties: `dnTemplate` `glueObjectClasses` `isReadOnly` A singleton subresource is a resource with no children. A singleton definition has the following required properties: `resource` A singleton definition has the following optional properties: `dnTemplate` `isReadOnly`
`dnTemplate` (string, optional)	Sets the relative DN template beneath which the subresource LDAP entries are located. If this is an empty string, the LDAP entries are located directly beneath the parent LDAP entry. DN templates can use variables in braces `{}`. DN template variables are substituted using values extracted from the URL template. Default: empty string
`glueObjectClasses` (array, required if the DN template contains one or more RDNs)	Specifies one or more LDAP object class names associated with any intermediate "glue" entries forming the DN template. Default: no object classes are specified
`isReadOnly` (boolean, optional)	Whether this resource is read-only. Default: `false`
`namingStrategy` (object, required)	Specifies the approach used to map LDAP entry names to JSON resources. LDAP entries mapped to JSON resources must be immediate subordinates of the mapping's `baseDn`. The following naming strategies are supported: RDN and resource ID are both derived from a single user attribute in the LDAP entry, as in the following example, where the `uid` attribute is the RDN and its value is the JSON resource ID: { "namingStrategy": { "type": "clientDnNaming", "dnAttribute": "uid" } } RDN and resource ID are derived from separate user attributes in the LDAP entry, as in the following example, where the RDN attribute is `uid`, but the JSON resource ID is the value of the `mail` attribute: { "namingStrategy": { "type": "clientNaming", "dnAttribute": "uid", "idAttribute": "mail" } } RDN is derived from a user attribute and the resource ID from an operational attribute in the LDAP entry, as in the following example, where the RDN attribute is `uid`, but the JSON resource ID is the value of the `entryUUID` operational attribute: { "namingStrategy": { "type": "serverNaming", "dnAttribute": "uid", "idAttribute": "entryUUID" } }
`resource` (string, required)	Specifies the resource type name of the subresource. A collection can contain objects with different subresource types as long as all types inherit from the same super type. In that case, set `resource` to the super type name.

Chapter 2. Request Handling

This chapter describes how DS services respond to requests.

2.1. Requests to Servers

DS servers listen for client requests using connection handlers. A connection handler interacts with client applications, accepting connections, reading requests, and sending responses. Most connection handlers expose configurable listen ports with security settings. The security settings point to other configuration objects, so two connection handlers can share the same certificate and private key, for example.

DS servers use different ports for different protocols. For example, a directory server might listen on port 389 for LDAP requests, port 443 for HTTPS requests, and port 4444 for administration requests from server configuration tools. Because DS servers use a different connection handler for each port, DS servers have several connection handlers enabled.

The setup command lets you initially configure connection handlers for LDAP(S), HTTP(S), and administrative traffic. The dsconfig command offers full access to all connection handler configurations.

When a client application opens a secure connection to a server, the JVM has responsibility for transport layer security negotiations. You can configure how connection handlers access keys required during the negotiations. You can also configure which clients on the network are allowed to use the connection handler. For details, see "Connection Handler" in the Configuration Reference.

Connection handlers receive incoming requests, and pass them along for processing by the core server subsystem.

For example, an LDAP connection handler enqueues requests to the core server, which in turn requests data from the appropriate backend as necessary. For more information about backends, see "About Database Backends" in the Administration Guide. The core server returns the LDAP response.

LDAP Requests

LDAP request processing occurs in the core directory server.

An HTTP connection handler translates each request to LDAP. Internally, the core server subsystem processes the resulting LDAP requests.

HTTP Requests

An HTTP connection handler translates to LDAP based on its configuration.

DS servers support other types of connection handlers. For example, JMX and SNMP connection handlers support monitoring applications. A special LDIF connection handler consumes LDIF files. For details, see "Configuring Connection Handlers" in the Administration Guide.

When deploying a server, decide which listen ports to expose over which networks. Determine how you want to secure the connections, as described in "Securing Network Connections" in the Security Guide.

2.2. Requests to Gateways

The gateway applications translate each HTTP request from the user-agent to the application server into one or more LDAP requests to remote directory services.

A DSML gateway translates each HTTP request into one or more LDAP requests. The translation depends on the DSML protocol. You configure only how HTTP user IDs map to LDAP identities for authentication.

Requests Through a DSML Gateway

DSML translates HTTP to LDAP based on the DSML protocol.

A REST to LDAP gateway translates an HTTP request into one or more LDAP requests. The translation depends on the specific REST to LDAP gateway configuration. An identity mapper translates the user identity into an LDAP identity for the bind. Then the REST to LDAP mapping defines how the REST JSON resource corresponds to LDAP entries. The gateway handles the mapping configuration in the same way as an HTTP connection handler.

Requests Through a REST to LDAP Gateway

REST to LDAP translates HTTP to LDAP based on its configuration.

Chapter 3. LDAP Result Codes

An operation result code as defined in RFC 4511 section 4.1.9 is used to indicate the final status of an operation. If a server detects multiple errors for an operation, only one result code is returned. The server should return the result code that best indicates the nature of the error encountered. Servers may return substituted result codes to prevent unauthorized disclosures.

OpenDJ LDAP Result Codes

Result Code	Name	Description
-1	Undefined	The result code that should only be used if the actual result code has not yet been determined. Despite not being a standard result code, it is an implementation of the null object design pattern for this type.
0	Success	The result code that indicates that the operation completed successfully.
1	Operations Error	The result code that indicates that the operation is not properly sequenced with relation to other operations (of same or different type). For example, this code is returned if the client attempts to StartTLS [RFC4346] while there are other uncompleted operations or if a TLS layer was already installed.
2	Protocol Error	The result code that indicates that the client sent a malformed or illegal request to the server.
3	Time Limit Exceeded	The result code that indicates that a time limit was exceeded while attempting to process the request.
4	Size Limit Exceeded	The result code that indicates that a size limit was exceeded while attempting to process the request.
5	Compare False	The result code that indicates that the attribute value assertion included in a compare request did not match the targeted entry.
6	Compare True	The result code that indicates that the attribute value assertion included in a compare request did match the targeted entry.
7	Authentication Method Not Supported	The result code that indicates that the requested authentication attempt failed because it referenced an invalid SASL mechanism.
8	Strong Authentication Required	The result code that indicates that the requested operation could not be processed because it requires that the client has completed a strong form of authentication.
10	Referral	The result code that indicates that a referral was encountered. Strictly speaking this result code should not be exceptional since it is considered as a "success" response. However, referrals should occur rarely in practice and, when they do occur, should not be ignored since the application may believe that a request has succeeded when, in fact, nothing was done.
11	Administrative Limit Exceeded	The result code that indicates that processing on the requested operation could not continue because an administrative limit was exceeded.
12	Unavailable Critical Extension	The result code that indicates that the requested operation failed because it included a critical extension that is unsupported or inappropriate for that request.
13	Confidentiality Required	The result code that indicates that the requested operation could not be processed because it requires confidentiality for the communication between the client and the server.
14	SASL Bind in Progress	The result code that should be used for intermediate responses in multi-stage SASL bind operations.
16	No Such Attribute	The result code that indicates that the requested operation failed because it targeted an attribute or attribute value that did not exist in the specified entry.
17	Undefined Attribute Type	The result code that indicates that the requested operation failed because it referenced an attribute that is not defined in the server schema.
18	Inappropriate Matching	The result code that indicates that the requested operation failed because it attempted to perform an inappropriate type of matching against an attribute.
19	Constraint Violation	The result code that indicates that the requested operation failed because it would have violated some constraint defined in the server.
20	Attribute or Value Exists	The result code that indicates that the requested operation failed because it would have resulted in a conflict with an existing attribute or attribute value in the target entry.
21	Invalid Attribute Syntax	The result code that indicates that the requested operation failed because it violated the syntax for a specified attribute.
32	No Such Entry	The result code that indicates that the requested operation failed because it referenced an entry that does not exist.
33	Alias Problem	The result code that indicates that the requested operation failed because it attempted to perform an illegal operation on an alias.
34	Invalid DN Syntax	The result code that indicates that the requested operation failed because it would have resulted in an entry with an invalid or malformed DN.
36	Alias Dereferencing Problem	The result code that indicates that a problem was encountered while attempting to dereference an alias for a search operation.
48	Inappropriate Authentication	The result code that indicates that an authentication attempt failed because the requested type of authentication was not appropriate for the targeted entry.
49	Invalid Credentials	The result code that indicates that an authentication attempt failed because the user did not provide a valid set of credentials.
50	Insufficient Access Rights	The result code that indicates that the client does not have sufficient permission to perform the requested operation.
51	Busy	The result code that indicates that the server is too busy to process the requested operation. This is a transient error which means the operation can safely be retried.
52	Unavailable	The result code that indicates that either the entire server or one or more required resources were not available for use in processing the request. This is a transient error which means the operation can safely be retried.
53	Unwilling to Perform	The result code that indicates that the server is unwilling to perform the requested operation.
54	Loop Detected	The result code that indicates that a referral or chaining loop was detected while processing the request.
60	Sort Control Missing	The result code that indicates that a search request included a VLV request control without a server-side sort control.
61	Offset Range Error	The result code that indicates that a search request included a VLV request control with an invalid offset.
64	Naming Violation	The result code that indicates that the requested operation failed because it would have violated the server's naming configuration.
65	Object Class Violation	The result code that indicates that the requested operation failed because it would have resulted in an entry that violated the server schema.
66	Not Allowed on Non-Leaf	The result code that indicates that the requested operation is not allowed for non-leaf entries.
67	Not Allowed on RDN	The result code that indicates that the requested operation is not allowed on an RDN attribute.
68	Entry Already Exists	The result code that indicates that the requested operation failed because it would have resulted in an entry that conflicts with an entry that already exists.
69	Object Class Modifications Prohibited	The result code that indicates that the operation could not be processed because it would have modified the objectclasses associated with an entry in an illegal manner.
71	Affects Multiple DSAs	The result code that indicates that the operation could not be processed because it would impact multiple DSAs or other repositories.
76	Virtual List View Error	The result code that indicates that the operation could not be processed because there was an error while processing the virtual list view control.
80	Other	The result code that should be used if no other result code is appropriate.
81	Server Connection Closed	The client-side result code that indicates that the server is down. This is for client-side use only and should never be transferred over protocol. This is a transient error which means the operation can be retried.
82	Local Error	The client-side result code that indicates that a local error occurred that had nothing to do with interaction with the server. This is for client-side use only and should never be transferred over protocol.
83	Encoding Error	The client-side result code that indicates that an error occurred while encoding a request to send to the server. This is for client-side use only and should never be transferred over protocol.
84	Decoding Error	The client-side result code that indicates that an error occurred while decoding a response from the server. This is for client-side use only and should never be transferred over protocol.
85	Client-Side Timeout	The client-side result code that indicates that the client did not receive an expected response in a timely manner. This is for client-side use only and should never be transferred over protocol. This is a transient error which means the operation can be retried.
86	Unknown Authentication Mechanism	The client-side result code that indicates that the user requested an unknown or unsupported authentication mechanism. This is for client-side use only and should never be transferred over protocol.
87	Filter Error	The client-side result code that indicates that the filter provided by the user was malformed and could not be parsed. This is for client-side use only and should never be transferred over protocol.
88	Cancelled by User	The client-side result code that indicates that the user cancelled an operation. This is for client-side use only and should never be transferred over protocol.
89	Parameter Error	The client-side result code that indicates that there was a problem with one or more of the parameters provided by the user. This is for client-side use only and should never be transferred over protocol.
90	Out of Memory	The client-side result code that indicates that the client application was not able to allocate enough memory for the requested operation. This is for client-side use only and should never be transferred over protocol.
91	Connect Error	The client-side result code that indicates that the client was not able to establish a connection to the server. This is for client-side use only and should never be transferred over protocol. This is a transient error which means the operation can be retried.
92	Operation Not Supported	The client-side result code that indicates that the user requested an operation that is not supported. This is for client-side use only and should never be transferred over protocol.
93	Control Not Found	The client-side result code that indicates that the client expected a control to be present in the response from the server but it was not included. This is for client-side use only and should never be transferred over protocol.
94	No Results Returned	The client-side result code that indicates that the requested single entry search operation or read operation failed because the Directory Server did not return any matching entries. This is for client-side use only and should never be transferred over protocol.
95	Unexpected Results Returned	The client-side result code that the requested single entry search operation or read operation failed because the Directory Server returned multiple matching entries (or search references) when only a single matching entry was expected. This is for client-side use only and should never be transferred over protocol.
96	Referral Loop Detected	The client-side result code that indicates that the client detected a referral loop caused by servers referencing each other in a circular manner. This is for client-side use only and should never be transferred over protocol.
97	Referral Hop Limit Exceeded	The client-side result code that indicates that the client reached the maximum number of hops allowed when attempting to follow a referral (i.e., following one referral resulted in another referral which resulted in another referral and so on). This is for client-side use only and should never be transferred over protocol.
118	Canceled	The result code that indicates that a cancel request was successful, or that the specified operation was canceled.
119	No Such Operation	The result code that indicates that a cancel request was unsuccessful because the targeted operation did not exist or had already completed.
120	Too Late	The result code that indicates that a cancel request was unsuccessful because processing on the targeted operation had already reached a point at which it could not be canceled.
121	Cannot Cancel	The result code that indicates that a cancel request was unsuccessful because the targeted operation was one that could not be canceled.
122	Assertion Failed	The result code that indicates that the filter contained in an assertion control failed to match the target entry.
123	Authorization Denied	The result code that should be used if the server will not allow the client to use the requested authorization.
16,654	No Operation	The result code that should be used if the server did not actually complete processing on the associated operation because the request included the LDAP No-Op control.

Chapter 4. File Layout

DS software installs and creates the following files and directories. The following table is not meant to be exhaustive.

File Locations

File or Directory	Description
`bak`	Base directory for backup archives
`bat`	Windows command-line tools
`bin`	UNIX/Linux command-line tools
`changelogDb`	Backend data for the external change log when using replication
`classes`	Directory added to the server classpath, permitting individual classes to be patched
`config`	(Optionally) immutable server configuration files
`config/audit-handlers`	Templates for configuring external Common Audit event handlers
`config/config.ldif`	LDIF representation of current DS server configuration
`config/MakeLDIF`	Templates for use with the makeldif LDIF generation tool
`db`	Backend database files
`db/adminRoot`	Mutable administrative backend files
`db/ads-truststore`	Mutable truststore for keys and certificates used by replication
`db/monitorUser`	Default monitor user backend files If a monitor user is created at setup time, this directory holds the files.
`db/rootUser`	Default root user backend files
`db/schema`	LDAP schema files
`db/tasks`	Task scheduler backend files
`db/userRoot`	Files for default persistent, indexed backend that holds user data
`example-plugin.zip`	Sample DS plugin code Install custom plugins in the `lib/extensions` directory.
`example-pwdscheme.zip`	Sample DS password storage scheme extension
`extlib`	Directory for additional .jar files used by your custom plugins If the instance path is not the same as the binaries, copy additional files into the `instance-path/extlib/` directory.
`import-tmp`	Working directory used when importing LDIF data
`ldif`	Directory for saving LDIF export files
`legal-notices`	License information
`lib`	Scripts and libraries shipped with DS servers
`lib/extensions`	Directory for custom plugins
`locks`	Lock files that prevent more than one process from using the same backend
`logs`	Access, errors, audit, and replication logs
`logs/server.pid`	Contains the process ID for a running server
`opendj_logo.png`	DS splash logo
`README`	About DS servers
`setup`	UNIX/Linux setup tool
`setup.bat`	Windows setup tool
`snmp`	SNMP support files
`template`	Templates for setting up a server instance
`template/setup-profiles`	Profile scripts to configure directory servers for specific use cases
`upgrade`	UNIX/Linux upgrade tool
`upgrade.bat`	Windows upgrade tool
`var`	Files the DS server writes to during operation Do not modify or move files in the `var` directory.
`var/archived-configs`	Snapshots of the main server configuration file, `config/config.ldif` The server writes a compressed snapshot file when the configuration is changed.
`var/config.ldif.startok`	The most recent version of the main server configuration file that the server successfully started with

Chapter 5. Ports Used

DS server software uses the TCP/IP ports described in "Server Ports".

Server Ports

Protocols	Conventional Ports	Active by Default?	Description
LDAP	389	No	Port for cleartext LDAP requests; also used to request StartTLS for a secure connection. The reserved LDAP port number is 389. Interactive setup initially suggests this port number. If the initially suggested port is not free or cannot be used due to lack of privileges, interactive setup adds 1000 to the port number and tries again, repeatedly adding 1000 until a free port is found. If LDAP is used, leave this port open to client applications.
LDAPS	636	No	Port for secure LDAPS requests. The standard LDAPS port number is 636. Interactive setup initially suggests this port number. If the initially suggested port is not free or cannot be used due to lack of privileges, interactive setup adds 1000 to the port number and tries again, repeatedly adding 1000 until a free port is found. If LDAPS is used, leave this port open to client applications.
HTTP, HTTPS	80, 443	No	Port for HTTP client requests, such as RESTful API calls. The standard HTTP port number is 80. The standard HTTPS port number is 443. Interactive setup initially suggests 8080 and 8443 instead. If an initially suggested port is not free or cannot be used due to lack of privileges, interactive setup adds 1000 to the port number and tries again, repeatedly adding 1000 until a free port is found. If HTTP or HTTPS is used, leave this port open to client applications. For production deployments, use HTTPS instead of HTTP.
Server administration	4444	Yes	Port for administrative requests, such as requests from the dsconfig command. Interactive setup initially suggests 4444. If an initially suggested port is not free or cannot be used due to lack of privileges, interactive setup adds 1000 to the port number and tries again, repeatedly adding 1000 until a free port is found. Initial setup secures access to this port.
Directory data replication	8989	No	Port for replication requests, using the DS-specific replication protocol. Interactive setup initially suggests 8989. If an initially suggested port is not free or cannot be used due to lack of privileges, interactive setup adds 1000 to the port number and tries again, repeatedly adding 1000 until a free port is found. If replication is used, leave this port open to other replicas. For production deployments, secure access to this port.
JMX	1689	No	Port for Java Management eXtension requests (1689), and JMX RMI requests. The default setting for the JMX RMI port is `0`, meaning the service chooses a port of its own. This can be configured using the JMX connection handler `rmi-port` setting If used in production deployments, secure access to this port.
SNMP	161, 162	No	Reserved ports are 161 for regular SNMP requests and 162 for traps. If used in production deployments, secure access to these ports.

Chapter 6. Standards, RFCs, and Internet-Drafts

DS 6.5 software implements the following RFCs, Internet-Drafts, and standards:

RFC 1274: The COSINE and Internet X.500 Schema

X.500 Directory Schema, or Naming Architecture, for use in the COSINE and Internet X.500 pilots.

RFC 1321: The MD5 Message-Digest Algorithm

MD5 message-digest algorithm that takes as input a message of arbitrary length and produces as output a 128-bit "fingerprint" or "message digest" of the input.

RFC 1777: Lightweight Directory Access Protocol (LDAPv2)

Provide access to the X.500 Directory while not incurring the resource requirements of the Directory Access Protocol.

Classified as an Historic document.

RFC 1778: The String Representation of Standard Attribute Syntaxes

Defines the requirements that must be satisfied by encoding rules used to render X.500 Directory attribute syntaxes into a form suitable for use in the LDAP, then defines the encoding rules for the standard set of attribute syntaxes.

Classified as an Historic document.

RFC 1779: A String Representation of Distinguished Names

Defines a string format for representing names, which is designed to give a clean representation of commonly used names, whilst being able to represent any distinguished name.

Classified as an Historic document.

RFC 2079: Definition of an X.500 Attribute Type and an Object Class to Hold Uniform Resource Identifiers (URIs)

Defines a new attribute type and an auxiliary object class to allow URIs, including URLs, to be stored in directory entries in a standard way.

RFC 2222: Simple Authentication and Security Layer (SASL)

Describes a method for adding authentication support to connection-based protocols.

RFC 2246: The TLS Protocol Version 1.0

Specifies Version 1.0 of the Transport Layer Security protocol.

RFC 2247: Using Domains in LDAP/X.500 Distinguished Names

Defines an algorithm by which a name registered with the Internet Domain Name Service can be represented as an LDAP distinguished name.

RFC 2251: Lightweight Directory Access Protocol (v3)

Describes a directory access protocol designed to provide access to directories supporting the X.500 models, while not incurring the resource requirements of the X.500 Directory Access Protocol.

RFC 2252: Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions

Defines a set of syntaxes for LDAPv3, and the rules by which attribute values of these syntaxes are represented as octet strings for transmission in the LDAP protocol.

RFC 2253: Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names

Defines a common UTF-8 format to represent distinguished names unambiguously.

RFC 2254: The String Representation of LDAP Search Filters

Defines the string format for representing names, which is designed to give a clean representation of commonly used distinguished names, while being able to represent any distinguished name.

RFC 2255: The LDAP URL Format

Describes a format for an LDAP Uniform Resource Locator.

RFC 2256: A Summary of the X.500(96) User Schema for use with LDAPv3

Provides an overview of the attribute types and object classes defined by the ISO and ITU-T committees in the X.500 documents, in particular those intended for use by directory clients.

RFC 2307: An Approach for Using LDAP as a Network Information Service

Describes an experimental mechanism for mapping entities related to TCP/IP and the UNIX system into X.500 entries so that they may be resolved with the Lightweight Directory Access Protocol.

RFC 2377: Naming Plan for Internet Directory-Enabled Applications

Proposes a new directory naming plan that leverages the strengths of the most popular and successful Internet naming schemes for naming objects in a hierarchical directory.

RFC 2696: LDAP Control Extension for Simple Paged Results Manipulation

Allows a client to control the rate at which an LDAP server returns the results of an LDAP search operation.

RFC 2713: Schema for Representing Java(tm) Objects in an LDAP Directory

Defines a common way for applications to store and retrieve Java objects from the directory.

RFC 2714: Schema for Representing CORBA Object References in an LDAP Directory

Define a common way for applications to store and retrieve CORBA object references from the directory.

RFC 2739: Calendar Attributes for vCard and LDAP

Defines a mechanism to locate a user calendar and free/busy time using the LDAP protocol.

RFC 2798: Definition of the inetOrgPerson LDAP Object Class

Define an object class called inetOrgPerson for use in LDAP and X.500 directory services that extends the X.521 standard organizationalPerson class.

RFC 2829: Authentication Methods for LDAP

Specifies particular combinations of security mechanisms which are required and recommended in LDAP implementations.

RFC 2830: Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security

Defines the "Start Transport Layer Security (TLS) Operation" for LDAP.

RFC 2849: The LDAP Data Interchange Format (LDIF) - Technical Specification

Describes a file format suitable for describing directory information or modifications made to directory information.

RFC 2891: LDAP Control Extension for Server Side Sorting of Search Results

Describes two LDAPv3 control extensions for server-side sorting of search results.

RFC 2926: Conversion of LDAP Schemas to and from SLP Templates

Describes a procedure for mapping between Service Location Protocol service advertisements and lightweight directory access protocol descriptions of services.

RFC 3045: Storing Vendor Information in the LDAP root DSE

Specifies two Lightweight Directory Access Protocol attributes, vendorName and vendorVersion that MAY be included in the root DSA-specific Entry (DSE) to advertise vendor-specific information.

RFC 3062: LDAP Password Modify Extended Operation

Describes an LDAP extended operation to allow modification of user passwords which is not dependent upon the form of the authentication identity nor the password storage mechanism used.

RFC 3112: LDAP Authentication Password Schema

Describes schema in support of user/password authentication in a LDAP directory including the authPassword attribute type. This attribute type holds values derived from the user's password(s) (commonly using cryptographic strength one-way hash).

RFC 3296: Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories

Details schema and protocol elements for representing and managing named subordinate references in Lightweight Directory Access Protocol (LDAP) Directories.

RFC 3377: Lightweight Directory Access Protocol (v3): Technical Specification

Specifies the set of RFCs comprising the Lightweight Directory Access Protocol Version 3 (LDAPv3), and addresses the "IESG Note" attached to RFCs 2251 through 2256.

RFC 3383: Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)

Provides procedures for registering extensible elements of the Lightweight Directory Access Protocol (LDAP).

RFC 3546: Transport Layer Security (TLS) Extensions

Describes extensions that may be used to add functionality to Transport Layer Security.

RFC 3671: Collective Attributes in the Lightweight Directory Access Protocol (LDAP)

Summarizes the X.500 information model for collective attributes and describes use of collective attributes in LDAP.

RFC 3672: Subentries in the Lightweight Directory Access Protocol (LDAP)

Adapts X.500 subentries mechanisms for use with the Lightweight Directory Access Protocol (LDAP).

RFC 3673: Lightweight Directory Access Protocol version 3 (LDAPv3): All Operational Attributes

Describes an LDAP extension which clients may use to request the return of all operational attributes.

RFC 3674: Feature Discovery in Lightweight Directory Access Protocol (LDAP)

Introduces a general mechanism for discovery of elective features and extensions which cannot be discovered using existing mechanisms.

RFC 3712: Lightweight Directory Access Protocol (LDAP): Schema for Printer Services

Defines a schema, object classes and attributes, for printers and printer services, for use with directories that support Lightweight Directory Access Protocol v3 (LDAP).

RFC 3771: Lightweight Directory Access Protocol (LDAP) Intermediate Response Message

Defines and describes the IntermediateResponse message, a general mechanism for defining single-request/multiple-response operations in Lightweight Directory Access Protocol.

RFC 3829: Lightweight Directory Access Protocol (LDAP) Authorization Identity Request and Response Controls

Extends the Lightweight Directory Access Protocol bind operation with a mechanism for requesting and returning the authorization identity it establishes.

RFC 3876: Returning Matched Values with the Lightweight Directory Access Protocol version 3 (LDAPv3)

Describes a control for the Lightweight Directory Access Protocol version 3 that is used to return a subset of attribute values from an entry.

RFC 3909: Lightweight Directory Access Protocol (LDAP) Cancel Operation

Describes a Lightweight Directory Access Protocol extended operation to cancel (or abandon) an outstanding operation, with a response to indicate the outcome of the operation.

RFC 4346: The Transport Layer Security (TLS) Protocol Version 1.1

Specifies Version 1.1 of the Transport Layer Security protocol.

RFC 4370: Lightweight Directory Access Protocol (LDAP) Proxied Authorization Control

Defines the Proxy Authorization Control, that allows a client to request that an operation be processed under a provided authorization identity instead of under the current authorization identity associated with the connection.

RFC 4403: Lightweight Directory Access Protocol (LDAP) Schema for Universal Description, Discovery, and Integration version 3 (UDDIv3)

Defines the Lightweight Directory Access Protocol schema for representing Universal Description, Discovery, and Integration data types in an LDAP directory.

RFC 4422: Simple Authentication and Security Layer (SASL)

Describes a framework for providing authentication and data security services in connection-oriented protocols via replaceable mechanisms.

RFC 4505: Anonymous Simple Authentication and Security Layer (SASL) Mechanism

Describes a new way to provide anonymous login is needed within the context of the Simple Authentication and Security Layer framework.

RFC 4510: Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map

Provides a road map of the LDAP Technical Specification.

RFC 4511: Lightweight Directory Access Protocol (LDAP): The Protocol

Describes the protocol elements, along with their semantics and encodings, of the Lightweight Directory Access Protocol.

RFC 4512: Lightweight Directory Access Protocol (LDAP): Directory Information Models

Describes the X.500 Directory Information Models as used in LDAP.

RFC 4513: Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms

Describes authentication methods and security mechanisms of the Lightweight Directory Access Protocol.

RFC 4514: Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names

Defines the string representation used in the Lightweight Directory Access Protocol to transfer distinguished names.

RFC 4515: Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters

Defines a human-readable string representation of LDAP search filters that is appropriate for use in LDAP URLs and in other applications.

RFC 4516: Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator

Describes a format for a Lightweight Directory Access Protocol Uniform Resource Locator.

RFC 4517: Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules

Defines a base set of syntaxes and matching rules for use in defining attributes for LDAP directories.

RFC 4518: Lightweight Directory Access Protocol (LDAP): Internationalized String Preparation

Defines string preparation algorithms for character-based matching rules defined for use in LDAP.

RFC 4519: Lightweight Directory Access Protocol (LDAP): Schema for User Applications

Provides a technical specification of attribute types and object classes intended for use by LDAP directory clients for many directory services, such as White Pages.

RFC 4523: Lightweight Directory Access Protocol (LDAP) Schema Definitions for X.509 Certificates

Describes schema for representing X.509 certificates, X.521 security information, and related elements in directories accessible using the Lightweight Directory Access Protocol (LDAP).

RFC 4524: COSINE LDAP/X.500 Schema

Provides a collection of schema elements for use with the Lightweight Directory Access Protocol from the COSINE and Internet X.500 pilot projects.

RFC 4525: Lightweight Directory Access Protocol (LDAP) Modify-Increment Extension

Describes an extension to the Lightweight Directory Access Protocol Modify operation to support an increment capability.

RFC 4526: Lightweight Directory Access Protocol (LDAP) Absolute True and False Filters

Extends the Lightweight Directory Access Protocol to support absolute True and False filters based upon similar capabilities found in X.500 directory systems.

RFC 4527: Lightweight Directory Access Protocol (LDAP) Read Entry Controls

Specifies an extension to the Lightweight Directory Access Protocol to allow the client to read the target entry of an update operation.

RFC 4528: Lightweight Directory Access Protocol (LDAP) Assertion Control

Defines the Lightweight Directory Access Protocol Assertion Control, which allows a client to specify that a directory operation should only be processed if an assertion applied to the target entry of the operation is true.

RFC 4529: Requesting Attributes by Object Class in the Lightweight Directory Access Protocol (LDAP)

Extends LDAP to support a mechanism that LDAP clients may use to request the return of all attributes of an object class.

RFC 4530: Lightweight Directory Access Protocol (LDAP) entryUUID Operational Attribute

Describes the LDAP/X.500 'entryUUID' operational attribute and associated matching rules and syntax.

RFC 4532: Lightweight Directory Access Protocol (LDAP) "Who am I?" Operation

Provides a mechanism for Lightweight Directory Access Protocol clients to obtain the authorization identity the server has associated with the user or application entity.

RFC 4616: The PLAIN Simple Authentication and Security Layer (SASL) Mechanism

Defines a simple cleartext user/password Simple Authentication and Security Layer mechanism called the PLAIN mechanism.

RFC 4634: US Secure Hash Algorithms (SHA and HMAC-SHA)

Specifies Secure Hash Algorithms, SHA-256, SHA-384, and SHA-512, for computing a condensed representation of a message or a data file.

RFC 4752: The Kerberos V5 ("GSSAPI") Simple Authentication and Security Layer (SASL) Mechanism

Describes the method for using the Generic Security Service Application Program Interface (GSS-API) Kerberos V5 in the Simple Authentication and Security Layer, called the GSSAPI mechanism.

RFC 4876: A Configuration Profile Schema for Lightweight Directory Access Protocol (LDAP)-Based Agents

Defines a schema for storing a profile for agents that make use of the Lightweight Directory Access protocol (LDAP).

RFC 5020: The Lightweight Directory Access Protocol (LDAP) entryDN Operational Attribute

Describes the Lightweight Directory Access Protocol (LDAP) / X.500 'entryDN' operational attribute, that provides a copy of the entry's distinguished name for use in attribute value assertions.

FIPS 180-1: Secure Hash Standard (SHA-1)

Specifies a Secure Hash Algorithm, SHA-1, for computing a condensed representation of a message or a data file.

FIPS 180-2: Secure Hash Standard (SHA-1, SHA-256, SHA-384, SHA-512)

Specifies four Secure Hash Algorithms for computing a condensed representation of electronic data.

DSMLv2: Directory Service Markup Language

Provides a method for expressing directory queries and updates as XML documents.

JavaScript Object Notation

A data-interchange format that aims to be both "easy for humans to read and write," and also "easy for machines to parse and generate."

Simple Cloud Identity Management: Core Schema 1.0

Platform neutral schema and extension model for representing users and groups in JSON and XML formats. DS supports the JSON formats.

The LDAP Relax Rules Control (Internet-Draft)

Experimental LDAP control allowing a directory client application to request temporary relaxation of data and service model rules.

This control relaxes LDAP constraints, allowing operations that are not normally permitted, such as modifying read-only attributes. To prevent misuse, restrict access to this control to limited administrative accounts.

Chapter 7. LDAP Controls

Controls provide a mechanism whereby the semantics and arguments of existing LDAP operations may be extended. One or more controls may be attached to a single LDAP message. A control only affects the semantics of the message it is attached to. Controls sent by clients are termed request controls, and those sent by servers are termed response controls.

DS software supports the following LDAP controls:

Account Usability Control

Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.8

Control originally provided by Sun Microsystems, used to determine whether a user account can be used to authenticate to the directory.

Assertion request control

Object Identifier: 1.3.6.1.1.12

RFC: RFC 4528 - Lightweight Directory Access Protocol (LDAP) Assertion Control

Authorization Identity request control

Object Identifier: 2.16.840.1.113730.3.4.16

RFC: RFC 3829 - Lightweight Directory Access Protocol (LDAP) Authorization Identity Request and Response Controls

Authorization Identity response control

Object Identifier: 2.16.840.1.113730.3.4.15

RFC: RFC 3829 - Lightweight Directory Access Protocol (LDAP) Authorization Identity Request and Response Controls

Entry Change Notification response control

Object Identifier: 2.16.840.1.113730.3.4.7

Internet-Draft: draft-ietf-ldapext-psearch - Persistent Search: A Simple LDAP Change Notification Mechanism

Get Effective Rights request control

Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.2

Internet-Draft: draft-ietf-ldapext-acl-model - Access Control Model for LDAPv3

Manage DSAIT request control

Object Identifier: 2.16.840.1.113730.3.4.2

RFC: RFC 3296 - Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories

Matched Values request control

Object Identifier: 1.2.826.0.1.3344810.2.3

RFC: RFC 3876 - Returning Matched Values with the Lightweight Directory Access Protocol version 3 (LDAPv3)

No-Op Control

Object Identifier: 1.3.6.1.4.1.4203.1.10.2

Internet-Draft: draft-zeilenga-ldap-noop - LDAP No-Op Control

Password Expired response control

Object Identifier: 2.16.840.1.113730.3.4.4

Internet-Draft: draft-vchu-ldap-pwd-policy - Password Policy for LDAP Directories

Password Expiring response control

Object Identifier: 2.16.840.1.113730.3.4.5

Internet-Draft: draft-vchu-ldap-pwd-policy - Password Policy for LDAP Directories

Password Policy response control

Object Identifier: 1.3.6.1.4.1.42.2.27.8.5.1

Internet-Draft: draft-behera-ldap-password-policy - Password Policy for LDAP Directories

Permissive Modify request control

Object Identifier: 1.2.840.113556.1.4.1413

Microsoft defined this control that, "Allows an LDAP modify to work under less restrictive conditions. Without it, a delete will fail if an attribute done not exist, and an add will fail if an attribute already exists. No data is needed in this control." (source of quote)

Persistent Search request control

Object Identifier: 2.16.840.1.113730.3.4.3

Internet-Draft: draft-ietf-ldapext-psearch - Persistent Search: A Simple LDAP Change Notification Mechanism

Post-Read request control

Object Identifier: 1.3.6.1.1.13.2

RFC: RFC 4527 - Lightweight Directory Access Protocol (LDAP) Read Entry Controls

Post-Read response control

Object Identifier: 1.3.6.1.1.13.2

RFC: RFC 4527 - Lightweight Directory Access Protocol (LDAP) Read Entry Controls

Pre-Read request control

Object Identifier: 1.3.6.1.1.13.1

RFC: RFC 4527 - Lightweight Directory Access Protocol (LDAP) Read Entry Controls

Pre-Read response control

Object Identifier: 1.3.6.1.1.13.1

RFC: RFC 4527 - Lightweight Directory Access Protocol (LDAP) Read Entry Controls

Proxied Authorization v1 request control

Object Identifier: 2.16.840.1.113730.3.4.12

Internet-Draft: draft-weltman-ldapv3-proxy-04 - LDAP Proxied Authorization Control

Proxied Authorization v2 request control

Object Identifier: 2.16.840.1.113730.3.4.18

RFC: RFC 4370 - Lightweight Directory Access Protocol (LDAP) Proxied Authorization Control

Public Changelog Exchange Control

Object Identifier: 1.3.6.1.4.1.26027.1.5.4

DS specific, for using the bookmark cookie when reading the external change log.

Server-Side Sort request control

Object Identifier: 1.2.840.113556.1.4.473

RFC: RFC 2891 - LDAP Control Extension for Server Side Sorting of Search Results

Server-Side Sort response control

Object Identifier: 1.2.840.113556.1.4.474

RFC: RFC 2891 - LDAP Control Extension for Server Side Sorting of Search Results

Simple Paged Results Control

Object Identifier: 1.2.840.113556.1.4.319

RFC: RFC 2696 - LDAP Control Extension for Simple Paged Results Manipulation

Subentries request controls

Object Identifier: 1.3.6.1.4.1.4203.1.10.1

RFC: Subentries in the Lightweight Directory Access Protocol (LDAP)

Object Identifier: 1.3.6.1.4.1.7628.5.101.1

Internet-Draft: draft-ietf-ldup-subentry - LDAP Subentry Schema

Subtree Delete request control

Object Identifier: 1.2.840.113556.1.4.805

Internet-Draft: draft-armijo-ldap-treedelete - Tree Delete Control

Transaction ID control

Object Identifier: 1.3.6.1.4.1.36733.2.1.5.1

ForgeRock control that enables Common Audit to associate an ID with a request. The ID is recorded with audit events, and can be used to correlate and track user interactions as they traverse the components of the ForgeRock platform.

The control's value is the UTF-8 encoding of the transaction ID.

Virtual List View request control

Object Identifier: 2.16.840.1.113730.3.4.9

Internet-Draft: draft-ietf-ldapext-ldapv3-vlv - LDAP Extensions for Scrolling View Browsing of Search Results

Virtual List View response control

Object Identifier: 2.16.840.1.113730.3.4.10

Internet-Draft: draft-ietf-ldapext-ldapv3-vlv - LDAP Extensions for Scrolling View Browsing of Search Results

Chapter 8. LDAP Extended Operations

Extended operations allow additional operations to be defined for services not already available in the protocol

DS software supports the following LDAP extended operations:

Cancel Extended Request

Object Identifier: 1.3.6.1.1.8

RFC: RFC 3909 - Lightweight Directory Access Protocol (LDAP) Cancel Operation

Get Connection ID Extended Request

Object Identifier: 1.3.6.1.4.1.26027.1.6.2

DS extended operation to return the connection ID of the associated client connection. This extended operation is intended for DS internal use.

Password Modify Extended Request

Object Identifier: 1.3.6.1.4.1.4203.1.11.1

RFC: RFC 3062 - LDAP Password Modify Extended Operation

Password Policy State Extended Operation

Object Identifier: 1.3.6.1.4.1.26027.1.6.1

DS extended operation to query and update password policy state for a given user entry.

Start Transport Layer Security Extended Request

Object Identifier: 1.3.6.1.4.1.1466.20037

RFC: RFC 4511 - Lightweight Directory Access Protocol (LDAP): The Protocol

Who am I? Extended Request

Object Identifier: 1.3.6.1.4.1.4203.1.11.3

RFC: RFC 4532 - Lightweight Directory Access Protocol (LDAP) "Who am I?" Operation

Chapter 9. Localization

DS software stores data in UTF-8 format. It enables you to store and to search for attribute values according to a variety of language specific locales. DS software is also itself localized for a smaller variety of languages.

9.1. DS Languages

DS 6.5 software is localized in the following languages:

French
German
Japanese
Simplified Chinese
Spanish

Note

Certain messages have also been translated into Catalan, Korean, Polish, and Traditional Chinese. Some error messages including messages labeled ERROR are provided only in English.

9.2. Directory Support For Locales and Language Subtypes

OpenDJ software supports the following locales with their associated language and country codes and their collation order object identifiers. Locale support depends on the Java Virtual Machine used at run time. The following list reflects all supported locales.

Supported Locales

Afrikaans

Code tag: af

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.1.1

Albanian

Code tag: sq

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.127.1

Amharic

Code tag: am

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.2.1

Arabic

Code tag: ar

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.3.1

Arabic (Algeria)

Code tag: ar-DZ

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.6.1

Arabic (Bahrain)

Code tag: ar-BH

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.5.1

Arabic (Egypt)

Code tag: ar-EG

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.7.1

Arabic (India)

Code tag: ar-IN

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.8.1

Arabic (Iraq)

Code tag: ar-IQ

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.9.1

Arabic (Jordan)

Code tag: ar-JO

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.10.1

Arabic (Kuwait)

Code tag: ar-KW

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.11.1

Arabic (Lebanon)

Code tag: ar-LB

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.12.1

Arabic (Libya)

Code tag: ar-LY

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.13.1

Arabic (Morocco)

Code tag: ar-MA

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.14.1

Arabic (Oman)

Code tag: ar-OM

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.15.1

Arabic (Qatar)

Code tag: ar-QA

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.16.1

Arabic (Saudi Arabia)

Code tag: ar-SA

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.17.1

Arabic (Sudan)

Code tag: ar-SD

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.18.1

Arabic (Syria)

Code tag: ar-SY

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.19.1

Arabic (Tunisia)

Code tag: ar-TN

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.20.1

Arabic (United Arab Emirates)

Code tag: ar-AE

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.4.1

Arabic (Yemen)

Code tag: ar-YE

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.21.1

Armenian

Code tag: hy

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.89.1

Basque

Code tag: eu

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.70.1

Belarusian

Code tag: be

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.22.1

Bengali

Code tag: bn

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.24.1

Bulgarian

Code tag: bg

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.23.1

Catalan

Code tag: ca

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.25.1

Chinese

Code tag: zh

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.143.1

Chinese (China)

Code tag: zh-CN

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.144.1

Chinese (Hong Kong)

Code tag: zh-HK

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.145.1

Chinese (Macao)

Code tag: zh-MO

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.146.1

Chinese (Singapore)

Code tag: zh-SG

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.147.1

Chinese (Taiwan)

Code tag: zh-TW

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.148.1

Cornish

Code tag: kw

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.99.1

Croatian

Code tag: hr

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.87.1

Czech

Code tag: cs

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.26.1

Danish

Code tag: da

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.27.1

Dutch

Code tag: nl

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.105.1

Dutch (Belgium)

Code tag: nl-BE

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.106.1

Dutch (Netherlands)

Code tag: nl-NL

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.105.1

English

Code tag: en

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.34.1

English (Australia)

Code tag: en-AU

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.35.1

English (Canada)

Code tag: en-CA

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.36.1

English (Hong Kong)

Code tag: en-HK

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.38.1

English (India)

Code tag: en-IN

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.40.1

English (Ireland)

Code tag: en-IE

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.39.1

English (Malta)

Code tag: en-MT

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.41.1

English (New Zealand)

Code tag: en-NZ

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.42.1

English (Philippines)

Code tag: en-PH

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.43.1

English (Singapore)

Code tag: en-SG

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.44.1

English (South Africa)

Code tag: en-ZA

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.46.1

English (U.S. Virgin Islands)

Code tag: en-VI

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.45.1

English (United Kingdom)

Code tag: en-GB

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.37.1

English (United States)

Code tag: en-US

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.34.1

English (Zimbabwe)

Code tag: en-ZW

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.47.1

Esperanto

Code tag: eo

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.48.1

Estonian

Code tag: et

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.69.1

Faroese

Code tag: fo

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.75.1

Finnish

Code tag: fi

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.74.1

French

Code tag: fr

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.76.1

French (Belgium)

Code tag: fr-BE

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.77.1

French (Canada)

Code tag: fr-CA

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.78.1

French (France)

Code tag: fr-FR

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.76.1

French (Luxembourg)

Code tag: fr-LU

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.80.1

French (Switzerland)

Code tag: fr-CH

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.79.1

Gallegan

Code tag: gl

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.82.1

German

Code tag: de

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.28.1

German (Austria)

Code tag: de-AT

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.29.1

German (Belgium)

Code tag: de-BE

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.30.1

German (Germany)

Code tag: de-DE

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.28.1

German (Luxembourg)

Code tag: de-LU

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.32.1

German (Switzerland)

Code tag: de-CH

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.31.1

Greek

Code tag: el

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.33.1

Greenlandic

Code tag: kl

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.95.1

Gujarati

Code tag: gu

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.83.1

Hebrew

Code tag: iw

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.85.1

Hindi

Code tag: hi

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.86.1

Hungarian

Code tag: hu

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.88.1

Icelandic

Code tag: is

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.91.1

Indonesian

Code tag: in

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.90.1

Irish

Code tag: ga

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.81.1

Italian

Code tag: it

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.92.1

Italian (Switzerland)

Code tag: it-CH

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.93.1

Japanese

Code tag: ja

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.94.1

Kannada

Code tag: kn

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.96.1

Konkani

Code tag: kok

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.98.1

Korean

Code tag: ko

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.97.1

Latvian

Code tag: lv

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.101.1

Lithuanian

Code tag: lt

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.100.1

Macedonian

Code tag: mk

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.102.1

Maltese

Code tag: mt

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.104.1

Manx

Code tag: gv

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.84.1

Marathi

Code tag: mr

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.103.1

Norwegian

Code tag: no

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.107.1

Norwegian (Norway)

Code tag: no-NO-NY

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.108.1

Norwegian Bokmål

Code tag: nb

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.110.1

Norwegian Nynorsk

Code tag: nn

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.109.1

Oromo

Code tag: om

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.111.1

Oromo (Ethiopia)

Code tag: om-ET

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.112.1

Oromo (Kenya)

Code tag: om-KE

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.113.1

Persian

Code tag: fa

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.71.1

Persian (India)

Code tag: fa-IN

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.72.1

Persian (Iran)

Code tag: fa-IR

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.73.1

Polish

Code tag: pl

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.114.1

Portuguese

Code tag: pt

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.115.1

Portuguese (Brazil)

Code tag: pt-BR

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.116.1

Portuguese (Portugal)

Code tag: pt-PT

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.115.1

Romanian

Code tag: ro

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.117.1

Russian

Code tag: ru

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.118.1

Russian (Russia)

Code tag: ru-RU

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.118.1

Russian (Ukraine)

Code tag: ru-UA

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.119.1

Serbian

Code tag: sr

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.128.1

Serbo-Croatian

Code tag: sh

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.120.1

Slovak

Code tag: sk

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.121.1

Slovenian

Code tag: sl

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.122.1

Somali

Code tag: so

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.123.1

Somali (Djibouti)

Code tag: so-DJ

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.124.1

Somali (Ethiopia)

Code tag: so-ET

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.125.1

Somali (Kenya)

Code tag: so-KE

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.126.1

Somali (Somalia)

Code tag: so-SO

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.123.1

Spanish

Code tag: es

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.49.1

Spanish (Argentina)

Code tag: es-AR

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.50.1

Spanish (Bolivia)

Code tag: es-BO

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.51.1

Spanish (Chile)

Code tag: es-CL

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.52.1

Spanish (Colombia)

Code tag: es-CO

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.53.1

Spanish (Costa Rica)

Code tag: es-CR

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.54.1

Spanish (Dominican Republic)

Code tag: es-DO

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.55.1

Spanish (Ecuador)

Code tag: es-EC

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.56.1

Spanish (El Salvador)

Code tag: es-SV

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.65.1

Spanish (Guatemala)

Code tag: es-GT

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.57.1

Spanish (Honduras)

Code tag: es-HN

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.58.1

Spanish (Mexico)

Code tag: es-MX

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.59.1

Spanish (Nicaragua)

Code tag: es-NI

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.60.1

Spanish (Panama)

Code tag: es-PA

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.61.1

Spanish (Paraguay)

Code tag: es-PY

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.64.1

Spanish (Peru)

Code tag: es-PE

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.62.1

Spanish (Puerto Rico)

Code tag: es-PR

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.63.1

Spanish (Spain)

Code tag: es-ES

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.49.1

Spanish (United States)

Code tag: es-US

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.66.1

Spanish (Uruguay)

Code tag: es-UY

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.67.1

Spanish (Venezuela)

Code tag: es-VE

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.68.1

Swahili

Code tag: sw

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.131.1

Swahili (Kenya)

Code tag: sw-KE

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.132.1

Swahili (Tanzania)

Code tag: sw-TZ

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.133.1

Swedish

Code tag: sv

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.129.1

Swedish (Finland)

Code tag: sv-FI

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.130.1

Swedish (Sweden)

Code tag: sv-SE

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.129.1

Tamil

Code tag: ta

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.134.1

Telugu

Code tag: te

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.135.1

Thai

Code tag: th

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.136.1

Tigrinya

Code tag: ti

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.137.1

Tigrinya (Eritrea)

Code tag: ti-ER

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.138.1

Tigrinya (Ethiopia)

Code tag: ti-ET

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.139.1

Turkish

Code tag: tr

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.140.1

Ukrainian

Code tag: uk

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.141.1

Vietnamese

Code tag: vi

Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.142.1

Supported Language Subtypes

Afrikaans, af
Albanian, sq
Amharic, am
Arabic, ar
Armenian, hy
Basque, eu
Belarusian, be
Bengali, bn
Bulgarian, bg
Catalan, ca
Chinese, zh
Cornish, kw
Croatian, hr
Czech, cs
Danish, da
Dutch, nl
English, en
Esperanto, eo
Estonian, et
Faroese, fo
Finnish, fi
French, fr
Gallegan, gl
German, de
Greek, el
Greenlandic, kl
Gujarati, gu
Hebrew, iw
Hindi, hi
Hungarian, hu
Icelandic, is
Indonesian, in
Irish, ga
Italian, it
Japanese, ja
Kannada, kn
Konkani, kok
Korean, ko
Latvian, lv
Lithuanian, lt
Macedonian, mk
Maltese, mt
Manx, gv
Marathi, mr
Norwegian, no
Norwegian Bokmål, nb
Norwegian Nynorsk, nn
Oromo, om
Persian, fa
Polish, pl
Portuguese, pt
Romanian, ro
Russian, ru
Serbian, sr
Serbo-Croatian, sh
Slovak, sk
Slovenian, sl
Somali, so
Spanish, es
Swahili, sw
Swedish, sv
Tamil, ta
Telugu, te
Thai, th
Tigrinya, ti
Turkish, tr
Ukrainian, uk
Vietnamese, vi

Chapter 10. Monitoring Metrics

DS server software exposes the monitoring metrics described in this chapter.

10.1. Metric Types

The following table describes the monitoring metrics that are available in each interface:

Type	Description
Counter	Cumulative metric for a numerical value that only increases while the server is running. Counts that reflect volatile data, such as the number of requests, are reset to 0 when the server starts up.
Gauge	Metric for a numerical value that can increase or decrease.
Summary	Metric that samples observations, providing a count of observations, sum total of observed amounts, average rate of events, and moving average rates across sliding time windows. Common REST and LDAP views show summaries as JSON objects. JSON summaries have the following fields:^[a] { "count": number, // Number of events since the server started "total": number, // Sum of quantities measured for each event // since the server started // The following are related to the "count": "mean_rate": number, // Average event rate per second // since the server started "m1_rate": number, // One-minute average event rate per second // (exponentially decaying) "m5_rate": number, // Five-minute average event rate per second // (exponentially decaying) "m15_rate": number, // Fifteen-minute average event rate per second // (exponentially decaying) } The `"total"` depends on the type of events measured. For example, if the `"count"` is the number of requests, then the `"total"` is the total etime in milliseconds to process all the requests. If the `"count"` is the number of times the server read bytes of data, then the `"total"` is the total number of bytes read. The Prometheus view does not provide time-based statistics, as rates can be calculated from the time-series data. Instead, the Prometheus view includes summary metrics whose names have the following suffixes or labels: `_count`: number of events since the server started `_total`: sum of quantities measured for each event since the server started `{quantile="0.5"}`: 50% at or below this value since the server started `{quantile="0.75"}`: 75% at or below this value since the server started `{quantile="0.95"}`: 95% at or below this value since the server started `{quantile="0.98"}`: 98% at or below this value since the server started `{quantile="0.99"}`: 99% at or below this value since the server started `{quantile="0.999"}`: 99.9% at or below this value since the server started
Timer	Metric combining a summary with other statistics. Common REST and LDAP views show summaries as JSON objects. JSON summaries have the following fields:^[a] { "count": number, // Number of events since the server started "total": number, // Total duration for all events // since the server started, in ms // (for requests, sum of the etimes // since the server started, in ms) // The following are related to the "count": "mean_rate": number, // Average event rate per second // since the server started "m1_rate": number, // One-minute average event rate per second // (exponentially decaying) "m5_rate": number, // Five-minute average event rate per second // (exponentially decaying) "m15_rate": number, // Fifteen-minute average event rate per second // (exponentially decaying) // The following are related to the "total": "mean": number, // Average duration over all events // since the server started, in ms "min": number, // Minimum duration recorded // since the server started, in ms "max": number, // Maximum duration recorded // since the server started, in ms "stddev": number, // Standard deviation of durations // since the server started, in ms "p50": number, // 50% durations at or below this value // (median) since the server started, in ms "p75": number, // 75% durations at or below this value // since the server started, in ms "p95": number, // 95% durations at or below this value // since the server started, in ms "p98": number, // 98% durations at or below this value // since the server started, in ms "p99": number, // 99% durations at or below this value // since the server started, in ms "p999": number, // 99.9% durations at or below this value // since the server started, in ms "p9999": number, // 99.99% durations at or below this value // since the server started, in ms "p99999": number // 99.999% durations at or below this value // since the server started, in ms } The Prometheus view does not provide time-based statistics. Rates can be calculated from the time-series data.
^[a] Monitoring metrics reflect sample observations made while the server is running. The values are not saved when the server shuts down. As a result, metrics of this type reflect data recorded since the server started. Metrics that show etime measurements in milliseconds (ms) continue to show values in ms even if the server is configured to log etimes in nanoseconds. The calculation of moving averages is intended to be the same as that of the uptime and top commands, where the moving average plotted over time is smoothed by weighting that decreases exponentially. For an explanation of the mechanism, see the Wikipedia section, Exponential moving average.

Some LDAP monitoring attributes use other syntaxes beyond the types described in this section. LDAP syntaxes are detailed in the LDAP Schema Reference.

10.2. LDAP Metrics

This section lists available LDAP metrics by name, indicating their types as described in "Metric Types".

LDAP metrics are exposed as LDAP attributes on entries under cn=monitor. Metrics entry object class names start with ds-monitor. Metrics attribute names start with ds-mon. The LDAP Schema Reference describes object classes, attribute types, and syntaxes.

Note

Some ds-mon-jvm-* metrics depend on the JVM version and configuration. In particular, GC-related metrics depend on the garbage collector that the server uses. The GC metric names are unstable, and can change even in a minor JVM release.

LDAP Metrics by Name

Name	Syntax	Description
`ds-mon-abandoned-requests`	Counter metric	Total number of abandoned operations since startup
`ds-mon-active-connections-count`	Integer	Number of active client connections
`ds-mon-active-persistent-searches`	Integer	Number of active persistent searches
`ds-mon-alive`	Boolean	Indicates whether the server is alive
`ds-mon-alive-errors`	Directory String	Lists server errors preventing the server from operating correctly that require administrative action
`ds-mon-approx-oldest-change-not-synchronized`	Generalized Time	Approximate date and time of the oldest change not yet synchronized
`ds-mon-approximate-delay`	Duration in milli-seconds	Approximate delay between this server and the connected replica
`ds-mon-backend-degraded-index-count`	Integer	Number of degraded indexes in the backend
`ds-mon-backend-degraded-index`	Directory String	Backend degraded index
`ds-mon-backend-entry-count`	Integer	Number of entries contained in the backend
`ds-mon-backend-filter-use-indexed`	Integer	Number of indexed searches performed against the backend
`ds-mon-backend-filter-use-start-time`	Generalized Time	Time when recording started for statistical information about the simple search filters processed against the backend
`ds-mon-backend-filter-use-unindexed`	Integer	Number of unindexed searches performed against the backend
`ds-mon-backend-filter-use`	Json	Information about the simple search filter processed against the backend
`ds-mon-backend-is-private`	Boolean	Whether the base DNs of this backend should be considered public or private
`ds-mon-backend-proxy-base-dn`	DN	Base DNs routed to remote LDAP servers by the proxy backend
`ds-mon-backend-proxy-shard`	Summary metric	Remote LDAP servers that the proxy backend forwards requests to
`ds-mon-backend-ttl-entries-deleted`	Summary metric	Summary for entries purged by time-to-live
`ds-mon-backend-ttl-is-running`	Boolean	Indicates whether time-to-live is in the process of purging expired entries
`ds-mon-backend-ttl-last-run-time`	Generalized Time	Last date and time when time-to-live finished purging expired entries
`ds-mon-backend-ttl-queue-size`	Integer	Number of entries queued for purging by the time-to-live service
`ds-mon-backend-ttl-thread-count`	Integer	Number of active time-to-live threads
`ds-mon-backend-writability-mode`	Directory String	Current backend behavior when processing write operations, can either be "disabled", "enabled" or "internal-only"
`ds-mon-base-dn-entry-count`	Integer	Number of subordinate entries of the base DN, including the base DN
`ds-mon-base-dn`	DN	Base DN handled by a backend
`ds-mon-build-number`	Integer	Build number of the Directory Server
`ds-mon-build-time`	Generalized Time	Build date and time of the Directory Server
`ds-mon-bytes-read`	Summary metric	Network bytes read summary
`ds-mon-bytes-written`	Summary metric	Network bytes written summary
`ds-mon-cache-entry-count`	Integer	Current number of entries held in this cache
`ds-mon-cache-max-entry-count`	Integer	Maximum number of entries allowed in this cache
`ds-mon-cache-max-size-bytes`	Size in bytes	Memory limit for this cache
`ds-mon-cache-misses`	Summary metric	Number of attempts to retrieve an entry that was not held in this cache
`ds-mon-cache-total-tries`	Summary metric	Number of attempts to retrieve an entry from this cache
`ds-mon-certificate-expires-at`	Generalized Time	Certificate expiration date and time
`ds-mon-certificate-issuer-dn`	DN	Certificate issuer DN
`ds-mon-certificate-serial-number`	Integer	Certificate serial number
`ds-mon-certificate-subject-dn`	DN	Certificate subject DN
`ds-mon-compact-version`	Directory String	Compact version of the Directory Server
`ds-mon-config-dn`	DN	DN of the configuration entry
`ds-mon-connected-to-server-hostport`	Host port	Host and replication port of the server that this server is connected to
`ds-mon-connected-to-server-id`	Integer	Identifier of the server that this server is connected to
`ds-mon-connection`	Json	Client connection summary information
`ds-mon-connections`	Summary metric	Connection summary
`ds-mon-current-connections`	Integer	Number of client connections currently established with the Directory Server
`ds-mon-current-delay`	Duration in milli-seconds	Current local delay in replaying replicated operations
`ds-mon-current-receive-window`	Integer	Current replication window size for receiving messages, indicating the number of replication messages a remote server can send before waiting on acknowledgement from this server. This does not depend on the TCP window size
`ds-mon-current-send-window`	Integer	Current replication window size for sending messages, indicating the number of replication messages this server can send before waiting on acknowledgement from the receiving server. This does not depend on the TCP window size
`ds-mon-current-time`	Generalized Time	Current date and time
`ds-mon-db-cache-evict-internal-nodes-count`	Integer	Number of internal nodes evicted from the database cache
`ds-mon-db-cache-evict-leaf-nodes-count`	Integer	Number of leaf nodes (data records) evicted from the database cache
`ds-mon-db-cache-misses-internal-nodes`	Integer	Number of internal nodes requested by btree operations that were not in the database cache
`ds-mon-db-cache-misses-leaf-nodes`	Integer	Number of leaf nodes (data records) requested by btree operations that were not in the database cache
`ds-mon-db-cache-size-active`	Size in bytes	Size of the database cache
`ds-mon-db-cache-size-total`	Size in bytes	Maximum size of the database cache
`ds-mon-db-cache-total-tries-internal-nodes`	Integer	Number of internal nodes requested by btree operations
`ds-mon-db-cache-total-tries-leaf-nodes`	Integer	Number of leaf nodes (data records) requested by btree operations
`ds-mon-db-checkpoint-count`	Integer	Number of checkpoints run so far
`ds-mon-db-log-cleaner-file-deletion-count`	Integer	Number of cleaner file deletions
`ds-mon-db-log-files-open`	Integer	Number of files currently open in the database file cache
`ds-mon-db-log-files-opened`	Integer	Number of times a log file has been opened
`ds-mon-db-log-size-active`	Size in bytes	Estimate of the amount in bytes of live data in all data files (i.e., the size of the DB, ignoring garbage)
`ds-mon-db-log-size-total`	Size in bytes	Size used by all data files on disk
`ds-mon-db-log-utilization-max`	Integer	Current maximum (upper bound) log utilization as a percentage
`ds-mon-db-log-utilization-min`	Integer	Current minimum (lower bound) log utilization as a percentage
`ds-mon-db-version`	Directory String	Database version used by the backend
`ds-mon-disk-dir`	Filesystem path	A monitored directory containing data that may change over time
`ds-mon-disk-free`	Size in bytes	Amount of free disk space
`ds-mon-disk-full-threshold`	Size in bytes	Effective full disk space threshold
`ds-mon-disk-low-threshold`	Size in bytes	Effective low disk space threshold
`ds-mon-disk-root`	Filesystem path	Monitored disk root
`ds-mon-disk-state`	Directory String	Current disk state, can be either "normal", "low" or "full"
`ds-mon-domain-generation-id`	Integer	Replication domain generation identifier
`ds-mon-domain-name`	DN	Replication domain name
`ds-mon-entries-awaiting-updates-count`	Duration in milli-seconds	Number of entries for which an update operation has been received but not replayed yet by this replica
`ds-mon-fix-ids`	Directory String	IDs of issues that have been fixed in this Directory Server build
`ds-mon-full-version`	Directory String	Full version of the Directory Server
`ds-mon-healthy`	Boolean	Indicates whether the server is able to handle requests
`ds-mon-healthy-errors`	Directory String	Lists transient server errors preventing the server from temporarily handling requests
`ds-mon-install-path`	Filesystem path	Directory Server root installation path
`ds-mon-instance-path`	Filesystem path	Directory Server instance path
`ds-mon-jvm-architecture`	Directory String	Java virtual machine architecture (e.g. 32-bit, 64-bit)
`ds-mon-jvm-arguments`	Directory String	Input arguments passed to the Java virtual machine
`ds-mon-jvm-available-cpus`	Integer	Number of processors available to the Java virtual machine
`ds-mon-jvm-class-path`	Filesystem path	Path used to find directories and JAR archives containing Java class files
`ds-mon-jvm-classes-loaded`	Integer	Number of classes loaded since the Java virtual machine started
`ds-mon-jvm-classes-unloaded`	Integer	Number of classes unloaded since the Java virtual machine started
`ds-mon-jvm-garbage-collector-concurrent-mark-sweep-count`	Integer	Number of collections performed by the "concurrent mark sweep" garbage collection algorithm
`ds-mon-jvm-garbage-collector-concurrent-mark-sweep-time`	Duration in milli-seconds	Approximate accumulated time taken by the "concurrent mark sweep" garbage collection algorithm
`ds-mon-jvm-garbage-collector-copy-count`	Integer	Number of collections performed by the "copy" garbage collection algorithm
`ds-mon-jvm-garbage-collector-copy-time`	Duration in milli-seconds	Approximate accumulated time taken by the "copy" garbage collection algorithm
`ds-mon-jvm-garbage-collector-g1-old-generation-count`	Integer	Number of collections performed by the "g1 old generation" garbage collection algorithm
`ds-mon-jvm-garbage-collector-g1-old-generation-time`	Duration in milli-seconds	Approximate accumulated time taken by the "g1 old generation" garbage collection algorithm
`ds-mon-jvm-garbage-collector-g1-young-generation-count`	Integer	Number of collections performed by the "g1 young generation" garbage collection algorithm
`ds-mon-jvm-garbage-collector-g1-young-generation-time`	Duration in milli-seconds	Approximate accumulated time taken by the "g1 young generation" garbage collection algorithm
`ds-mon-jvm-garbage-collector-mark-sweep-compact-count`	Integer	Number of collections performed by the "mark sweep compact" garbage collection algorithm
`ds-mon-jvm-garbage-collector-mark-sweep-compact-time`	Duration in milli-seconds	Approximate accumulated time taken by the "mark sweep compact" garbage collection algorithm
`ds-mon-jvm-garbage-collector-par-new-count`	Integer	Number of collections performed by the "par new" garbage collection algorithm
`ds-mon-jvm-garbage-collector-par-new-time`	Duration in milli-seconds	Approximate accumulated time taken by the "par new" garbage collection algorithm
`ds-mon-jvm-garbage-collector-ps-mark-sweep-count`	Integer	Number of collections performed by the "parallel scavenge mark sweep" garbage collection algorithm
`ds-mon-jvm-garbage-collector-ps-mark-sweep-time`	Duration in milli-seconds	Approximate accumulated time taken by the "parallel scavenge mark sweep" garbage collection algorithm
`ds-mon-jvm-garbage-collector-ps-scavenge-count`	Integer	Number of collections performed by the "parallel scavenge" garbage collection algorithm
`ds-mon-jvm-garbage-collector-ps-scavenge-time`	Duration in milli-seconds	Approximate accumulated time taken by the "parallel scavenge" garbage collection algorithm
`ds-mon-jvm-java-home`	Filesystem path	Installation directory for Java runtime environment (JRE)
`ds-mon-jvm-java-vendor`	Directory String	Java runtime environment (JRE) vendor
`ds-mon-jvm-java-version`	Directory String	Java runtime environment (JRE) version
`ds-mon-jvm-memory-heap-init`	Size in bytes	Amount of heap memory that the Java virtual machine initially requested from the operating system
`ds-mon-jvm-memory-heap-max`	Size in bytes	Maximum amount of heap memory that the Java virtual machine will attempt to use
`ds-mon-jvm-memory-heap-reserved`	Size in bytes	Amount of heap memory that is committed for the Java virtual machine to use
`ds-mon-jvm-memory-heap-used`	Size in bytes	Amount of heap memory used by the Java virtual machine
`ds-mon-jvm-memory-init`	Size in bytes	Amount of memory that the Java virtual machine initially requested from the operating system
`ds-mon-jvm-memory-max`	Size in bytes	Maximum amount of memory that the Java virtual machine will attempt to use
`ds-mon-jvm-memory-non-heap-init`	Size in bytes	Amount of non-heap memory that the Java virtual machine initially requested from the operating system
`ds-mon-jvm-memory-non-heap-max`	Size in bytes	Maximum amount of non-heap memory that the Java virtual machine will attempt to use
`ds-mon-jvm-memory-non-heap-reserved`	Size in bytes	Amount of non-heap memory that is committed for the Java virtual machine to use
`ds-mon-jvm-memory-non-heap-used`	Size in bytes	Amount of non-heap memory used by the Java virtual machine
`ds-mon-jvm-memory-pools-code-cache-init`	Size in bytes	Amount of "code cache" memory that the Java virtual machine initially requested from the operating system
`ds-mon-jvm-memory-pools-code-cache-max`	Size in bytes	Maximum amount of "code cache" memory that the Java virtual machine will attempt to use
`ds-mon-jvm-memory-pools-code-cache-reserved`	Size in bytes	Amount of "code cache" memory that is committed for the Java virtual machine to use
`ds-mon-jvm-memory-pools-code-cache-used`	Size in bytes	Amount of "code cache" memory used by the Java virtual machine
`ds-mon-jvm-memory-pools-compressed-class-space-init`	Size in bytes	Amount of "compressed class space" memory that the Java virtual machine initially requested from the operating system
`ds-mon-jvm-memory-pools-compressed-class-space-max`	Size in bytes	Maximum amount of "compressed class space" memory that the Java virtual machine will attempt to use
`ds-mon-jvm-memory-pools-compressed-class-space-reserved`	Size in bytes	Amount of "compressed class space" memory that is committed for the Java virtual machine to use
`ds-mon-jvm-memory-pools-compressed-class-space-used`	Size in bytes	Amount of "compressed class space" memory used by the Java virtual machine
`ds-mon-jvm-memory-pools-metaspace-init`	Size in bytes	Amount of "metaspace" memory that the Java virtual machine initially requested from the operating system
`ds-mon-jvm-memory-pools-metaspace-max`	Size in bytes	Maximum amount of "metaspace" memory that the Java virtual machine will attempt to use
`ds-mon-jvm-memory-pools-metaspace-reserved`	Size in bytes	Amount of "metaspace" memory that is committed for the Java virtual machine to use
`ds-mon-jvm-memory-pools-metaspace-used`	Size in bytes	Amount of "metaspace" memory used by the Java virtual machine
`ds-mon-jvm-memory-pools-ps-eden-space-init`	Size in bytes	Amount of "parallel scavenge eden space" memory that the Java virtual machine initially requested from the operating system
`ds-mon-jvm-memory-pools-ps-eden-space-max`	Size in bytes	Maximum amount of "parallel scavenge eden space" memory that the Java virtual machine will attempt to use
`ds-mon-jvm-memory-pools-ps-eden-space-reserved`	Size in bytes	Amount of "parallel scavenge eden space" memory that is committed for the Java virtual machine to use
`ds-mon-jvm-memory-pools-ps-eden-space-used-after-gc`	Size in bytes	Amount of "parallel scavenge eden space" memory after the last time garbage collection recycled unused objects in this memory pool
`ds-mon-jvm-memory-pools-ps-eden-space-used`	Size in bytes	Amount of "parallel scavenge eden space" memory used by the Java virtual machine
`ds-mon-jvm-memory-pools-ps-old-gen-init`	Size in bytes	Amount of "parallel scavenge old generation" memory that the Java virtual machine initially requested from the operating system
`ds-mon-jvm-memory-pools-ps-old-gen-max`	Size in bytes	Maximum amount of "parallel scavenge old generation" memory that the Java virtual machine will attempt to use
`ds-mon-jvm-memory-pools-ps-old-gen-reserved`	Size in bytes	Amount of "parallel scavenge old generation" memory that is committed for the Java virtual machine to use
`ds-mon-jvm-memory-pools-ps-old-gen-used-after-gc`	Size in bytes	Amount of "parallel scavenge old generation" memory after the last time garbage collection recycled unused objects in this memory pool
`ds-mon-jvm-memory-pools-ps-old-gen-used`	Size in bytes	Amount of "parallel scavenge old generation" memory used by the Java virtual machine
`ds-mon-jvm-memory-pools-ps-survivor-space-init`	Size in bytes	Amount of "parallel scavenge survivor space" memory that the Java virtual machine initially requested from the operating system
`ds-mon-jvm-memory-pools-ps-survivor-space-max`	Size in bytes	Maximum amount of "parallel scavenge survivor space" memory that the Java virtual machine will attempt to use
`ds-mon-jvm-memory-pools-ps-survivor-space-reserved`	Size in bytes	Amount of "parallel scavenge survivor space" memory that is committed for the Java virtual machine to use
`ds-mon-jvm-memory-pools-ps-survivor-space-used-after-gc`	Size in bytes	Amount of "parallel scavenge survivor space" memory after the last time garbage collection recycled unused objects in this memory pool
`ds-mon-jvm-memory-pools-ps-survivor-space-used`	Size in bytes	Amount of "parallel scavenge survivor space" memory used by the Java virtual machine
`ds-mon-jvm-memory-reserved`	Size in bytes	Amount of memory that is committed for the Java virtual machine to use
`ds-mon-jvm-memory-used`	Size in bytes	Amount of memory used by the Java virtual machine
`ds-mon-jvm-supported-tls-ciphers`	Directory String	Transport Layer Security (TLS) cipher suites supported by this Directory Server
`ds-mon-jvm-supported-tls-protocols`	Directory String	Transport Layer Security (TLS) protocols supported by this Directory Server
`ds-mon-jvm-threads-blocked-count`	Integer	Number of threads in the BLOCKED state
`ds-mon-jvm-threads-count`	Integer	Number of live threads including both daemon and non-daemon threads
`ds-mon-jvm-threads-daemon-count`	Integer	Number of live daemon threads
`ds-mon-jvm-threads-deadlock-count`	Integer	Number of deadlocked threads
`ds-mon-jvm-threads-deadlocks`	Directory String	Diagnostic stack traces for deadlocked threads
`ds-mon-jvm-threads-new-count`	Integer	Number of threads in the NEW state
`ds-mon-jvm-threads-runnable-count`	Integer	Number of threads in the RUNNABLE state
`ds-mon-jvm-threads-terminated-count`	Integer	Number of threads in the TERMINATED state
`ds-mon-jvm-threads-timed-waiting-count`	Integer	Number of threads in the TIMED_WAITING state
`ds-mon-jvm-threads-waiting-count`	Integer	Number of threads in the WAITING state
`ds-mon-jvm-vendor`	Directory String	Java virtual machine vendor
`ds-mon-jvm-version`	Directory String	Java virtual machine version
`ds-mon-listen-address`	Directory String	Host and port
`ds-mon-lost-connections`	Duration in milli-seconds	Number of times the replica lost its connection to the replication server
`ds-mon-major-version`	Integer	Major version number of the Directory Server
`ds-mon-max-connections`	Integer	Maximum number of simultaneous client connections that have been established with the Directory Server
`ds-mon-max-receive-window`	Integer	Maximum replication window size for receiving messages, indicating the number of replication messages a remote server can send before waiting on acknowledgement from this server. This does not depend on the TCP window size
`ds-mon-max-send-window`	Integer	Maximum replication window size for sending messages, indicating the number of replication messages this server can send before waiting on acknowledgement from the receiving server. This does not depend on the TCP window size
`ds-mon-minor-version`	Integer	Minor version number of the Directory Server
`ds-mon-missing-changes`	Integer	Missing changes for replication
`ds-mon-newest-change-number`	Integer	Newest change number present in the change number index database
`ds-mon-newest-csn-timestamp`	Generalized Time	Timestamp of the newest CSN present in the replica database
`ds-mon-newest-csn`	CSN (Change Sequence Number)	Newest CSN present in the replica database
`ds-mon-oldest-change-number`	Integer	Oldest change number present in the change number index database
`ds-mon-oldest-csn-timestamp`	Generalized Time	Timestamp of the oldest CSN present in the replica database
`ds-mon-oldest-csn`	CSN (Change Sequence Number)	Oldest CSN present in the replica database
`ds-mon-os-architecture`	Directory String	Operating system architecture
`ds-mon-os-name`	Directory String	Operating system name
`ds-mon-os-version`	Directory String	Operating system version
`ds-mon-point-version`	Integer	Point version number of the Directory Server
`ds-mon-product-name`	Directory String	Full name of the Directory Server
`ds-mon-protocol`	Directory String	Network protocol
`ds-mon-replayed-updates-conflicts-resolved`	Counter metric	Number of updates replayed on this replica for which replication naming conflicts have been resolved
`ds-mon-replayed-updates-conflicts-unresolved`	Counter metric	Number of updates replayed on this replica for which replication naming conflicts have not been resolved
`ds-mon-replayed-updates`	Timer metric	Timer for updates that have been replayed on this replica
`ds-mon-requests-abandon`	Timer metric	Abandon request timer
`ds-mon-requests-add`	Timer metric	Add request timer
`ds-mon-requests-bind`	Timer metric	Bind request timer
`ds-mon-requests-compare`	Timer metric	Compare request timer
`ds-mon-requests-delete`	Timer metric	Delete request timer
`ds-mon-requests-extended`	Timer metric	Extended request timer
`ds-mon-requests-failure-client-invalid-request`	Timer metric	Timer for requests that failed because there was a problem while attempting to perform the associated operation (associated LDAP result codes: 1, 2, 12, 15, 16, 17, 18, 19, 20, 21, 23, 34, 35, 36, 37, 38, 39; associated HTTP status codes: client error (4xx) except 401 and 403)
`ds-mon-requests-failure-client-redirect`	Timer metric	Timer for requests that could not complete because further action is required (associated HTTP status codes: redirection (3xx))
`ds-mon-requests-failure-client-referral`	Timer metric	Timer for requests that failed because the server did not hold the request targeted entry (but was able to provide alternative servers that may) (associated LDAP result code: 10)
`ds-mon-requests-failure-client-resource-limit`	Timer metric	Timer for requests that failed because they were trying to exceed the resource limits allocated to the associated clients (associated LDAP result codes: time, size and admin limit exceeded (respectively 4, 5 and 11)
`ds-mon-requests-failure-client-security`	Timer metric	Timer for requests that failed for security reasons (associated LDAP result codes: 8, 9, 13, 25, 26, 27; associated HTTP status codes: unauthorized (401) and forbidden (403))
`ds-mon-requests-failure-server`	Timer metric	Timer for apparently valid requests that failed because the server was not able to process them (associated LDAP result codes: busy (51), unavailable (52), unwilling to perform (53) and other (80); associated HTTP status codes: server error (5xx))
`ds-mon-requests-failure-uncategorized`	Timer metric	Timer for requests that failed due to uncategorized reasons
`ds-mon-requests-get`	Timer metric	GET request timer
`ds-mon-requests-in-queue`	Integer	Number of requests in the work queue that have not yet been picked up for processing
`ds-mon-requests-modify-dn`	Timer metric	Modify DN request timer
`ds-mon-requests-modify`	Timer metric	Modify request timer
`ds-mon-requests-patch`	Timer metric	PATCH request timer
`ds-mon-requests-post`	Timer metric	POST request timer
`ds-mon-requests-put`	Timer metric	PUT request timer
`ds-mon-requests-rejected-queue-full`	Summary metric	Summary for operations that have been rejected because the work queue was already at its maximum capacity
`ds-mon-requests-search-base`	Timer metric	Base object search request timer
`ds-mon-requests-search-one`	Timer metric	One level search request timer
`ds-mon-requests-search-sub`	Timer metric	Subtree search request timer
`ds-mon-requests-submitted`	Summary metric	Summary for operations that have been successfully submitted to the work queue
`ds-mon-requests-unbind`	Timer metric	Unbind request timer
`ds-mon-requests-uncategorized`	Timer metric	Uncategorized request timer
`ds-mon-revision`	Directory String	Revision ID in the source repository from which the Directory Server is build
`ds-mon-sent-updates`	Counter metric	Number of replication updates sent by this replica
`ds-mon-server-hostport`	Host port	Host and port of a server
`ds-mon-server-id`	Integer	Server identifier
`ds-mon-server-state`	CSN (Change Sequence Number)	Replication server state
`ds-mon-short-name`	Directory String	Short name of the Directory Server
`ds-mon-ssl-encryption`	Boolean	Whether SSL encryption is used when exchanging messages with this server
`ds-mon-start-time`	Generalized Time	Start date and time for the Directory Server
`ds-mon-status-last-changed`	Generalized Time	Last date and time the replication status of the local replica changed
`ds-mon-status`	Directory String	Replication status of the local replica, can either be "Invalid", "Not connected", "Normal", "Degraded", "Full update", "Bad generation id"
`ds-mon-system-name`	Directory String	Fully qualified domain name of the system where the Directory Server is running
`ds-mon-total-connections`	Integer	Total number of client connections that have been established with the Directory Server since it started
`ds-mon-updates-inbound-queue`	Integer	Number of remote updates received from the replication server but not replayed yet on this replica
`ds-mon-updates-outbound-queue`	Integer	Number of local updates that are waiting to be sent to the replication server once they complete
`ds-mon-updates-totals-per-replay-thread`	Json	JSON array of the number of updates replayed per replay thread
`ds-mon-vendor-name`	Directory String	Vendor name of the Directory Server
`ds-mon-version-qualifier`	Directory String	Version qualifier of the Directory Server
`ds-mon-working-directory`	Filesystem path	Current working directory of the user running the Directory Server

10.3. Prometheus Metrics

This section lists available Prometheus metrics by name, indicating their types as described in "Metric Types".

The labels are listed in braces. For example, the labels in ds_backend_db_cache_misses_internal_nodes{backend,type} are backend and type.

Note

Some ds_jvm_* metrics depend on the JVM version and configuration. In particular, GC-related metrics depend on the garbage collector that the server uses. The GC metric names are unstable, and can change even in a minor JVM release.

Prometheus Metrics by Name

Name	Type	Description
`ds_all_entry_caches_cache_entry_count`	Gauge	Current number of entries held in this cache
`ds_all_entry_caches_cache_misses_count`	Summary	Number of attempts to retrieve an entry that was not held in this cache
`ds_all_entry_caches_cache_misses_total`	Summary	Number of attempts to retrieve an entry that was not held in this cache
`ds_all_entry_caches_cache_total_tries_count`	Summary	Number of attempts to retrieve an entry from this cache
`ds_all_entry_caches_cache_total_tries_total`	Summary	Number of attempts to retrieve an entry from this cache
`ds_backend_db_cache_evict_internal_nodes_count{backend,type}`	Gauge	Number of internal nodes evicted from the database cache
`ds_backend_db_cache_evict_leaf_nodes_count{backend,type}`	Gauge	Number of leaf nodes (data records) evicted from the database cache
`ds_backend_db_cache_misses_internal_nodes{backend,type}`	Gauge	Number of internal nodes requested by btree operations that were not in the database cache
`ds_backend_db_cache_misses_leaf_nodes{backend,type}`	Gauge	Number of leaf nodes (data records) requested by btree operations that were not in the database cache
`ds_backend_db_cache_size_active_bytes{backend,type}`	Gauge	Size of the database cache
`ds_backend_db_cache_size_total_bytes{backend,type}`	Gauge	Maximum size of the database cache
`ds_backend_db_cache_total_tries_internal_nodes{backend,type}`	Gauge	Number of internal nodes requested by btree operations
`ds_backend_db_cache_total_tries_leaf_nodes{backend,type}`	Gauge	Number of leaf nodes (data records) requested by btree operations
`ds_backend_db_checkpoint_count{backend,type}`	Gauge	Number of checkpoints run so far
`ds_backend_db_log_cleaner_file_deletion_count{backend,type}`	Gauge	Number of cleaner file deletions
`ds_backend_db_log_files_open{backend,type}`	Gauge	Number of files currently open in the database file cache
`ds_backend_db_log_files_opened{backend,type}`	Gauge	Number of times a log file has been opened
`ds_backend_db_log_size_active_bytes{backend,type}`	Gauge	Estimate of the amount in bytes of live data in all data files (i.e., the size of the DB, ignoring garbage)
`ds_backend_db_log_size_total_bytes{backend,type}`	Gauge	Size used by all data files on disk
`ds_backend_db_log_utilization_max{backend,type}`	Gauge	Current maximum (upper bound) log utilization as a percentage
`ds_backend_db_log_utilization_min{backend,type}`	Gauge	Current minimum (lower bound) log utilization as a percentage
`ds_backend_degraded_index_count{backend,type}`	Gauge	Number of degraded indexes in the backend
`ds_backend_entry_count{backend,base_dn,dc,type}`	Gauge	Number of subordinate entries of the base DN, including the base DN
`ds_backend_entry_count{backend,base_dn,type}`	Gauge	Number of subordinate entries of the base DN, including the base DN
`ds_backend_filter_use_indexed{backend,type}`	Gauge	Number of indexed searches performed against the backend
`ds_backend_filter_use_start_time_seconds{backend,type}`	Gauge	Time when recording started for statistical information about the simple search filters processed against the backend
`ds_backend_filter_use_unindexed{backend,type}`	Gauge	Number of unindexed searches performed against the backend
`ds_backend_is_private{backend,type}`	Gauge	Whether the base DNs of this backend should be considered public or private
`ds_backend_ttl_entries_deleted_count{backend,type}`	Summary	Summary for entries purged by time-to-live
`ds_backend_ttl_entries_deleted_total{backend,type}`	Summary	Summary for entries purged by time-to-live
`ds_backend_ttl_is_running{backend,type}`	Gauge	Indicates whether time-to-live is in the process of purging expired entries
`ds_backend_ttl_last_run_time_seconds{backend,type}`	Gauge	Last date and time when time-to-live finished purging expired entries
`ds_backend_ttl_queue_size{backend,type}`	Gauge	Number of entries queued for purging by the time-to-live service
`ds_backend_ttl_thread_count{backend,type}`	Gauge	Number of active time-to-live threads
`ds_certificates_certificate_expires_at_seconds{alias,key_manager}`	Gauge	Certificate expiration date and time
`ds_connection_handlers_http_active_connections_count{http_handler}`	Gauge	Number of active client connections
`ds_connection_handlers_http_bytes_read_count{http_handler}`	Summary	Network bytes read summary
`ds_connection_handlers_http_bytes_read_total{http_handler}`	Summary	Network bytes read summary
`ds_connection_handlers_http_bytes_written_count{http_handler}`	Summary	Network bytes written summary
`ds_connection_handlers_http_bytes_written_total{http_handler}`	Summary	Network bytes written summary
`ds_connection_handlers_http_requests_count{http_handler,type}`	Summary	Delete request timer
`ds_connection_handlers_http_requests_count{http_handler,type}`	Summary	GET request timer
`ds_connection_handlers_http_requests_count{http_handler,type}`	Summary	PATCH request timer
`ds_connection_handlers_http_requests_count{http_handler,type}`	Summary	POST request timer
`ds_connection_handlers_http_requests_count{http_handler,type}`	Summary	PUT request timer
`ds_connection_handlers_http_requests_count{http_handler,type}`	Summary	Uncategorized request timer
`ds_connection_handlers_http_requests_failure_count{http_handler,type}`	Summary	Timer for apparently valid requests that failed because the server was not able to process them (associated LDAP result codes: busy (51), unavailable (52), unwilling to perform (53) and other (80); associated HTTP status codes: server error (5xx))
`ds_connection_handlers_http_requests_failure_count{http_handler,type}`	Summary	Timer for requests that could not complete because further action is required (associated HTTP status codes: redirection (3xx))
`ds_connection_handlers_http_requests_failure_count{http_handler,type}`	Summary	Timer for requests that failed because there was a problem while attempting to perform the associated operation (associated LDAP result codes: 1, 2, 12, 15, 16, 17, 18, 19, 20, 21, 23, 34, 35, 36, 37, 38, 39; associated HTTP status codes: client error (4xx) except 401 and 403)
`ds_connection_handlers_http_requests_failure_count{http_handler,type}`	Summary	Timer for requests that failed due to uncategorized reasons
`ds_connection_handlers_http_requests_failure_count{http_handler,type}`	Summary	Timer for requests that failed for security reasons (associated LDAP result codes: 8, 9, 13, 25, 26, 27; associated HTTP status codes: unauthorized (401) and forbidden (403))
`ds_connection_handlers_http_requests_failure_seconds_total{http_handler,type}`	Summary	Timer for apparently valid requests that failed because the server was not able to process them (associated LDAP result codes: busy (51), unavailable (52), unwilling to perform (53) and other (80); associated HTTP status codes: server error (5xx))
`ds_connection_handlers_http_requests_failure_seconds_total{http_handler,type}`	Summary	Timer for requests that could not complete because further action is required (associated HTTP status codes: redirection (3xx))
`ds_connection_handlers_http_requests_failure_seconds_total{http_handler,type}`	Summary	Timer for requests that failed because there was a problem while attempting to perform the associated operation (associated LDAP result codes: 1, 2, 12, 15, 16, 17, 18, 19, 20, 21, 23, 34, 35, 36, 37, 38, 39; associated HTTP status codes: client error (4xx) except 401 and 403)
`ds_connection_handlers_http_requests_failure_seconds_total{http_handler,type}`	Summary	Timer for requests that failed due to uncategorized reasons
`ds_connection_handlers_http_requests_failure_seconds_total{http_handler,type}`	Summary	Timer for requests that failed for security reasons (associated LDAP result codes: 8, 9, 13, 25, 26, 27; associated HTTP status codes: unauthorized (401) and forbidden (403))
`ds_connection_handlers_http_requests_failure_seconds{http_handler,type,quantile}`	Summary	Timer for apparently valid requests that failed because the server was not able to process them (associated LDAP result codes: busy (51), unavailable (52), unwilling to perform (53) and other (80); associated HTTP status codes: server error (5xx))
`ds_connection_handlers_http_requests_failure_seconds{http_handler,type,quantile}`	Summary	Timer for requests that could not complete because further action is required (associated HTTP status codes: redirection (3xx))
`ds_connection_handlers_http_requests_failure_seconds{http_handler,type,quantile}`	Summary	Timer for requests that failed because there was a problem while attempting to perform the associated operation (associated LDAP result codes: 1, 2, 12, 15, 16, 17, 18, 19, 20, 21, 23, 34, 35, 36, 37, 38, 39; associated HTTP status codes: client error (4xx) except 401 and 403)
`ds_connection_handlers_http_requests_failure_seconds{http_handler,type,quantile}`	Summary	Timer for requests that failed due to uncategorized reasons
`ds_connection_handlers_http_requests_failure_seconds{http_handler,type,quantile}`	Summary	Timer for requests that failed for security reasons (associated LDAP result codes: 8, 9, 13, 25, 26, 27; associated HTTP status codes: unauthorized (401) and forbidden (403))
`ds_connection_handlers_http_requests_seconds_total{http_handler,type}`	Summary	Delete request timer
`ds_connection_handlers_http_requests_seconds_total{http_handler,type}`	Summary	GET request timer
`ds_connection_handlers_http_requests_seconds_total{http_handler,type}`	Summary	PATCH request timer
`ds_connection_handlers_http_requests_seconds_total{http_handler,type}`	Summary	POST request timer
`ds_connection_handlers_http_requests_seconds_total{http_handler,type}`	Summary	PUT request timer
`ds_connection_handlers_http_requests_seconds_total{http_handler,type}`	Summary	Uncategorized request timer
`ds_connection_handlers_http_requests_seconds{http_handler,type,quantile}`	Summary	Delete request timer
`ds_connection_handlers_http_requests_seconds{http_handler,type,quantile}`	Summary	GET request timer
`ds_connection_handlers_http_requests_seconds{http_handler,type,quantile}`	Summary	PATCH request timer
`ds_connection_handlers_http_requests_seconds{http_handler,type,quantile}`	Summary	POST request timer
`ds_connection_handlers_http_requests_seconds{http_handler,type,quantile}`	Summary	PUT request timer
`ds_connection_handlers_http_requests_seconds{http_handler,type,quantile}`	Summary	Uncategorized request timer
`ds_connection_handlers_ldap_abandoned_requests{ldap_handler}`	Counter	Total number of abandoned operations since startup
`ds_connection_handlers_ldap_active_connections_count{ldap_handler}`	Gauge	Number of active client connections
`ds_connection_handlers_ldap_active_persistent_searches{ldap_handler}`	Gauge	Number of active persistent searches
`ds_connection_handlers_ldap_bytes_read_count{ldap_handler}`	Summary	Network bytes read summary
`ds_connection_handlers_ldap_bytes_read_total{ldap_handler}`	Summary	Network bytes read summary
`ds_connection_handlers_ldap_bytes_written_count{ldap_handler}`	Summary	Network bytes written summary
`ds_connection_handlers_ldap_bytes_written_total{ldap_handler}`	Summary	Network bytes written summary
`ds_connection_handlers_ldap_connections_count{ldap_handler}`	Summary	Connection summary
`ds_connection_handlers_ldap_connections_total{ldap_handler}`	Summary	Connection summary
`ds_connection_handlers_ldap_requests_count{ldap_handler,scope,type}`	Summary	Base object search request timer
`ds_connection_handlers_ldap_requests_count{ldap_handler,scope,type}`	Summary	One level search request timer
`ds_connection_handlers_ldap_requests_count{ldap_handler,scope,type}`	Summary	Subtree search request timer
`ds_connection_handlers_ldap_requests_count{ldap_handler,type}`	Summary	Abandon request timer
`ds_connection_handlers_ldap_requests_count{ldap_handler,type}`	Summary	Add request timer
`ds_connection_handlers_ldap_requests_count{ldap_handler,type}`	Summary	Bind request timer
`ds_connection_handlers_ldap_requests_count{ldap_handler,type}`	Summary	Compare request timer
`ds_connection_handlers_ldap_requests_count{ldap_handler,type}`	Summary	Delete request timer
`ds_connection_handlers_ldap_requests_count{ldap_handler,type}`	Summary	Extended request timer
`ds_connection_handlers_ldap_requests_count{ldap_handler,type}`	Summary	Modify DN request timer
`ds_connection_handlers_ldap_requests_count{ldap_handler,type}`	Summary	Modify request timer
`ds_connection_handlers_ldap_requests_count{ldap_handler,type}`	Summary	Unbind request timer
`ds_connection_handlers_ldap_requests_count{ldap_handler,type}`	Summary	Uncategorized request timer
`ds_connection_handlers_ldap_requests_failure_count{ldap_handler,type}`	Summary	Timer for apparently valid requests that failed because the server was not able to process them (associated LDAP result codes: busy (51), unavailable (52), unwilling to perform (53) and other (80); associated HTTP status codes: server error (5xx))
`ds_connection_handlers_ldap_requests_failure_count{ldap_handler,type}`	Summary	Timer for requests that failed because the server did not hold the request targeted entry (but was able to provide alternative servers that may) (associated LDAP result code: 10)
`ds_connection_handlers_ldap_requests_failure_count{ldap_handler,type}`	Summary	Timer for requests that failed because there was a problem while attempting to perform the associated operation (associated LDAP result codes: 1, 2, 12, 15, 16, 17, 18, 19, 20, 21, 23, 34, 35, 36, 37, 38, 39; associated HTTP status codes: client error (4xx) except 401 and 403)
`ds_connection_handlers_ldap_requests_failure_count{ldap_handler,type}`	Summary	Timer for requests that failed because they were trying to exceed the resource limits allocated to the associated clients (associated LDAP result codes: time, size and admin limit exceeded (respectively 4, 5 and 11)
`ds_connection_handlers_ldap_requests_failure_count{ldap_handler,type}`	Summary	Timer for requests that failed due to uncategorized reasons
`ds_connection_handlers_ldap_requests_failure_count{ldap_handler,type}`	Summary	Timer for requests that failed for security reasons (associated LDAP result codes: 8, 9, 13, 25, 26, 27; associated HTTP status codes: unauthorized (401) and forbidden (403))
`ds_connection_handlers_ldap_requests_failure_seconds_total{ldap_handler,type}`	Summary	Timer for apparently valid requests that failed because the server was not able to process them (associated LDAP result codes: busy (51), unavailable (52), unwilling to perform (53) and other (80); associated HTTP status codes: server error (5xx))
`ds_connection_handlers_ldap_requests_failure_seconds_total{ldap_handler,type}`	Summary	Timer for requests that failed because the server did not hold the request targeted entry (but was able to provide alternative servers that may) (associated LDAP result code: 10)
`ds_connection_handlers_ldap_requests_failure_seconds_total{ldap_handler,type}`	Summary	Timer for requests that failed because there was a problem while attempting to perform the associated operation (associated LDAP result codes: 1, 2, 12, 15, 16, 17, 18, 19, 20, 21, 23, 34, 35, 36, 37, 38, 39; associated HTTP status codes: client error (4xx) except 401 and 403)
`ds_connection_handlers_ldap_requests_failure_seconds_total{ldap_handler,type}`	Summary	Timer for requests that failed because they were trying to exceed the resource limits allocated to the associated clients (associated LDAP result codes: time, size and admin limit exceeded (respectively 4, 5 and 11)
`ds_connection_handlers_ldap_requests_failure_seconds_total{ldap_handler,type}`	Summary	Timer for requests that failed due to uncategorized reasons
`ds_connection_handlers_ldap_requests_failure_seconds_total{ldap_handler,type}`	Summary	Timer for requests that failed for security reasons (associated LDAP result codes: 8, 9, 13, 25, 26, 27; associated HTTP status codes: unauthorized (401) and forbidden (403))
`ds_connection_handlers_ldap_requests_failure_seconds{ldap_handler,type,quantile}`	Summary	Timer for apparently valid requests that failed because the server was not able to process them (associated LDAP result codes: busy (51), unavailable (52), unwilling to perform (53) and other (80); associated HTTP status codes: server error (5xx))
`ds_connection_handlers_ldap_requests_failure_seconds{ldap_handler,type,quantile}`	Summary	Timer for requests that failed because the server did not hold the request targeted entry (but was able to provide alternative servers that may) (associated LDAP result code: 10)
`ds_connection_handlers_ldap_requests_failure_seconds{ldap_handler,type,quantile}`	Summary	Timer for requests that failed because there was a problem while attempting to perform the associated operation (associated LDAP result codes: 1, 2, 12, 15, 16, 17, 18, 19, 20, 21, 23, 34, 35, 36, 37, 38, 39; associated HTTP status codes: client error (4xx) except 401 and 403)
`ds_connection_handlers_ldap_requests_failure_seconds{ldap_handler,type,quantile}`	Summary	Timer for requests that failed because they were trying to exceed the resource limits allocated to the associated clients (associated LDAP result codes: time, size and admin limit exceeded (respectively 4, 5 and 11)
`ds_connection_handlers_ldap_requests_failure_seconds{ldap_handler,type,quantile}`	Summary	Timer for requests that failed due to uncategorized reasons
`ds_connection_handlers_ldap_requests_failure_seconds{ldap_handler,type,quantile}`	Summary	Timer for requests that failed for security reasons (associated LDAP result codes: 8, 9, 13, 25, 26, 27; associated HTTP status codes: unauthorized (401) and forbidden (403))
`ds_connection_handlers_ldap_requests_seconds_total{ldap_handler,scope,type}`	Summary	Base object search request timer
`ds_connection_handlers_ldap_requests_seconds_total{ldap_handler,scope,type}`	Summary	One level search request timer
`ds_connection_handlers_ldap_requests_seconds_total{ldap_handler,scope,type}`	Summary	Subtree search request timer
`ds_connection_handlers_ldap_requests_seconds_total{ldap_handler,type}`	Summary	Abandon request timer
`ds_connection_handlers_ldap_requests_seconds_total{ldap_handler,type}`	Summary	Add request timer
`ds_connection_handlers_ldap_requests_seconds_total{ldap_handler,type}`	Summary	Bind request timer
`ds_connection_handlers_ldap_requests_seconds_total{ldap_handler,type}`	Summary	Compare request timer
`ds_connection_handlers_ldap_requests_seconds_total{ldap_handler,type}`	Summary	Delete request timer
`ds_connection_handlers_ldap_requests_seconds_total{ldap_handler,type}`	Summary	Extended request timer
`ds_connection_handlers_ldap_requests_seconds_total{ldap_handler,type}`	Summary	Modify DN request timer
`ds_connection_handlers_ldap_requests_seconds_total{ldap_handler,type}`	Summary	Modify request timer
`ds_connection_handlers_ldap_requests_seconds_total{ldap_handler,type}`	Summary	Unbind request timer
`ds_connection_handlers_ldap_requests_seconds_total{ldap_handler,type}`	Summary	Uncategorized request timer
`ds_connection_handlers_ldap_requests_seconds{ldap_handler,scope,type,quantile}`	Summary	Base object search request timer
`ds_connection_handlers_ldap_requests_seconds{ldap_handler,scope,type,quantile}`	Summary	One level search request timer
`ds_connection_handlers_ldap_requests_seconds{ldap_handler,scope,type,quantile}`	Summary	Subtree search request timer
`ds_connection_handlers_ldap_requests_seconds{ldap_handler,type,quantile}`	Summary	Abandon request timer
`ds_connection_handlers_ldap_requests_seconds{ldap_handler,type,quantile}`	Summary	Add request timer
`ds_connection_handlers_ldap_requests_seconds{ldap_handler,type,quantile}`	Summary	Bind request timer
`ds_connection_handlers_ldap_requests_seconds{ldap_handler,type,quantile}`	Summary	Compare request timer
`ds_connection_handlers_ldap_requests_seconds{ldap_handler,type,quantile}`	Summary	Delete request timer
`ds_connection_handlers_ldap_requests_seconds{ldap_handler,type,quantile}`	Summary	Extended request timer
`ds_connection_handlers_ldap_requests_seconds{ldap_handler,type,quantile}`	Summary	Modify DN request timer
`ds_connection_handlers_ldap_requests_seconds{ldap_handler,type,quantile}`	Summary	Modify request timer
`ds_connection_handlers_ldap_requests_seconds{ldap_handler,type,quantile}`	Summary	Unbind request timer
`ds_connection_handlers_ldap_requests_seconds{ldap_handler,type,quantile}`	Summary	Uncategorized request timer
`ds_current_connections`	Gauge	Number of client connections currently established with the Directory Server
`ds_current_time_seconds`	Gauge	Current date and time
`ds_disk_free_space_bytes{disk}`	Gauge	Amount of free disk space
`ds_disk_free_space_full_threshold_bytes{disk}`	Gauge	Effective full disk space threshold
`ds_disk_free_space_low_threshold_bytes{disk}`	Gauge	Effective low disk space threshold
`ds_entry_cache_entry_count{cache}`	Gauge	Current number of entries held in this cache
`ds_entry_cache_max_entry_count{cache}`	Gauge	Maximum number of entries allowed in this cache
`ds_entry_cache_max_size_bytes{cache}`	Gauge	Memory limit for this cache
`ds_entry_cache_misses_count{cache}`	Summary	Number of attempts to retrieve an entry that was not held in this cache
`ds_entry_cache_misses_total{cache}`	Summary	Number of attempts to retrieve an entry that was not held in this cache
`ds_entry_cache_total_tries_count{cache}`	Summary	Number of attempts to retrieve an entry from this cache
`ds_entry_cache_total_tries_total{cache}`	Summary	Number of attempts to retrieve an entry from this cache
`ds_health_status_alive`	Gauge	Indicates whether the server is alive
`ds_health_status_healthy`	Gauge	Indicates whether the server is able to handle requests
`ds_jvm_available_cpus`	Gauge	Number of processors available to the Java virtual machine
`ds_jvm_classes_loaded`	Gauge	Number of classes loaded since the Java virtual machine started
`ds_jvm_classes_unloaded`	Gauge	Number of classes unloaded since the Java virtual machine started
`ds_jvm_garbage_collector_ps_mark_sweep_count`	Gauge	Number of collections performed by the "parallel scavenge mark sweep" garbage collection algorithm
`ds_jvm_garbage_collector_ps_mark_sweep_time_seconds`	Gauge	Approximate accumulated time taken by the "parallel scavenge mark sweep" garbage collection algorithm
`ds_jvm_garbage_collector_ps_scavenge_count`	Gauge	Number of collections performed by the "parallel scavenge" garbage collection algorithm
`ds_jvm_garbage_collector_ps_scavenge_time_seconds`	Gauge	Approximate accumulated time taken by the "parallel scavenge" garbage collection algorithm
`ds_jvm_memory_heap_init_bytes`	Gauge	Amount of heap memory that the Java virtual machine initially requested from the operating system
`ds_jvm_memory_heap_max_bytes`	Gauge	Maximum amount of heap memory that the Java virtual machine will attempt to use
`ds_jvm_memory_heap_reserved_bytes`	Gauge	Amount of heap memory that is committed for the Java virtual machine to use
`ds_jvm_memory_heap_used_bytes`	Gauge	Amount of heap memory used by the Java virtual machine
`ds_jvm_memory_init_bytes`	Gauge	Amount of memory that the Java virtual machine initially requested from the operating system
`ds_jvm_memory_max_bytes`	Gauge	Maximum amount of memory that the Java virtual machine will attempt to use
`ds_jvm_memory_non_heap_init_bytes`	Gauge	Amount of non-heap memory that the Java virtual machine initially requested from the operating system
`ds_jvm_memory_non_heap_max_bytes`	Gauge	Maximum amount of non-heap memory that the Java virtual machine will attempt to use
`ds_jvm_memory_non_heap_reserved_bytes`	Gauge	Amount of non-heap memory that is committed for the Java virtual machine to use
`ds_jvm_memory_non_heap_used_bytes`	Gauge	Amount of non-heap memory used by the Java virtual machine
`ds_jvm_memory_pools_code_cache_init_bytes`	Gauge	Amount of "code cache" memory that the Java virtual machine initially requested from the operating system
`ds_jvm_memory_pools_code_cache_max_bytes`	Gauge	Maximum amount of "code cache" memory that the Java virtual machine will attempt to use
`ds_jvm_memory_pools_code_cache_reserved_bytes`	Gauge	Amount of "code cache" memory that is committed for the Java virtual machine to use
`ds_jvm_memory_pools_code_cache_used_bytes`	Gauge	Amount of "code cache" memory used by the Java virtual machine
`ds_jvm_memory_pools_compressed_class_space_init_bytes`	Gauge	Amount of "compressed class space" memory that the Java virtual machine initially requested from the operating system
`ds_jvm_memory_pools_compressed_class_space_max_bytes`	Gauge	Maximum amount of "compressed class space" memory that the Java virtual machine will attempt to use
`ds_jvm_memory_pools_compressed_class_space_reserved_bytes`	Gauge	Amount of "compressed class space" memory that is committed for the Java virtual machine to use
`ds_jvm_memory_pools_compressed_class_space_used_bytes`	Gauge	Amount of "compressed class space" memory used by the Java virtual machine
`ds_jvm_memory_pools_metaspace_init_bytes`	Gauge	Amount of "metaspace" memory that the Java virtual machine initially requested from the operating system
`ds_jvm_memory_pools_metaspace_max_bytes`	Gauge	Maximum amount of "metaspace" memory that the Java virtual machine will attempt to use
`ds_jvm_memory_pools_metaspace_reserved_bytes`	Gauge	Amount of "metaspace" memory that is committed for the Java virtual machine to use
`ds_jvm_memory_pools_metaspace_used_bytes`	Gauge	Amount of "metaspace" memory used by the Java virtual machine
`ds_jvm_memory_pools_ps_eden_space_init_bytes`	Gauge	Amount of "parallel scavenge eden space" memory that the Java virtual machine initially requested from the operating system
`ds_jvm_memory_pools_ps_eden_space_max_bytes`	Gauge	Maximum amount of "parallel scavenge eden space" memory that the Java virtual machine will attempt to use
`ds_jvm_memory_pools_ps_eden_space_reserved_bytes`	Gauge	Amount of "parallel scavenge eden space" memory that is committed for the Java virtual machine to use
`ds_jvm_memory_pools_ps_eden_space_used_after_gc_bytes`	Gauge	Amount of "parallel scavenge eden space" memory after the last time garbage collection recycled unused objects in this memory pool
`ds_jvm_memory_pools_ps_eden_space_used_bytes`	Gauge	Amount of "parallel scavenge eden space" memory used by the Java virtual machine
`ds_jvm_memory_pools_ps_old_gen_init_bytes`	Gauge	Amount of "parallel scavenge old generation" memory that the Java virtual machine initially requested from the operating system
`ds_jvm_memory_pools_ps_old_gen_max_bytes`	Gauge	Maximum amount of "parallel scavenge old generation" memory that the Java virtual machine will attempt to use
`ds_jvm_memory_pools_ps_old_gen_reserved_bytes`	Gauge	Amount of "parallel scavenge old generation" memory that is committed for the Java virtual machine to use
`ds_jvm_memory_pools_ps_old_gen_used_after_gc_bytes`	Gauge	Amount of "parallel scavenge old generation" memory after the last time garbage collection recycled unused objects in this memory pool
`ds_jvm_memory_pools_ps_old_gen_used_bytes`	Gauge	Amount of "parallel scavenge old generation" memory used by the Java virtual machine
`ds_jvm_memory_pools_ps_survivor_space_init_bytes`	Gauge	Amount of "parallel scavenge survivor space" memory that the Java virtual machine initially requested from the operating system
`ds_jvm_memory_pools_ps_survivor_space_max_bytes`	Gauge	Maximum amount of "parallel scavenge survivor space" memory that the Java virtual machine will attempt to use
`ds_jvm_memory_pools_ps_survivor_space_reserved_bytes`	Gauge	Amount of "parallel scavenge survivor space" memory that is committed for the Java virtual machine to use
`ds_jvm_memory_pools_ps_survivor_space_used_after_gc_bytes`	Gauge	Amount of "parallel scavenge survivor space" memory after the last time garbage collection recycled unused objects in this memory pool
`ds_jvm_memory_pools_ps_survivor_space_used_bytes`	Gauge	Amount of "parallel scavenge survivor space" memory used by the Java virtual machine
`ds_jvm_memory_reserved_bytes`	Gauge	Amount of memory that is committed for the Java virtual machine to use
`ds_jvm_memory_used_bytes`	Gauge	Amount of memory used by the Java virtual machine
`ds_jvm_threads_blocked_count`	Gauge	Number of threads in the BLOCKED state
`ds_jvm_threads_count`	Gauge	Number of live threads including both daemon and non-daemon threads
`ds_jvm_threads_daemon_count`	Gauge	Number of live daemon threads
`ds_jvm_threads_deadlock_count`	Gauge	Number of deadlocked threads
`ds_jvm_threads_new_count`	Gauge	Number of threads in the NEW state
`ds_jvm_threads_runnable_count`	Gauge	Number of threads in the RUNNABLE state
`ds_jvm_threads_terminated_count`	Gauge	Number of threads in the TERMINATED state
`ds_jvm_threads_timed_waiting_count`	Gauge	Number of threads in the TIMED_WAITING state
`ds_jvm_threads_waiting_count`	Gauge	Number of threads in the WAITING state
`ds_max_connections`	Gauge	Maximum number of simultaneous client connections that have been established with the Directory Server
`ds_replication_changelog_connected_changelogs_current_receive_window{changelog_id,domain_name,dc}`	Gauge	Current replication window size for receiving messages, indicating the number of replication messages a remote server can send before waiting on acknowledgement from this server. This does not depend on the TCP window size
`ds_replication_changelog_connected_changelogs_current_receive_window{changelog_id,domain_name}`	Gauge	Current replication window size for receiving messages, indicating the number of replication messages a remote server can send before waiting on acknowledgement from this server. This does not depend on the TCP window size
`ds_replication_changelog_connected_changelogs_current_send_window{changelog_id,domain_name,dc}`	Gauge	Current replication window size for sending messages, indicating the number of replication messages this server can send before waiting on acknowledgement from the receiving server. This does not depend on the TCP window size
`ds_replication_changelog_connected_changelogs_current_send_window{changelog_id,domain_name}`	Gauge	Current replication window size for sending messages, indicating the number of replication messages this server can send before waiting on acknowledgement from the receiving server. This does not depend on the TCP window size
`ds_replication_changelog_connected_changelogs_domain_generation_id{changelog_id,domain_name,dc}`	Gauge	Replication domain generation identifier
`ds_replication_changelog_connected_changelogs_domain_generation_id{changelog_id,domain_name}`	Gauge	Replication domain generation identifier
`ds_replication_changelog_connected_changelogs_max_receive_window{changelog_id,domain_name,dc}`	Gauge	Maximum replication window size for receiving messages, indicating the number of replication messages a remote server can send before waiting on acknowledgement from this server. This does not depend on the TCP window size
`ds_replication_changelog_connected_changelogs_max_receive_window{changelog_id,domain_name}`	Gauge	Maximum replication window size for receiving messages, indicating the number of replication messages a remote server can send before waiting on acknowledgement from this server. This does not depend on the TCP window size
`ds_replication_changelog_connected_changelogs_max_send_window{changelog_id,domain_name,dc}`	Gauge	Maximum replication window size for sending messages, indicating the number of replication messages this server can send before waiting on acknowledgement from the receiving server. This does not depend on the TCP window size
`ds_replication_changelog_connected_changelogs_max_send_window{changelog_id,domain_name}`	Gauge	Maximum replication window size for sending messages, indicating the number of replication messages this server can send before waiting on acknowledgement from the receiving server. This does not depend on the TCP window size
`ds_replication_changelog_connected_changelogs_missing_changes{changelog_id,domain_name,dc}`	Gauge	Missing changes for replication
`ds_replication_changelog_connected_changelogs_missing_changes{changelog_id,domain_name}`	Gauge	Missing changes for replication
`ds_replication_changelog_connected_changelogs_ssl_encryption{changelog_id,domain_name,dc}`	Gauge	Whether SSL encryption is used when exchanging messages with this server
`ds_replication_changelog_connected_changelogs_ssl_encryption{changelog_id,domain_name}`	Gauge	Whether SSL encryption is used when exchanging messages with this server
`ds_replication_changelog_connected_replicas_approx_oldest_change_not_synchronized_seconds{domain_name,dc,server_id}`	Gauge	Approximate date and time of the oldest change not yet synchronized
`ds_replication_changelog_connected_replicas_approx_oldest_change_not_synchronized_seconds{domain_name,server_id}`	Gauge	Approximate date and time of the oldest change not yet synchronized
`ds_replication_changelog_connected_replicas_approximate_delay_seconds{domain_name,dc,server_id}`	Gauge	Approximate delay between this server and the connected replica
`ds_replication_changelog_connected_replicas_approximate_delay_seconds{domain_name,server_id}`	Gauge	Approximate delay between this server and the connected replica
`ds_replication_changelog_connected_replicas_current_receive_window{domain_name,dc,server_id}`	Gauge	Current replication window size for receiving messages, indicating the number of replication messages a remote server can send before waiting on acknowledgement from this server. This does not depend on the TCP window size
`ds_replication_changelog_connected_replicas_current_receive_window{domain_name,server_id}`	Gauge	Current replication window size for receiving messages, indicating the number of replication messages a remote server can send before waiting on acknowledgement from this server. This does not depend on the TCP window size
`ds_replication_changelog_connected_replicas_current_send_window{domain_name,dc,server_id}`	Gauge	Current replication window size for sending messages, indicating the number of replication messages this server can send before waiting on acknowledgement from the receiving server. This does not depend on the TCP window size
`ds_replication_changelog_connected_replicas_current_send_window{domain_name,server_id}`	Gauge	Current replication window size for sending messages, indicating the number of replication messages this server can send before waiting on acknowledgement from the receiving server. This does not depend on the TCP window size
`ds_replication_changelog_connected_replicas_domain_generation_id{domain_name,dc,server_id}`	Gauge	Replication domain generation identifier
`ds_replication_changelog_connected_replicas_domain_generation_id{domain_name,server_id}`	Gauge	Replication domain generation identifier
`ds_replication_changelog_connected_replicas_max_receive_window{domain_name,dc,server_id}`	Gauge	Maximum replication window size for receiving messages, indicating the number of replication messages a remote server can send before waiting on acknowledgement from this server. This does not depend on the TCP window size
`ds_replication_changelog_connected_replicas_max_receive_window{domain_name,server_id}`	Gauge	Maximum replication window size for receiving messages, indicating the number of replication messages a remote server can send before waiting on acknowledgement from this server. This does not depend on the TCP window size
`ds_replication_changelog_connected_replicas_max_send_window{domain_name,dc,server_id}`	Gauge	Maximum replication window size for sending messages, indicating the number of replication messages this server can send before waiting on acknowledgement from the receiving server. This does not depend on the TCP window size
`ds_replication_changelog_connected_replicas_max_send_window{domain_name,server_id}`	Gauge	Maximum replication window size for sending messages, indicating the number of replication messages this server can send before waiting on acknowledgement from the receiving server. This does not depend on the TCP window size
`ds_replication_changelog_connected_replicas_missing_changes{domain_name,dc,server_id}`	Gauge	Missing changes for replication
`ds_replication_changelog_connected_replicas_missing_changes{domain_name,server_id}`	Gauge	Missing changes for replication
`ds_replication_changelog_connected_replicas_ssl_encryption{domain_name,dc,server_id}`	Gauge	Whether SSL encryption is used when exchanging messages with this server
`ds_replication_changelog_connected_replicas_ssl_encryption{domain_name,server_id}`	Gauge	Whether SSL encryption is used when exchanging messages with this server
`ds_replication_changelog_domain_generation_id{domain_name,dc}`	Gauge	Replication domain generation identifier
`ds_replication_changelog_domain_generation_id{domain_name}`	Gauge	Replication domain generation identifier
`ds_replication_changelog_missing_changes{domain_name,dc}`	Gauge	Missing changes for replication
`ds_replication_changelog_missing_changes{domain_name}`	Gauge	Missing changes for replication
`ds_replication_changelog_newest_change_number`	Gauge	Newest change number present in the change number index database
`ds_replication_changelog_oldest_change_number`	Gauge	Oldest change number present in the change number index database
`ds_replication_changelog_replica_dbs_newest_csn_timestamp_seconds{domain_name,dc,server_id}`	Gauge	Timestamp of the newest CSN present in the replica database
`ds_replication_changelog_replica_dbs_oldest_csn_timestamp_seconds{domain_name,dc,server_id}`	Gauge	Timestamp of the oldest CSN present in the replica database
`ds_replication_replica_current_receive_window`	Gauge	Current replication window size for receiving messages, indicating the number of replication messages a remote server can send before waiting on acknowledgement from this server. This does not depend on the TCP window size
`ds_replication_replica_current_send_window`	Gauge	Current replication window size for sending messages, indicating the number of replication messages this server can send before waiting on acknowledgement from the receiving server. This does not depend on the TCP window size
`ds_replication_replica_domain_generation_id`	Gauge	Replication domain generation identifier
`ds_replication_replica_entries_awaiting_updates_count`	Gauge	Number of entries for which an update operation has been received but not replayed yet by this replica
`ds_replication_replica_lost_connections`	Gauge	Number of times the replica lost its connection to the replication server
`ds_replication_replica_max_receive_window`	Gauge	Maximum replication window size for receiving messages, indicating the number of replication messages a remote server can send before waiting on acknowledgement from this server. This does not depend on the TCP window size
`ds_replication_replica_max_send_window`	Gauge	Maximum replication window size for sending messages, indicating the number of replication messages this server can send before waiting on acknowledgement from the receiving server. This does not depend on the TCP window size
`ds_replication_replica_remote_replicas_current_delay_seconds{domain_name,dc,remote_server_id,server_id}`	Gauge	Current local delay in replaying replicated operations
`ds_replication_replica_remote_replicas_replayed_updates_count{domain_name,dc,remote_server_id,server_id}`	Summary	Timer for updates that have been replayed on this replica
`ds_replication_replica_remote_replicas_replayed_updates_seconds_total{domain_name,dc,remote_server_id,server_id}`	Summary	Timer for updates that have been replayed on this replica
`ds_replication_replica_remote_replicas_replayed_updates_seconds{domain_name,dc,remote_server_id,server_id,quantile}`	Summary	Timer for updates that have been replayed on this replica
`ds_replication_replica_replayed_updates_conflicts_resolved`	Counter	Number of updates replayed on this replica for which replication naming conflicts have been resolved
`ds_replication_replica_replayed_updates_conflicts_unresolved`	Counter	Number of updates replayed on this replica for which replication naming conflicts have not been resolved
`ds_replication_replica_replayed_updates_count`	Summary	Timer for updates that have been replayed on this replica
`ds_replication_replica_replayed_updates_seconds_total`	Summary	Timer for updates that have been replayed on this replica
`ds_replication_replica_replayed_updates_seconds{quantile}`	Summary	Timer for updates that have been replayed on this replica
`ds_replication_replica_sent_updates`	Counter	Number of replication updates sent by this replica
`ds_replication_replica_ssl_encryption`	Gauge	Whether SSL encryption is used when exchanging messages with this server
`ds_replication_replica_status_last_changed_seconds`	Gauge	Last date and time the replication status of the local replica changed
`ds_replication_replica_updates_inbound_queue`	Gauge	Number of remote updates received from the replication server but not replayed yet on this replica
`ds_replication_replica_updates_outbound_queue`	Gauge	Number of local updates that are waiting to be sent to the replication server once they complete
`ds_start_time_seconds`	Gauge	Start date and time for the Directory Server
`ds_total_connections`	Gauge	Total number of client connections that have been established with the Directory Server since it started
`ds_work_queue_requests_in_queue`	Gauge	Number of requests in the work queue that have not yet been picked up for processing
`ds_work_queue_requests_rejected_queue_full_count`	Summary	Summary for operations that have been rejected because the work queue was already at its maximum capacity
`ds_work_queue_requests_rejected_queue_full_total`	Summary	Summary for operations that have been rejected because the work queue was already at its maximum capacity
`ds_work_queue_requests_submitted_count`	Summary	Summary for operations that have been successfully submitted to the work queue
`ds_work_queue_requests_submitted_total`	Summary	Summary for operations that have been successfully submitted to the work queue

Part 11. Tools Reference

Find the bundled tools where you installed the server, as indicated in "Server Command-Line Tools" in the Administration Guide.

Chapter 11.1. addrate — measure add and delete throughput and response time

11.1.1. Synopsis

addrate {options} template-file-path

11.1.2. Description

This utility can be used to measure add and optionally delete throughput and response time of a directory server using user-defined entries. The {template-file-path} argument identifies a template file that has the same form as a template file for the makeldif command.

Examples:

This example adds entries and randomly deletes them while the number of entries added is greater than 10,000:

addrate -p 1389 -f -c 10 -C random -s 10000 addrate.template

This example adds entries and starts to delete them in the same order if their age is greater than a certain time:

addrate -p 1389 -f -c 10 -C fifo -a 2 addrate.template

For details about the template file, see makeldif.template.

When you do not use the -f option to keep connections open and rebind on the connections, the tool can exhaust its available ports, causing the tool to crash. You can work around this problem on test systems by changing TCP settings on the system.

For example, on Linux systems, set the following parameters in the /etc/sysctl.conf file:

net.ipv4.tcp_fin_timeout = 30
net.ipv4.tcp_tw_recycle = 1
net.ipv4.tcp_tw_reuse = 1

The parameter net.ipv4.tcp_fin_timeout sets the length of time in seconds to wait for a final FIN packet before forcing a close of the socket. The default is 60 (seconds).

The parameter net.ipv4.tcp_tw_recycle enables fast recycling of TIME_WAIT sockets. The default is 0 (false). Enabling this can cause Network Address Translation (NAT) issues.

The parameter net.ipv4.tcp_tw_reuse enables reuse of TIME_WAIT sockets for new connections. The default is 0 (false).

These settings are recommended only for testing, and not for production systems.

After making the changes to /etc/sysctl.conf, reload the configuration with the sysctl command:

# sysctl -p

11.1.3. Options

The addrate command takes the following options:

Command options:

-a | --deleteAgeThreshold {seconds}

Specifies the age at which added entries will become candidates for deletion.

-B | --warmUpDuration {warmUpDuration}

Warm up duration in seconds.

Default: 0

-c | --numConnections {numConnections}

Number of connections.

Default: 1

-C | --deleteMode {fifo | random | off}

The algorithm used for selecting entries to be deleted which must be one of "fifo", "random", or "off".

Default: FIFO

-d | --maxDuration {maxDuration}

Maximum duration in seconds, 0 for unlimited.

Default: 0

-e | --percentile {percentile}

Calculate max response time for a percentile of operations.

-f | --keepConnectionsOpen

Keep connections open.

Default: false

-F | --noRebind

Keep connections open and do not rebind.

Default: false

-g | --constant {name=value}

A constant that overrides the value set in the template file.

-i | --statInterval {statInterval}

Display results each specified number of seconds.

Default: 5

-m | --maxIterations {maxIterations}

Max iterations, 0 for unlimited.

Default: 0

-M | --targetThroughput {targetThroughput}

Target average throughput to achieve.

Default: 0

-n | --noPurge

Disable the purge phase when the tool stops.

Default: false

-r | --resourcePath {path}

Path to look for template resources (e.g. data files).

The utility looks for resources in the following locations in this order:

The current directory where the command is run.
The resource path directory.
The built-in files.

-R | --randomSeed {seed}

The seed to use for initializing the random number generator.

Default: 0

-s | --deleteSizeThreshold {count}

Specifies the number of entries to be added before deletion begins.

Default: 10000

-S | --scriptFriendly

Use script-friendly mode.

Default: false

-t | --numConcurrentRequests {numConcurrentRequests}

Number of concurrent requests per connection.

Default: 1

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default:

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server port number.

-q | --useStartTls

Use StartTLS to secure communication with the server.

Default: false

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

-Z | --useSsl

Use SSL for secure communication with the server.

Default: false

Utility input/output options:

--no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-v | --verbose

Use verbose mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.1.4. Exit Codes

0: The command completed successfully.
80: The command could not complete due to an input/output error.
89: An error occurred while parsing the command-line arguments.

11.1.5. Examples

The following example adds entries, and then randomly deletes them when more than 10,000 entries have been added:

$ addrate -p 1389 -D "cn=Directory Manager" -w password \
-f -c 10 -C random -s 10000 /path/to/opendj/config/MakeLDIF/addrate.template
--------------------------------------------------------------------------------------
|     Throughput    |                 Response Time                |    Additional   |
|    (ops/second)   |                (milliseconds)                |    Statistics   |
|   recent  average |   recent  average    99.9%   99.99%  99.999% |  err/sec   Add% |
--------------------------------------------------------------------------------------
|    275.3    275.3 |   12.057   12.057   102.76   113.25   113.25 |      0.0 100.00 |
|    329.1    302.2 |   10.181   11.036    93.85   113.25   113.25 |      0.0 100.00 |
|    339.2    314.5 |    9.719   10.563   113.25   122.16   122.16 |      0.0 100.00 |
|    365.6    327.3 |    7.616    9.740   105.91   120.59   122.16 |      0.0 100.00 |
|    385.8    339.0 |    7.312    9.187   102.76   120.59   122.16 |      0.0 100.00 |
|    366.8    343.6 |    7.776    8.936    99.61   120.59   122.16 |      0.0  91.44 |
|    337.2    342.7 |   10.746    9.191   119.01   505.41   509.61 |      0.0  49.61 |
^C|    372.8    343.8 |    7.662    9.130   119.01   505.41   509.61 |      0.0  50.30 |
Purge phase...

The following example also adds entries, and then deletes them in the order they were added after they are 10 seconds old:

$ addrate -p 1389 -D "cn=Directory Manager" -w password -f -c 10 -C fifo -a 10 \
 /path/to/opendj/config/MakeLDIF/addrate.template
--------------------------------------------------------------------------------------
|     Throughput    |                 Response Time                |    Additional   |
|    (ops/second)   |                (milliseconds)                |    Statistics   |
|   recent  average |   recent  average    99.9%   99.99%  99.999% |  err/sec   Add% |
--------------------------------------------------------------------------------------
|    377.8    377.8 |    7.258    7.258    18.87    20.71    20.71 |      0.0 100.00 |
|    393.2    385.5 |    7.069    7.161    18.09    23.20    23.20 |      0.0 100.00 |
|    387.8    386.3 |    7.226    7.183    28.18    36.44    37.49 |      0.0  50.05 |
|    396.8    388.9 |    6.957    7.125    23.20    36.44    37.49 |      0.0  50.18 |
|    400.6    391.2 |    6.906    7.080    19.27    36.44    37.49 |      0.0  49.73 |
^C|    397.6    391.4 |    7.083    7.080    19.27    36.44    37.49 |      0.0  50.00 |
Purge phase...

Chapter 11.2. authrate — measure bind throughput and response time

11.2.1. Synopsis

authrate {options} [filter template string] [attributes ...]

11.2.2. Description

This utility can be used to measure bind throughput and response time of a directory service using user-defined bind or search-then-bind operations.

Template strings may be used in the bind DN option as well as the authid and authzid SASL bind options. A search operation may be used to retrieve the bind DN by specifying the base DN and a filter. The retrieved entry DN will be appended as the last argument in the argument list when evaluating template strings.

Example (bind only):

authrate -p 1389 -D 'uid=user.{},ou=people,dc=example,dc=com' \

-w password -f -c 10 -g 'rand(0,2000)'

Example (search then bind):

authrate -p 1389 -D '{2}' -w password -f -c 10 \

-b 'ou=people,dc=example,dc=com' -s one -g 'rand(0,2000)' '(uid=user.{1})'

Before trying the example, import 2000 randomly generated users.

When you do not use the -f option to keep connections open and rebind on the connections, the tool can exhaust its available ports, causing the tool to crash. You can work around this problem on test systems by changing TCP settings on the system.

For example, on Linux systems, set the following parameters in the /etc/sysctl.conf file:

net.ipv4.tcp_fin_timeout = 30
net.ipv4.tcp_tw_recycle = 1
net.ipv4.tcp_tw_reuse = 1

The parameter net.ipv4.tcp_fin_timeout sets the length of time in seconds to wait for a final FIN packet before forcing a close of the socket. The default is 60 (seconds).

The parameter net.ipv4.tcp_tw_recycle enables fast recycling of TIME_WAIT sockets. The default is 0 (false). Enabling this can cause Network Address Translation (NAT) issues.

The parameter net.ipv4.tcp_tw_reuse enables reuse of TIME_WAIT sockets for new connections. The default is 0 (false).

These settings are recommended only for testing, and not for production systems.

After making the changes to /etc/sysctl.conf, reload the configuration with the sysctl command:

# sysctl -p

11.2.3. Options

The authrate command takes the following options:

Command options:

-a | --dereferencePolicy {dereferencePolicy}

Alias dereference policy ('never', 'always', 'search', or 'find').

Default: never

-b | --baseDn {baseDN}

Base DN template string.

-B | --warmUpDuration {warmUpDuration}

Warm up duration in seconds.

Default: 0

-c | --numConnections {numConnections}

Number of connections.

Default: 1

-d | --maxDuration {maxDuration}

Maximum duration in seconds, 0 for unlimited.

Default: 0

-e | --percentile {percentile}

Calculate max response time for a percentile of operations.

-f | --keepConnectionsOpen

Keep connections open.

Default: false

-g | --argument {generator function or static string}

Argument used to evaluate the template strings in program parameters (ie. Base DN, Search Filter). The set of all arguments provided form the argument list in order. Besides static string arguments, they can be generated per iteration with the following functions:

"inc({filename})" Consecutive, incremental line from file

"inc({min},{max})" Consecutive, incremental number

"rand({filename})" Random line from file

"rand({min},{max})" Random number

"randstr({length},_charSet_)" Random string of specified length and optionally from characters in the charSet string. A range of character can be specified with [start-end] charSet notation. If no charSet is specified, the default charSet of [A-Z][a-z][0-9] will be used.

-i | --statInterval {statInterval}

Display results each specified number of seconds.

Default: 5

-I | --invalidPassword {invalidPassword}

Calculate max response time for a percentile of operations.

Default: 0

-m | --maxIterations {maxIterations}

Max iterations, 0 for unlimited.

Default: 0

-M | --targetThroughput {targetThroughput}

Target average throughput to achieve.

Default: 0

-s | --searchScope {searchScope}

Search scope ('base', 'one', 'sub', or 'subordinates'). Note: 'subordinates' is an LDAP extension that might not work with all LDAP servers.

Default: sub

-S | --scriptFriendly

Use script-friendly mode.

Default: false

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default:

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server port number.

-q | --useStartTls

Use StartTLS to secure communication with the server.

Default: false

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

-Z | --useSsl

Use SSL for secure communication with the server.

Default: false

Utility input/output options:

-n | --no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-v | --verbose

Use verbose mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.2.4. Exit Codes

0: The command completed successfully.
89: An error occurred while parsing the command-line arguments.

11.2.5. Examples

The following example demonstrates measuring simple bind performance:

$ authrate -p 1389 -D "uid=user.{},ou=people,dc=example,dc=com" -g "rand(0,2000)" -w password -c 10 -f
-------------------------------------------------------------------------------
|     Throughput    |                 Response Time                |          |
|    (ops/second)   |                (milliseconds)                |          |
|   recent  average |   recent  average    99.9%   99.99%  99.999% |  err/sec |
-------------------------------------------------------------------------------
|  26046.6  26046.6 |    0.377    0.377    10.62    20.71    36.44 |      0.0 |
|  45757.6  35902.1 |    0.214    0.273     7.21    15.93    26.08 |      0.0 |
|  47457.8  39754.0 |    0.206    0.247     5.70    13.57    25.30 |      0.0 |
|  47715.2  41744.3 |    0.205    0.235     4.98    12.32    24.77 |      0.0 |
|  48203.0  43036.0 |    0.203    0.228     4.59    11.80    20.84 |      0.0 |
|  49363.0  44090.5 |    0.198    0.222     4.33    11.27    20.71 |      0.0 |
^C

All user password values are password for this example.

Chapter 11.3. backendstat — gather OpenDJ backend debugging information

11.3.1. Synopsis

backendstat {subcommand} {options}

11.3.2. Description

This utility can be used to debug a backend.

11.3.3. Options

The backendstat command takes the following options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.3.4. Subcommands

The backendstat command supports the following subcommands:

11.3.4.1. backendstat dump-index

Dump records from an index, decoding keys and values. Depending on index size, this subcommand can generate lots of output.

11.3.4.1.1. Options

The backendstat dump-index command takes the following options:

-n | --backendId {backendName}

The backend ID of the backend.

-b | --baseDn {baseDN}

The base DN within the backend.

-i | --indexName {indexName}

The name of the index.

-q | --statsOnly

Do not display backend data, just statistics.

Default: false

-K | --maxKeyValue {maxKeyValue}

Only show records with keys that should be ordered before the provided value using the comparator for the database container.

-k | --minKeyValue {minKeyValue}

Only show records with keys that should be ordered after the provided value using the comparator for the database container.

-X | --maxHexKeyValue {maxKeyValue}

Only show records with keys that should be ordered before the provided value using the comparator for the database container.

-x | --minHexKeyValue {minKeyValue}

Only show records with keys that should be ordered after the provided value using the comparator for the database container.

-S | --maxDataSize {maxDataSize}

Only show records whose data is no larger than the provided value.

Default: -1

-s | --minDataSize {minDataSize}

Only show records whose data is no smaller than the provided value.

Default: -1

-p | --skipDecode

Do not try to decode backend data to their appropriate types.

Default: false

11.3.4.2. backendstat dump-raw-db

Dump the raw records in hexadecimal format for a low-level database within the pluggable backend's storage engine. Depending on index size, this subcommand can generate lots of output.

11.3.4.2.1. Options

The backendstat dump-raw-db command takes the following options:

-n | --backendId {backendName}

The backend ID of the backend.

-d | --dbName {databaseName}

The raw database name.

-q | --statsOnly

Do not display backend data, just statistics.

Default: false

-K | --maxKeyValue {maxKeyValue}

Only show records with keys that should be ordered before the provided value using the comparator for the database container.

-k | --minKeyValue {minKeyValue}

Only show records with keys that should be ordered after the provided value using the comparator for the database container.

-X | --maxHexKeyValue {maxKeyValue}

Only show records with keys that should be ordered before the provided value using the comparator for the database container.

-x | --minHexKeyValue {minKeyValue}

Only show records with keys that should be ordered after the provided value using the comparator for the database container.

-S | --maxDataSize {maxDataSize}

Only show records whose data is no larger than the provided value.

Default: -1

-s | --minDataSize {minDataSize}

Only show records whose data is no smaller than the provided value.

Default: -1

-l | --singleLine

Write hexadecimal data on a single line instead of pretty format.

Default: false

11.3.4.3. backendstat list-backends

List the pluggable backends.

11.3.4.4. backendstat list-base-dns

List the base DNs in a backend.

11.3.4.4.1. Options

The backendstat list-base-dns command takes the following options:

-n | --backendId {backendName}: The backend ID of the backend.

11.3.4.5. backendstat list-indexes

List the indexes associated with a pluggable backend. This subcommand may take a long time to complete depending on the size of the backend.

11.3.4.5.1. Options

The backendstat list-indexes command takes the following options:

-n | --backendId {backendName}: The backend ID of the backend.
-b | --baseDn {baseDN}: The base DN within the backend.

11.3.4.6. backendstat list-raw-dbs

List the low-level databases within a pluggable backend's storage engine. This subcommand may take a long time to complete depending on the size of the backend.

11.3.4.6.1. Options

The backendstat list-raw-dbs command takes the following options:

-n | --backendId {backendName}

The backend ID of the backend.

-u | --useSiUnits

Uses SI Units for printing sizes.

Default: false

11.3.4.7. backendstat show-index-status

Shows the status of indexes for a backend base DN. This subcommand can take a long time to complete, as it reads all indexes for all backends.

When you run the show-index-status subcommand, the result is a table, followed by a "Total", which is the total number of indexes, followed by a list of indexes with "Over index-entry-limit keys" to show the values for which the number of entries exceeded the index entry limit. The table has the following columns.

Index Name

Name of the index, which takes the form attr.type for attribute indexes, and vlv.name for VLV indexes. Some indexes are for the directory server's internal use.

Example: givenName.caseIgnoreSubstringsMatch:6

Raw DB Name

The internal name of the database within the storage which the directory server is using for the index.

Example: /dc=example,dc=com/givenName.caseIgnoreSubstringsMatch:6

Index Valid

This is true for valid indexes. If this is false, the index might be degraded. Verify the index, and rebuild the index if necessary.

Record Count

Number of indexed keys. Use the backendstat dump-tree command to see how many entry IDs correspond to each key.

Over Index Entry Limit

Number of keys for which there are too many values to maintain an index, based on the index entry limit. This is recorded as - for VLV indexes.

In other words, with the default index entry limit of 4000, if every user in your large directory has an email address ending in @example.com, and a substring index with default substring length of 6 is maintained for mail, then the directory server does not maintain indexes for keys corresponding to substrings in @example.com.

As a result, an LDAP search with the filter "(mail=*@example.com)" becomes an unindexed search even though a substring index exists for the mail attribute. By default the directory server does not allow unindexed searches except by privileged users. This is usually exactly the behavior you want in order to prevent client applications from sending searches that return every user in the directory for example. Clients should refine their search filters instead.

95%, 90%, 85%

Number of keys for which the number of values is approaching the index entry limit, having at least the specified percentage. This is a measure of how full the entry ID lists are.

11.3.4.7.1. Options

The backendstat show-index-status command takes the following options:

-n | --backendId {backendName}: The backend ID of the backend.
-b | --baseDn {baseDN}: The base DN within the backend.

11.3.5. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.3.6. Examples

The following example displays index information:

$ bin/backendstat dump-index -n userRoot -b dc=example,dc=com -i id2childrencount
Key (len 2): 1#52
Value (len 8): 1
Key (len 2): 2#52
Value (len 8): 500000
Key (len 9): Total Children Count
Value (len 8): 500001

Total Records: 3
Total / Average Key Size: 13 bytes / 4 bytes
Total / Average Data Size: 24 bytes / 8 bytes

Chapter 11.4. backup — back up directory data

11.4.1. Synopsis

backup {options}

11.4.2. Description

This utility can be used to back up one or more Directory Server backends.

11.4.3. Options

The backup command takes the following options:

Command options:

-a | --backUpAll

Back up all backends in the server.

Default: false

-A | --hash

Generate a hash of the backup contents.

Default: false

-B | --incrementalBaseId {backupID}

Backup ID of the source archive for an incremental backup.

-c | --compress

Compress the backup contents.

Default: false

-d | --backupDirectory {backupDir}

Path to the target directory for the backup file(s).

-i | --incremental

Perform an incremental backup rather than a full backup.

Default: false

-I | --backupId {backupID}

Use the provided identifier for the backup.

-n | --backendId {backendName}

Backend ID for the backend to archive.

--offline

Indicates that the command must be run in offline mode.

Default: false

-s | --signHash

Sign the hash of the backup contents.

Default: false

-y | --encrypt

Encrypt the backup contents.

Default: false

Task Scheduling Options

--completionNotify {emailAddress}

Email address of a recipient to be notified when the task completes. This option may be specified more than once.

--dependency {taskID}

ID of a task upon which this task depends. A task will not start execution until all its dependencies have completed execution.

--errorNotify {emailAddress}

Email address of a recipient to be notified if an error occurs when this task executes. This option may be specified more than once.

--failedDependencyAction {action}

Action this task will take should one if its dependent tasks fail. The value must be one of PROCESS,CANCEL,DISABLE. If not specified defaults to CANCEL.

--recurringTask {schedulePattern}

Indicates the task is recurring and will be scheduled according to the value argument expressed in crontab(5) compatible time/date pattern.

The schedule pattern for a recurring task supports only the following crontab features:

Time and Date Fields

Field	Allowed Values
minute	0-59
hour	0-23
day of month	1-31
month	1-12 (or names)
day of week	0-7 (0 or 7 is Sunday, or use names)

A field can contain an asterisk, *. An asterisk stands for first-last.

Fields can include ranges of numbers. A range is two numbers separated by a hyphen, and is inclusive. For example, 8-10 for an "hour" field means execution at hours 8, 9, and 10.

Fields can include lists. A list is a set of numbers or ranges separated by commas. For example, 4,8-10 for an "hour" field means execution at hours 4, 8, 9, and 10.

When using names for in "month" or "day of week" fields, use the first three letters of the particular month or day of the week. Case does not matter. Ranges and lists of names are not supported.

-t | --start {startTime}

Indicates the date/time at which this operation will start when scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC time or YYYYMMDDhhmmss for local time. A value of '0' will cause the task to be scheduled for immediate execution. When this option is specified the operation will be scheduled to start at the specified time after which this utility will exit immediately.

Task Backend Connection Options

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default: cn=Directory Manager

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

Utility input/output options:

--no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.4.4. Exit Codes

0: The command completed successfully.
1: An error occurred.

11.4.5. Examples

The following example backs up all user data while the server is online:

$ backup -p 4444 -D "cn=Directory Manager" -w password -a -d /path/to/opendj/bak -t 0
Backup task <timestamp> scheduled to start ...

The following example schedules back up of all user data every night at 2 AM when the server is online, and sends mail to diradmin@example.com when finished, or on error:

$ backup -p 4444 -D "cn=Directory Manager" -w password -a \
 -d /path/to/opendj/bak --recurringTask "00 02 * * *" \
 --completionNotify diradmin@example.com --errorNotify diradmin@example.com
Recurring Backup task BackupTask-<taskId> scheduled successfully

The following example backs up all user data while the server is offline:

$ stop-ds
Stopping Server...

$ backup --backupAll --backupDirectory /path/to/opendj/bak --offline
... msg=The backup process completed successfully

$ start-ds
... The Directory Server has started successfully

Chapter 11.5. base64 — encode and decode base64 strings

11.5.1. Synopsis

base64 {subcommand} {options}

11.5.2. Description

This utility can be used to encode and decode information using base64.

11.5.3. Options

The base64 command takes the following options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.5.4. Subcommands

The base64 command supports the following subcommands:

11.5.4.1. base64 decode

Decode base64-encoded information into raw data. When no options are specified, this subcommand reads from standard input and writes to standard output.

11.5.4.1.1. Options

The base64 decode command takes the following options:

-d | --encodedData {data}: The base64-encoded data to be decoded.
-f | --encodedDataFile {path}: The path to a file containing the base64-encoded data to be decoded.
-o | --toRawFile {path}: The path to a file to which the raw base64-decoded data should be written.

11.5.4.2. base64 encode

Encode raw data using base64. When no options are specified, this subcommand reads from standard input and writes to standard output.

11.5.4.2.1. Options

The base64 encode command takes the following options:

-d | --rawData {data}: The raw data to be base64 encoded.
-f | --rawDataFile {path}: The path to a file containing the raw data to be base64 encoded.
-o | --toEncodedFile {path}: The path to a file to which the base64-encoded data should be written.

11.5.5. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.5.6. Examples

The following command shows the changes from the external change log in human-readable format:

$ base64 decode -d YWRkOiBkZXNjcmlwdGlvbgpkZXNjcmlwdGlvbjogQSB0aGlyZCBjaGFuZ2UK\
LQpyZXBsYWNlOiBtb2RpZmllcnNOYW1lCm1vZGlmaWVyc05hbWU6IGNuPURpcmVjdG9yeSBNYW5hZ2V\
yLGNuPVJvb3QgRE5zLGNuPWNvbmZpZwotCnJlcGxhY2U6IG1vZGlmeVRpbWVzdGFtcAptb2RpZnlUaW\
1lc3RhbXA6IDIwMTEwNjEzMDcxMjEwWgotCg==
add: description
description: A third change
-
replace: modifiersName
modifiersName: cn=Directory Manager,cn=Root DNs,cn=config
-
replace: modifyTimestamp
modifyTimestamp: 20110613071210Z
-

Chapter 11.6. changelogstat — debug changelog and changenumber files

11.6.1. Synopsis

changelogstat {subcommand} {options}

11.6.2. Description

This utility can be used to debug changelog and changenumber files.

11.6.3. Options

The changelogstat command takes the following options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.6.4. Subcommands

The changelogstat command supports the following subcommands:

11.6.4.1. changelogstat dump-change-number-db

Dump the change number DB.

11.6.4.1.1. Options

The changelogstat dump-change-number-db command takes the following options:

--outputDir {directory}: The output directory for the dump files.
--from {change number}: The lower bound of the range of change numbers to dump.
--to {change number}: The upper bound of the range of change numbers to dump.

11.6.4.2. changelogstat dump-replica-db

Dump the replica DB for a given domain and replica.

11.6.4.2.1. Options

The changelogstat dump-replica-db command takes the following options:

--outputDir {directory}: The output directory for the dump files.
--from {csn}: The lower bound of the range of changes to dump.
--to {csn}: The upper bound of the range of changes to dump.

11.6.4.3. changelogstat dump-replica-db-file

Dump a replica DB file.

11.6.4.3.1. Options

The changelogstat dump-replica-db-file command takes the following options:

--from {csn}: The lower bound of the range of changes to dump.
--to {csn}: The upper bound of the range of changes to dump.

11.6.5. Exit Codes

0: The command completed successfully.
1: An error occurred.

11.6.6. Examples

To dump the change number DB from change number 10 to 15:

$ changelogstat dump-change-number-db --from 10 --to 15

 changeNumber=10 baseDN=dc=example,dc=com csn=01010166aaf2a3e3000002c61 (sid=1,tsd=Thu Oct 25 13:18:40 CEST 2018,ts=1540466320355,seqnum=710)
 changeNumber=11 baseDN=dc=example,dc=com csn=01010166aaf2a3e3000002c71 (sid=1,tsd=Thu Oct 25 13:18:40 CEST 2018,ts=1540466320355,seqnum=711)
 changeNumber=12 baseDN=dc=example,dc=com csn=01010166aaf2a3e3000002c81 (sid=1,tsd=Thu Oct 25 13:18:40 CEST 2018,ts=1540466320355,seqnum=712)
 changeNumber=13 baseDN=dc=example,dc=com csn=01010166aaf2a3e3000002c91 (sid=1,tsd=Thu Oct 25 13:18:40 CEST 2018,ts=1540466320355,seqnum=713)
 changeNumber=14 baseDN=dc=example,dc=com csn=01010166aaf2a3e3000002ca1 (sid=1,tsd=Thu Oct 25 13:18:40 CEST 2018,ts=1540466320355,seqnum=714)
 changeNumber=15 baseDN=dc=example,dc=com csn=01010166aaf2a3e3000002cb1 (sid=1,tsd=Thu Oct 25 13:18:40 CEST 2018,ts=1540466320355,seqnum=715)

To dump the replica DB for the domain dc=example,dc=com on the server 1:

$ changelogstat dump-replica-db --outputDir myOutputDir dc=example,dc=com 1

To dump a specific replica DB file:

$ changelogstat dump-replica-db-file changelogDb/2.dom/1.server/01010166aaf2a3e3000002bd1.log

 ModifyMsg content:  protocolVersion: 10 dn: uid=user.48,ou=people,dc=example,dc=com csn: 01010166aaf2a3e3000002bd1 uniqueId: 55cf0798-774c-3d55-888b-c3833d57ba0e
 ModifyMsg content:  protocolVersion: 10 dn: uid=user.73,ou=people,dc=example,dc=com csn: 01010166aaf2a3e3000002be1 uniqueId: 8977f8ac-1579-3538-accf-a6ce7f612076
 ModifyMsg content:  protocolVersion: 10 dn: uid=user.34,ou=people,dc=example,dc=com csn: 01010166aaf2a3e3000002bf1 uniqueId: a1fa5d92-326a-3283-a040-114300fcc7e5
 ModifyMsg content:  protocolVersion: 10 dn: uid=user.69,ou=people,dc=example,dc=com csn: 01010166aaf2a3e3000002c01 uniqueId: da34114f-b183-3ccd-b7d8-486791aa4651
 ...
 ModifyMsg content:  protocolVersion: 10 dn: uid=user.4,ou=people,dc=example,dc=com csn: 01010166aaf2da2400008b7d1 uniqueId: 1539438e-ae81-36ce-aecf-dd4dc72a12f0
 ModifyMsg content:  protocolVersion: 10 dn: uid=user.27,ou=people,dc=example,dc=com csn: 01010166aaf2da2400008b7e1 uniqueId: 950dd85c-9e53-3b12-8074-c2eb88582156
 ModifyMsg content:  protocolVersion: 10 dn: uid=user.13,ou=people,dc=example,dc=com csn: 01010166aaf2da2400008b7f1 uniqueId: 120b8640-5295-36dc-9ea3-8b20735348ab
 ModifyMsg content:  protocolVersion: 10 dn: uid=user.91,ou=people,dc=example,dc=com csn: 01010166aaf2da2400008b801 uniqueId: 6e9c2930-cc4f-3f7b-9dcf-d81aa46f57f9

Chapter 11.7. create-rc-script — script to manage OpenDJ as a service on UNIX

11.7.1. Synopsis

create-rc-script {options}

11.7.2. Description

Create an RC script that may be used to start, stop, and restart the Directory Server on UNIX-based systems.

11.7.3. Options

The create-rc-script command takes the following options:

Command options:

-f | --outputFile {path}: The path to the output file to create.
-j | --javaHome {path}: The path to the Java installation that should be used to run the server.
-J | --javaArgs {args}: A set of arguments that should be passed to the JVM when running the server.
-u | --userName {userName}: The name of the user account under which the server should run.

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.7.4. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.7.5. Examples

The following example adds a script to start the server at boot time on a Debian-based system, and then updates the runlevel system to use the script:

$ sudo create-rc-script -f /etc/init.d/opendj -u opendj-user
$ sudo update-rc.d opendj

Chapter 11.8. dsconfig — manage OpenDJ server configuration

11.8.1. Synopsis

dsconfig {subcommand} {options}

11.8.2. Description

This utility can be used to define a base configuration for the Directory Server.

The dsconfig command is the primary command-line tool for viewing and editing the server configuration. When started without arguments, dsconfig prompts you for administration connection information, including the host name, administration port number, administrator bind DN and administrator password. The dsconfig command then connects securely to the directory server over the administration port. Once connected it presents you with a menu-driven interface to the server configuration.

When you pass connection information, subcommands, and additional options to dsconfig, the command runs in script mode and so is not interactive, though it can prompt you to ask whether to apply changes and whether to trust certificates (unless you use the --no-prompt and --trustAll options, respectively).

You can prepare dsconfig batch scripts by running the tool with the --commandFilePath option in interactive mode, then reading from the batch file with the --batchFilePath option in script mode. Batch files can be useful when you have many dsconfig commands to run and want to avoid starting the JVM for each command. Alternatively, you can read commands from standard input by using the --batch option.

The dsconfig command categorizes directory server configuration into components, also called managed objects. Actual components often inherit from a parent component type. For example, one component is a Connection Handler. An LDAP Connection Handler is a type of Connection Handler. You configure the LDAP Connection Handler component to specify how the server handles LDAP connections coming from client applications.

Configuration components have properties. For example, the LDAP Connection Handler component has properties such as listen-port and allow-start-tls. You can set the component's listen-port property to 389 to use the default LDAP port number. You can set the component's allow-start-tls property to true to permit LDAP client applications to use StartTLS. Much of the configuration you do with dsconfig involves setting component properties.

11.8.3. Options

The dsconfig command takes the following options:

Command options:

--batch

Reads from standard input a set of commands to be executed.

Default: false

--commandFilePath {path}

The full path to the file where the equivalent non-interactive commands will be written when this command is run in interactive mode.

--configFile {configFile}

Path to the Directory Server configuration file.

Default: null/config/config.ldif

--help-all

Display all subcommands.

Default: false

--help-core-server

Display subcommands relating to core server.

Default: false

--help-database

Display subcommands relating to caching and backends.

Default: false

--help-logging

Display subcommands relating to logging.

Default: false

--help-proxy

Display subcommands relating to directory proxy.

Default: false

--help-replication

Display subcommands relating to replication.

Default: false

--help-security

Display subcommands relating to authentication and authorization.

Default: false

--help-service-discovery

Display subcommands relating to service discovery mechanism.

Default: false

--help-user-management

Display subcommands relating to user management.

Default: false

--offline

Indicates that the command must be run in offline mode.

Default: false

Configuration Options

--advanced

Allows the configuration of advanced components and properties.

Default: false

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default: cn=Directory Manager

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

Utility input/output options:

-F | --batchFilePath {batchFilePath}

Path to a batch file containing a set of commands to be executed.

-n | --no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-Q | --quiet

Use quiet mode.

Default: false

-s | --script-friendly

Use script-friendly mode.

Default: false

-v | --verbose

Use verbose mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.8.4. Subcommands

The dsconfig command provides many subcommands.

Subcommands let you create, list, and delete entire configuration components, and get and set component properties. Subcommands have names that reflect these five actions:

create-component
list-components
delete-component
get-component-prop
set-component-prop

Here, component names are names of managed object types. Subcommand component names are lower-case, hyphenated versions of the friendly names. When you act on an actual configuration component, you provide the name of the component as an option argument.

For example, the Log Publisher component has these corresponding subcommands.

create-log-publisher
list-log-publishers
delete-log-publisher
get-log-publisher-prop
set-log-publisher-prop

When you create or delete Log Publisher components and when you get and set their configuration properties, you provide the name of the actual log publisher, which you can find by using the list-log-publishers subcommand:

# Get the log publishers' names:
$ dsconfig \
 list-log-publishers \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --trustAll \
 --no-prompt
Log Publisher                      : Type                   : enabled
-----------------------------------:------------------------:--------
...
Json File-Based Access Logger      : json-file-access       : true
...

# Use the name to read a property:
$ dsconfig \
 get-log-publisher-prop \
 --publisher-name "Json File-Based Access Logger" \
 --property rotation-policy \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --trustAll \
 --no-prompt
Property        : Value(s)
----------------:--------------------------------------------------------------
rotation-policy : 24 Hours Time Limit Rotation Policy, Size Limit Rotation
                : Policy

Many subcommands let you set property values. Notice in the reference for the subcommands below that specific options are available for handling multi-valued properties. Whereas you can assign a single property value by using the --set option, you assign multiple values to a multi-valued property by using the --add option. You can reset the values of the multi-valued property by using the --reset option.

Some property values take a time duration. Durations are expressed as numbers followed by units. For example 1 s means one second, and 2 w means two weeks. Some durations have minimum granularity or maximum units, so you cannot necessary specify every duration in milliseconds or weeks for example. Some durations allow you to use a special value to mean unlimited. Units are specified as follows.

ms: milliseconds
s: seconds
m: minutes
h: hours
d: days
w: weeks

Use the --help* options described above to view help for subcommands.

For help with individual subcommands, either use dsconfig subcommand --help, or start dsconfig in interactive mode, without specifying a subcommand.

To view all component properties, use the dsconfig list-properties command.

11.8.5. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.8.6. Examples

The following example starts the dsconfig command in interactive, menu-driven mode on the default port of the current host:

$ dsconfig -h opendj.example.com -p 4444 -D "cn=Directory Manager" -w password

>>>> OpenDJ configuration console main menu

What do you want to configure?

    1)   Access Control Handler               22)  Key Manager Provider
    2)   Access Log Filtering Criteria        23)  Log Publisher
    3)   Account Status Notification Handler  24)  Log Retention Policy
    4)   Administration Connector             25)  Log Rotation Policy
    5)   Alert Handler                        26)  Password Generator
    6)   Backend                              27)  Password Policy
    7)   Backend Index                        28)  Password Storage Scheme
    8)   Backend VLV Index                    29)  Password Validator
    9)   Certificate Mapper                   30)  Plugin
    10)  Connection Handler                   31)  Plugin Root
    11)  Crypto Manager                       32)  Replication Domain
    12)  Debug Target                         33)  Replication Server
    13)  Entry Cache                          34)  Root DSE Backend
    14)  Extended Operation Handler           35)  SASL Mechanism Handler
    15)  External Changelog Domain            36)  Schema Provider
    16)  Global Access Control Policy         37)  Service Discovery Mechanism
    17)  Global Configuration                 38)  Synchronization Provider
    18)  Group Implementation                 39)  Trust Manager Provider
    19)  HTTP Authorization Mechanism         40)  Virtual Attribute
    20)  HTTP Endpoint                        41)  Work Queue
    21)  Identity Mapper

    a)   show advanced components and properties
    q)   quit

Enter choice:

The following example demonstrates generating a batch file that corresponds to an interactive session enabling the debug log. The example then demonstrates using a modified batch file to disable the debug log:

$ dsconfig \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --commandFilePath ~/enable-debug-log.batch

$ cat ~/enable-debug-log.batch
# dsconfig session start date: <date>

# Session operation number: 1
# Operation date: <date>
dsconfig set-log-publisher-prop \
          --publisher-name File-Based\ Debug\ Logger \
          --set enabled:true \
          --hostname opendj.example.com \
          --port 4444 \
          --trustStorePath /path/to/opendj/config/admin-truststore \
          --bindDN cn=Directory\ Manager \
          --bindPassword ****** \
          --no-prompt

$ cp ~/enable-debug-log.batch ~/disable-debug-log.batch
$ vi ~/disable-debug-log.batch
$ cat ~/disable-debug-log.batch
set-log-publisher-prop \
          --publisher-name File-Based\ Debug\ Logger \
          --set enabled:false \
          --hostname opendj.example.com \
          --port 4444 \
          --trustStorePath /path/to/opendj/config/admin-truststore \
          --bindDN cn=Directory\ Manager \
          --bindPassword password \
          --no-prompt

$ dsconfig --batchFilePath ~/disable-debug-log.batch --no-prompt
set-log-publisher-prop
--publisher-name
File-Based Debug Logger
--set
enabled:false
--hostname
opendj.example.com
--port
4444
--trustStorePath
/path/to/opendj/config/admin-truststore
--bindDN
cn=Directory Manager
--bindPassword
password
--no-prompt

Notice that the original command file looks like a shell script with the bind password value replaced by asterisks. To pass the content as a batch file to the dsconfig command, strip dsconfig itself, and include the bind password for the administrative user or replace that option with an alternative, such as reading the password from a file.

Chapter 11.9. dsreplication — manage directory data replication

11.9.1. Synopsis

dsreplication {subcommand} {options}

11.9.2. Description

This utility manages replication between servers so that their data is synchronized. For replication to work you must first configure replication using the 'configure' subcommand and then initialize the contents of one of the servers with the contents of the other using the 'initialize' subcommand.

11.9.3. Options

The dsreplication command takes the following options:

Command options:

--commandFilePath {path}

The full path to the file where the equivalent non-interactive commands will be written when this command is run in interactive mode.

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-j | --adminPasswordFile {bindPasswordFile}

The file containing the password of the global administrator.

-w | --adminPassword {bindPassword}

The global administrator password.

Configuration Options

--advanced

Allows the configuration of advanced components and properties.

Default: false

LDAP connection options:

-I | --adminUid {adminUID}

User ID of the Global Administrator to use to bind to the server. For the 'configure' subcommand if no Global Administrator was defined previously for none of the server the Global Administrator will be created using the provided data.

Default: admin

-K | --keyStorePath {keyStorePath}

Certificate key store path.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-P | --trustStorePath {trustStorePath}

Certificate trust store path.

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

Utility input/output options:

-n | --no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-Q | --quiet

Use quiet mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.9.4. Subcommands

The dsreplication command supports the following subcommands:

11.9.4.1. dsreplication configure

Updates the configuration of the servers to replicate the data under the specified base DN. If one of the specified servers is already replicating the data under the base DN with other servers, executing this subcommand will update the configuration of all the servers (so it is sufficient to execute the command line once for each server we add to the replication topology).

11.9.4.1.1. Options

The dsreplication configure command takes the following options:

-h | --host1 {host}

Fully qualified host name or IP address of the first server whose contents will be replicated.

Default: localhost.localdomain

-p | --port1 {port}

Directory server administration port number of the first server whose contents will be replicated.

-D | --bindDn1 {bindDN}

DN to use to bind to the first server whose contents will be replicated. If not specified the global administrator will be used to bind.

Default: cn=Directory Manager

--bindPassword1 {bindPassword}

Password to use to bind to the first server whose contents will be replicated. If no bind DN was specified for the first server the password of the global administrator will be used to bind.

--bindPasswordFile1 {bindPasswordFile}

File containing the password to use to bind to the first server whose contents will be replicated. If no bind DN was specified for the first server the password of the global administrator will be used to bind.

-r | --replicationPort1 {port}

Port that will be used by the replication mechanism in the first server to communicate with the other servers. You have to specify this option only if replication was not previously configured in the first server.

--secureReplication1

Specifies whether the communication through the replication port of the first server is encrypted or not. This option will only be taken into account the first time replication is configured on the first server.

Default: false

--noReplicationServer1

Do not configure a replication port or change log on the first server. The first server will contain replicated data but will not contain a change log of modifications made to the replicated data. Note that each replicated topology must contain at least two servers with a change log to avoid a single point of failure.

Default: false

--onlyReplicationServer1

Configure only a change log and replication port on the first server. The first server will not contain replicated data, but will contain a change log of the modifications made to the replicated data on other servers.

Default: false

-O | --host2 {host}

Fully qualified host name or IP address of the second server whose contents will be replicated.

Default: localhost.localdomain

--port2 {port}

Directory server administration port number of the second server whose contents will be replicated.

--bindDn2 {bindDN}

DN to use to bind to the second server whose contents will be replicated. If not specified the global administrator will be used to bind.

Default: cn=Directory Manager

--bindPassword2 {bindPassword}

Password to use to bind to the second server whose contents will be replicated. If no bind DN was specified for the second server the password of the global administrator will be used to bind.

-F | --bindPasswordFile2 {bindPasswordFile}

File containing the password to use to bind to the second server whose contents will be replicated. If no bind DN was specified for the second server the password of the global administrator will be used to bind.

-R | --replicationPort2 {port}

Port that will be used by the replication mechanism in the second server to communicate with the other servers. You have to specify this option only if replication was not previously configured in the second server.

--secureReplication2

Specifies whether the communication through the replication port of the second server is encrypted or not. This option will only be taken into account the first time replication is configured on the second server.

Default: false

--noReplicationServer2

Do not configure a replication port or change log on the second server. The second server will contain replicated data but will not contain a change log of modifications made to the replicated data. Note that each replicated topology must contain at least two servers with a change log to avoid a single point of failure.

Default: false

--onlyReplicationServer2

Configure only a change log and replication port on the second server. The second server will not contain replicated data, but will contain a change log of the modifications made to the replicated data on other servers.

Default: false

-S | --skipPortCheck

Skip the check to determine whether the specified replication ports are usable.

Default: false

--noSchemaReplication

Do not replicate the schema between the servers.

Default: false

--useSecondServerAsSchemaSource

Use the second server to initialize the schema of the first server. If this option nor option --noSchemaReplication are specified the schema of the first server will be used to initialize the schema of the second server.

Default: false

-b | --baseDn {baseDN}

Base DN(s) of the data to be replicated. Multiple base DNs can be provided by using this option multiple times.

11.9.4.2. dsreplication initialize

Initialize the contents of the data under the specified base DN on the destination server with the contents on the source server. This operation is required after configuring replication in order replication to work ('initialize-all' can also be used for this purpose).

11.9.4.2.1. Options

The dsreplication initialize command takes the following options:

-h | --hostSource {host}

Fully qualified host name or IP address of the source server whose contents will be used to initialize the destination server.

Default: localhost.localdomain

-p | --portSource {port}

Directory server administration port number of the source server whose contents will be used to initialize the destination server.

-O | --hostDestination {host}

Fully qualified host name or IP address of the destination server whose contents will be initialized.

Default: localhost.localdomain

--portDestination {port}

Directory server administration port number of the destination server whose contents will be initialized.

-b | --baseDn {baseDN}

Base DN(s) of the data for which replication will be initialized. Multiple base DNs can be provided by using this option multiple times.

11.9.4.3. dsreplication initialize-all

Initialize the contents of the data under the specified base DN on all the servers whose contents are being replicated with the contents on the specified server. This operation is required after configuring replication for replication to work ('initialize' applied to each server can also be used for this purpose).

11.9.4.3.1. Options

The dsreplication initialize-all command takes the following options:

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-p | --port {port}

Directory server administration port number.

-b | --baseDn {baseDN}

Base DN(s) of the data for which replication will be initialized. Multiple base DNs can be provided by using this option multiple times.

11.9.4.4. dsreplication post-external-initialization

This subcommand must be called after initializing the contents of all the replicated servers using the tool import-ldif or the binary copy method. You must specify the list of base DNs that have been initialized and you must provide the credentials of any of the servers that are being replicated. See the usage of the subcommand 'pre-external-initialization' for more information.

11.9.4.4.1. Options

The dsreplication post-external-initialization command takes the following options:

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-p | --port {port}

Directory server administration port number.

-b | --baseDn {baseDN}

Base DN(s) of the data that have been restored from backup. Multiple base DNs can be provided by using this option multiple times.

11.9.4.5. dsreplication pre-external-initialization

This subcommand must be called before initializing the contents of all the replicated servers using the tool import-ldif or the binary copy method. You must specify the list of base DNs that will be initialized and you must provide the credentials of any of the servers that are being replicated. After calling this subcommand, initialize the contents of all the servers in the topology (use the same LDIF file/binary copy on each of the servers), then call the subcommand 'post-external-initialization'.

11.9.4.5.1. Options

The dsreplication pre-external-initialization command takes the following options:

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-p | --port {port}

Directory server administration port number.

-b | --baseDn {baseDN}

Base DN(s) of the data that will be restored from backup. Multiple base DNs can be provided by using this option multiple times.

11.9.4.6. dsreplication purge-historical

Launches a purge processing of the historical informations stored in the user entries by replication. Since this processing may take a while, you must specify the maximum duration for this processing.

11.9.4.6.1. Options

The dsreplication purge-historical command takes the following options:

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-p | --port {port}

Directory server administration port number.

--maximumDuration {maximum duration}

This argument specifies the maximum duration the purge processing must last expressed in seconds.

Default: 3600

-b | --baseDn {baseDN}

Base DN(s) from which historical information will be purged. Multiple base DNs can be provided by using this option multiple times.

-t | --start {startTime}

Indicates the date/time at which this operation will start when scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC time or YYYYMMDDhhmmss for local time. A value of '0' will cause the task to be scheduled for immediate execution. When this option is specified the operation will be scheduled to start at the specified time after which this utility will exit immediately.

--recurringTask {schedulePattern}

Indicates the task is recurring and will be scheduled according to the value argument expressed in crontab(5) compatible time/date pattern.

The schedule pattern for a recurring task supports only the following crontab features:

Time and Date Fields

Field	Allowed Values
minute	0-59
hour	0-23
day of month	1-31
month	1-12 (or names)
day of week	0-7 (0 or 7 is Sunday, or use names)

A field can contain an asterisk, *. An asterisk stands for first-last.

Fields can include ranges of numbers. A range is two numbers separated by a hyphen, and is inclusive. For example, 8-10 for an "hour" field means execution at hours 8, 9, and 10.

Fields can include lists. A list is a set of numbers or ranges separated by commas. For example, 4,8-10 for an "hour" field means execution at hours 4, 8, 9, and 10.

When using names for in "month" or "day of week" fields, use the first three letters of the particular month or day of the week. Case does not matter. Ranges and lists of names are not supported.

--completionNotify {emailAddress}

Email address of a recipient to be notified when the task completes. This option may be specified more than once.

--errorNotify {emailAddress}

Email address of a recipient to be notified if an error occurs when this task executes. This option may be specified more than once.

--dependency {taskID}

ID of a task upon which this task depends. A task will not start execution until all its dependencies have completed execution.

--failedDependencyAction {action}

Action this task will take should one if its dependent tasks fail. The value must be one of PROCESS,CANCEL,DISABLE. If not specified defaults to CANCEL.

11.9.4.7. dsreplication reset-change-number

Re-synchronizes the change-log changenumber on one server with the change-log changenumber of another.

11.9.4.7.1. Options

The dsreplication reset-change-number command takes the following options:

-h | --hostSource {host}

Fully qualified host name or IP address of the source server whose contents will be used to initialize the destination server.

Default: localhost.localdomain

-p | --portSource {port}

Directory server administration port number of the source server whose contents will be used to initialize the destination server.

-O | --hostDestination {host}

Fully qualified host name or IP address of the destination server whose contents will be initialized.

Default: localhost.localdomain

--portDestination {port}

Directory server administration port number of the destination server whose contents will be initialized.

--change-number {change number}

The change number to use as the basis for re-synchronization.

11.9.4.8. dsreplication resume

Resumes replication on the specified server.

11.9.4.8.1. Options

The dsreplication resume command takes the following options:

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-p | --port {port}

Directory server administration port number.

11.9.4.9. dsreplication status

Displays a list with the basic replication configuration of the base DNs of the servers defined in the registration information. If no base DNs are specified as parameter the information for all base DNs is displayed.

11.9.4.9.1. Options

The dsreplication status command takes the following options:

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-p | --port {port}

Directory server administration port number.

-s | --script-friendly

Use script-friendly mode.

Default: false

-b | --baseDn {baseDN}

This option can be used to filter replication topology base DN(s).

Multiple base DNs can be provided by using this option multiple times. If no base DNs are specified the information for all base DNs is displayed.

11.9.4.10. dsreplication suspend

Suspends (pauses) replication on the specified server.

11.9.4.10.1. Options

The dsreplication suspend command takes the following options:

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-p | --port {port}

Directory server administration port number.

11.9.4.11. dsreplication unconfigure

Unconfigures replication on the specified server for the provided base DN and removes references in the other servers with which it is replicating data.

11.9.4.11.1. Options

The dsreplication unconfigure command takes the following options:

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-p | --port {port}

Directory server administration port number.

-a | --unconfigureReplicationServer

Unconfigure the replication server. The replication port and change log will be unconfigured on the specified server.

Default: false

--unconfigureAll

Unconfigure the replication configuration on the specified server. The contents of the server are no longer replicated and the replication server (changelog and replication port) is unconfigured if it is configured.

Default: false

-D | --bindDn {bindDN}

DN to use to bind to the server where we want to unconfigure replication. This option must be used when no Global Administrator has been defined on the server or if the user does not want to remove references in the other replicated servers. The password provided for the Global Administrator will be used when specifying this option.

Default: cn=Directory Manager

-b | --baseDn {baseDN}

Base DN(s) of the data for which replication will be unconfigured. Multiple base DNs can be provided by using this option multiple times.

11.9.5. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.9.6. Examples

The following example configures and then initializes replication for a new replica on opendj2.example.com from an existing replica on opendj.example.com:

$ dsreplication configure -I admin -w password -X -n -b 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

$ dsreplication initialize-all -I admin -w password -X -n -b dc=example,dc=com \
 -h opendj.example.com -p 4444

Chapter 11.10. encode-password — encode a password with a storage scheme

11.10.1. Synopsis

encode-password {options}

11.10.2. Description

This utility can be used to encode user passwords with a specified storage scheme, or to determine whether a given clear-text value matches a provided encoded password.

11.10.3. Options

The encode-password command takes the following options:

Command options:

-a | --authPasswordSyntax

Use the authentication password syntax rather than the user password syntax.

Default: false

-c | --clearPassword {clearPW}

Clear-text password to encode or to compare against an encoded password.

-e | --encodedPassword {encodedPW}

Encoded password to compare against the clear-text password.

-E | --encodedPasswordFile {file}

Encoded password file.

-f | --clearPasswordFile {file}

Clear-text password file.

-i | --interactivePassword

The password to encode or to compare against an encoded password is interactively asked to the user.

Default: false

-l | --listSchemes

List available password storage schemes.

Default: false

-r | --useCompareResultCode

Use the LDAP compare result as an exit code for the password comparison.

Default: false

-s | --storageScheme {scheme}

Scheme to use for the encoded password.

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.10.4. Exit Codes

0: The command completed successfully.
5: The -r option was used, and the compare did not match.
6: The -r option was used, and the compare did match.
other: An error occurred.

11.10.5. Examples

The following example encodes a password and compares a password with the encoded value:

$ encode-password -l
3DES
AES
BASE64
BCRYPT
BLOWFISH
CLEAR
CRYPT
MD5
PBKDF2
PKCS5S2
RC4
SHA
SMD5
SSHA
SSHA256
SSHA384
SSHA512

$ encode-password -c secret12 -s CRYPT
{CRYPT}ZulJ6Dy3TFnrE

$ encode-password -c secret12 -s CRYPT -e "{CRYPT}ZulJ6Dy3TFnrE" -r
The provided clear-text and encoded passwords match

$ echo $?
6

Chapter 11.11. export-ldif — export directory data in LDIF

11.11.1. Synopsis

export-ldif {options}

11.11.2. Description

This utility can be used to export data from a Directory Server backend in LDIF form.

11.11.3. Options

The export-ldif command takes the following options:

Command options:

-a | --appendToLdif

Append an existing LDIF file rather than overwriting it.

Default: false

-b | --includeBranch {branchDN}

Base DN of a branch to include in the LDIF export.

-B | --excludeBranch {branchDN}

Base DN of a branch to exclude from the LDIF export.

-c | --compress

Compress the LDIF data as it is exported.

Default: false

-e | --excludeAttribute {attribute}

Attribute to exclude from the LDIF export.

--excludeFilter {filter}

Filter to identify entries to exclude from the LDIF export.

-i | --includeAttribute {attribute}

Attribute to include in the LDIF export.

--includeFilter {filter}

Filter to identify entries to include in the LDIF export.

-l | --ldifFile {ldifFile}

Path to the LDIF file to be written.

-n | --backendId {backendName}

Backend ID for the backend to export.

-O | --excludeOperational

Exclude operational attributes from the LDIF export.

Default: false

--offline

Indicates that the command must be run in offline mode.

Default: false

Task Scheduling Options

--completionNotify {emailAddress}

Email address of a recipient to be notified when the task completes. This option may be specified more than once.

--dependency {taskID}

ID of a task upon which this task depends. A task will not start execution until all its dependencies have completed execution.

--errorNotify {emailAddress}

Email address of a recipient to be notified if an error occurs when this task executes. This option may be specified more than once.

--failedDependencyAction {action}

Action this task will take should one if its dependent tasks fail. The value must be one of PROCESS,CANCEL,DISABLE. If not specified defaults to CANCEL.

--recurringTask {schedulePattern}

Indicates the task is recurring and will be scheduled according to the value argument expressed in crontab(5) compatible time/date pattern.

The schedule pattern for a recurring task supports only the following crontab features:

Time and Date Fields

Field	Allowed Values
minute	0-59
hour	0-23
day of month	1-31
month	1-12 (or names)
day of week	0-7 (0 or 7 is Sunday, or use names)

A field can contain an asterisk, *. An asterisk stands for first-last.

Fields can include ranges of numbers. A range is two numbers separated by a hyphen, and is inclusive. For example, 8-10 for an "hour" field means execution at hours 8, 9, and 10.

Fields can include lists. A list is a set of numbers or ranges separated by commas. For example, 4,8-10 for an "hour" field means execution at hours 4, 8, 9, and 10.

When using names for in "month" or "day of week" fields, use the first three letters of the particular month or day of the week. Case does not matter. Ranges and lists of names are not supported.

-t | --start {startTime}

Indicates the date/time at which this operation will start when scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC time or YYYYMMDDhhmmss for local time. A value of '0' will cause the task to be scheduled for immediate execution. When this option is specified the operation will be scheduled to start at the specified time after which this utility will exit immediately.

Task Backend Connection Options

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default: cn=Directory Manager

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

Utility input/output options:

--no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

--wrapColumn {wrapColumn}

Column at which to wrap long lines (0 for no wrapping).

Default: 0

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.11.4. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.11.5. Examples

The following example exports data to a file, Example.ldif, with the server offline:

$ export-ldif -b dc=example,dc=com -n userRoot -l /path/to/opendj/ldif/Example.ldif --offline
... category=BACKEND severity=INFORMATION ...
...Exported 160 entries and skipped 0 in 0 seconds (average rate 1428.6/sec)

Chapter 11.12. import-ldif — import directory data from LDIF

11.12.1. Synopsis

import-ldif {options}

11.12.2. Description

This utility can be used to import LDIF data into a Directory Server backend, overwriting existing data. It cannot be used to append data to the backend database.

11.12.3. Options

The import-ldif command takes the following options:

Command options:

-A | --templateFile {templateFile}

Path to a MakeLDIF template to use to generate the import data.

-b | --includeBranch {branchDN}

Base DN of a branch to include in the LDIF import.

-B | --excludeBranch {branchDN}

Base DN of a branch to exclude from the LDIF import.

-c | --isCompressed

LDIF file is compressed.

Default: false

--countRejects

Count the number of entries rejected by the server and return that value as the exit code (values > 255 will be reduced to 255 due to exit code restrictions).

Default: false

-e | --excludeAttribute {attribute}

Attribute to exclude from the LDIF import.

--excludeFilter {filter}

Filter to identify entries to exclude from the LDIF import.

-F | --clearBackend

Remove all entries for all base DNs in the backend before importing.

Default: false

-i | --includeAttribute {attribute}

Attribute to include in the LDIF import.

--includeFilter {filter}

Filter to identify entries to include in the LDIF import.

-l | --ldifFile {ldifFile}

Path to the LDIF file to be imported.

-n | --backendId {backendName}

Backend ID for the backend to import.

-O | --overwrite

Overwrite an existing rejects and/or skip file rather than appending to it.

Default: false

--offline

Indicates that the command must be run in offline mode.

Default: false

-R | --rejectFile {rejectFile}

Write rejected entries to the specified file.

-s | --randomSeed {seed}

Seed for the MakeLDIF random number generator.

Default: 0

-S | --skipSchemaValidation

Skip schema validation during the LDIF import.

Default: false

--skipFile {skipFile}

Write skipped entries to the specified file.

--threadCount {count}

Number of threads used to read LDIF file during import. Default value (0) equals: 2 x (number of CPUs).

Default: 0

--tmpDirectory {directory}

Path to temporary directory for index scratch files during LDIF import.

Default: import-tmp

Task Scheduling Options

--completionNotify {emailAddress}

Email address of a recipient to be notified when the task completes. This option may be specified more than once.

--dependency {taskID}

ID of a task upon which this task depends. A task will not start execution until all its dependencies have completed execution.

--errorNotify {emailAddress}

Email address of a recipient to be notified if an error occurs when this task executes. This option may be specified more than once.

--failedDependencyAction {action}

Action this task will take should one if its dependent tasks fail. The value must be one of PROCESS,CANCEL,DISABLE. If not specified defaults to CANCEL.

--recurringTask {schedulePattern}

Indicates the task is recurring and will be scheduled according to the value argument expressed in crontab(5) compatible time/date pattern.

The schedule pattern for a recurring task supports only the following crontab features:

Time and Date Fields

Field	Allowed Values
minute	0-59
hour	0-23
day of month	1-31
month	1-12 (or names)
day of week	0-7 (0 or 7 is Sunday, or use names)

A field can contain an asterisk, *. An asterisk stands for first-last.

Fields can include ranges of numbers. A range is two numbers separated by a hyphen, and is inclusive. For example, 8-10 for an "hour" field means execution at hours 8, 9, and 10.

Fields can include lists. A list is a set of numbers or ranges separated by commas. For example, 4,8-10 for an "hour" field means execution at hours 4, 8, 9, and 10.

When using names for in "month" or "day of week" fields, use the first three letters of the particular month or day of the week. Case does not matter. Ranges and lists of names are not supported.

-t | --start {startTime}

Indicates the date/time at which this operation will start when scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC time or YYYYMMDDhhmmss for local time. A value of '0' will cause the task to be scheduled for immediate execution. When this option is specified the operation will be scheduled to start at the specified time after which this utility will exit immediately.

Task Backend Connection Options

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default: cn=Directory Manager

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

Utility input/output options:

--no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-Q | --quiet

Use quiet mode (no output).

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.12.4. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.12.5. Examples

The following example imports the content of a file in the current directory, Example.ldif, with the server offline:

$ import-ldif -b dc=example,dc=com -n userRoot -l Example.ldif --offline
... category=RUNTIME_INFORMATION severity=NOTICE...
... msg=Import LDIF environment close took 0 seconds

Chapter 11.13. ldapcompare — perform LDAP compare operations

11.13.1. Synopsis

ldapcompare {options} attribute:value DN

11.13.2. Description

This utility can be used to perform LDAP compare operations in the Directory Server.

11.13.3. Options

The ldapcompare command takes the following options:

Command options:

--assertionFilter {filter}

Use the LDAP assertion control with the provided filter.

-J | --control {controloid[:criticality[:value|::b64value|:<filePath]]}

Use a request control with the provided information.

For some controloid values, you can replace object identifiers with user-friendly strings. The values are not case-sensitive:

Assertion, LdapAssertion

Assertion Request Control, Object Identifier: 1.3.6.1.1.12

AccountUsable, AccountUsability

Account Usability Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.8

AuthzId, AuthorizationIdentity

Authorization Identity Request Control, Object Identifier: 2.16.840.1.113730.3.4.16

Csn, ChangeNumber, ChangeSequenceNumber

Change Sequence Number Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.9

This is an internal DS server control.

EffectiveRights, GetEffectiveRights

Get Effective Rights Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.2

ManageDsaIt

Manage DSAIT Request Control, Object Identifier: 2.16.840.1.113730.3.4.2

Noop, No-Op

No-Op Request Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.2

PwPolicy, PasswordPolicy

Password Policy Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.8.5.1

PermissiveModify

Permissive Modify Request Control, Object Identifier: 1.2.840.113556.1.4.1413

PSearch, PersistentSearch

Persistent Search Request Control, Object Identifier: 2.16.840.1.113730.3.4.3

PostRead

Post Read Request Control, Object Identifier: 1.3.6.1.1.13.2

PreRead

Pre Read Request Control, Object Identifier: 1.3.6.1.1.13.1

ProxiedAuthV1

Proxied Authorization Request Control V1, Object Identifier: 2.16.840.1.113730.3.4.12

ProxiedAuth, ProxiedAuthV2

Proxied Authorization Request Control V2, Object Identifier: 2.16.840.1.113730.3.4.18

RealAttrsOnly, RealAttributesOnly

Real Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.17

RelaxRules

Relax Rules Request Control, Object Identifier: 1.3.6.1.4.1.4203.666.5.12

TreeDelete, SubTreeDelete

Subtree Delete Request Control, Object Identifier: 1.2.840.113556.1.4.805

Sort, ServerSideSort

Server Side Sort Request Control, Object Identifier: 1.2.840.113556.1.4.473

PagedResults, SimplePagedResults

Simple Paged Results Control, Object Identifier: 1.2.840.113556.1.4.319

SubEntries

Sub-Entries Request Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.1

TxnId, TransactionId

Transaction ID Control, Object Identifier: 1.3.6.1.4.1.36733.2.1.5.1

This is an internal ForgeRock control.

VirtualAttrsOnly, VirtualAttributesOnly

Virtual Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.19

Vlv, VirtualListView

Virtual List View Request Control, Object Identifier: 2.16.840.1.113730.3.4.9

-m | --useCompareResultCode

Use the LDAP compare result as an exit code for the LDAP compare operations.

Default: false

-n | --dry-run

Show what would be done but do not perform any operation and do not contact the server.

Default: false

-S | --scriptFriendly

Use script-friendly mode.

Default: false

-Y | --proxyAs {authzID}

Use the proxied authorization control with the given authorization ID.

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default:

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server port number.

-q | --useStartTls

Use StartTLS to secure communication with the server.

Default: false

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

-Z | --useSsl

Use SSL for secure communication with the server.

Default: false

Utility input/output options:

--no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-v | --verbose

Use verbose mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.13.4. Exit Codes

0

The command completed successfully.

5

The LDAP compare operation did not match.

6

The -m option was used, and the LDAP compare operation did match.

ldap-error

An LDAP error occurred while processing the operation.

LDAP result codes are described in RFC 4511. Also see the additional information for details.

89

An error occurred while parsing the command-line arguments.

11.13.5. Files

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

11.13.6. Examples

The following examples demonstrate comparing Babs Jensen's UID.

The following example uses a matching UID value:

$ ldapcompare -p 1389 uid:bjensen uid=bjensen,ou=people,dc=example,dc=com
Comparing type uid with value bjensen in entry
uid=bjensen,ou=people,dc=example,dc=com
Compare operation returned true for entry
uid=bjensen,ou=people,dc=example,dc=com

The following example uses a UID value that does not match:

$ ldapcompare -p 1389 uid:beavis uid=bjensen,ou=people,dc=example,dc=com
Comparing type uid with value beavis in entry
uid=bjensen,ou=people,dc=example,dc=com
Compare operation returned false for entry
uid=bjensen,ou=people,dc=example,dc=com

Chapter 11.14. ldapdelete — perform LDAP delete operations

11.14.1. Synopsis

ldapdelete {options} [DN]

11.14.2. Description

This utility can be used to perform LDAP delete operations in the Directory Server.

If standard input is used to specify entries to remove, end your input with EOF (Ctrl+D on UNIX, Ctrl+Z on Windows).

11.14.3. Options

The ldapdelete command takes the following options:

Command options:

-c | --continueOnError

Continue processing even if there are errors.

Default: false

-J | --control {controloid[:criticality[:value|::b64value|:<filePath]]}

Use a request control with the provided information.

For some controloid values, you can replace object identifiers with user-friendly strings. The values are not case-sensitive:

Assertion, LdapAssertion

Assertion Request Control, Object Identifier: 1.3.6.1.1.12

AccountUsable, AccountUsability

Account Usability Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.8

AuthzId, AuthorizationIdentity

Authorization Identity Request Control, Object Identifier: 2.16.840.1.113730.3.4.16

Csn, ChangeNumber, ChangeSequenceNumber

Change Sequence Number Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.9

This is an internal DS server control.

EffectiveRights, GetEffectiveRights

Get Effective Rights Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.2

ManageDsaIt

Manage DSAIT Request Control, Object Identifier: 2.16.840.1.113730.3.4.2

Noop, No-Op

No-Op Request Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.2

PwPolicy, PasswordPolicy

Password Policy Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.8.5.1

PermissiveModify

Permissive Modify Request Control, Object Identifier: 1.2.840.113556.1.4.1413

PSearch, PersistentSearch

Persistent Search Request Control, Object Identifier: 2.16.840.1.113730.3.4.3

PostRead

Post Read Request Control, Object Identifier: 1.3.6.1.1.13.2

PreRead

Pre Read Request Control, Object Identifier: 1.3.6.1.1.13.1

ProxiedAuthV1

Proxied Authorization Request Control V1, Object Identifier: 2.16.840.1.113730.3.4.12

ProxiedAuth, ProxiedAuthV2

Proxied Authorization Request Control V2, Object Identifier: 2.16.840.1.113730.3.4.18

RealAttrsOnly, RealAttributesOnly

Real Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.17

RelaxRules

Relax Rules Request Control, Object Identifier: 1.3.6.1.4.1.4203.666.5.12

TreeDelete, SubTreeDelete

Subtree Delete Request Control, Object Identifier: 1.2.840.113556.1.4.805

Sort, ServerSideSort

Server Side Sort Request Control, Object Identifier: 1.2.840.113556.1.4.473

PagedResults, SimplePagedResults

Simple Paged Results Control, Object Identifier: 1.2.840.113556.1.4.319

SubEntries

Sub-Entries Request Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.1

TxnId, TransactionId

Transaction ID Control, Object Identifier: 1.3.6.1.4.1.36733.2.1.5.1

This is an internal ForgeRock control.

VirtualAttrsOnly, VirtualAttributesOnly

Virtual Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.19

Vlv, VirtualListView

Virtual List View Request Control, Object Identifier: 2.16.840.1.113730.3.4.9

-n | --dry-run

Show what would be done but do not perform any operation and do not contact the server.

Default: false

--numConnections {numConnections}

Number of connections.

Default: 1

-x | --deleteSubtree

Delete the specified entry and all entries below it.

Default: false

-Y | --proxyAs {authzID}

Use the proxied authorization control with the given authorization ID.

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default:

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server port number.

-q | --useStartTls

Use StartTLS to secure communication with the server.

Default: false

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

-Z | --useSsl

Use SSL for secure communication with the server.

Default: false

Utility input/output options:

--no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-v | --verbose

Use verbose mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.14.4. Exit Codes

0

The command completed successfully.

ldap-error

An LDAP error occurred while processing the operation.

LDAP result codes are described in RFC 4511. Also see the additional information for details.

89

An error occurred while parsing the command-line arguments.

11.14.5. Files

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

11.14.6. Examples

The following command deletes a user entry from the directory:

$ ldapdelete -p 1389 -D "cn=Directory Manager" -w password \
 uid=bjensen,ou=people,dc=example,dc=com
Processing DELETE request for uid=bjensen,ou=people,dc=example,dc=com
DELETE operation successful for DN uid=bjensen,ou=people,dc=example,dc=com

The following command deletes the ou=Groups entry and all entries underneath ou=Groups:

$ ldapdelete -p 1389 -D "cn=Directory Manager" -w password -x \
 ou=groups,dc=example,dc=com
Processing DELETE request for ou=groups,dc=example,dc=com
DELETE operation successful for DN ou=groups,dc=example,dc=com

Chapter 11.15. ldapmodify — perform LDAP modify, add, delete, mod DN operations

11.15.1. Synopsis

ldapmodify {options} [changes_files ...]

11.15.2. Description

This utility can be used to perform LDAP modify, add, delete, and modify DN operations in the Directory Server. When not using file(s) to specify modifications, end your input with EOF (Ctrl+D on UNIX, Ctrl+Z on Windows).

11.15.3. Options

The ldapmodify command takes the following options:

Command options:

--assertionFilter {filter}

Use the LDAP assertion control with the provided filter.

-c | --continueOnError

Continue processing even if there are errors.

Default: false

-J | --control {controloid[:criticality[:value|::b64value|:<filePath]]}

Use a request control with the provided information.

For some controloid values, you can replace object identifiers with user-friendly strings. The values are not case-sensitive:

Assertion, LdapAssertion

Assertion Request Control, Object Identifier: 1.3.6.1.1.12

AccountUsable, AccountUsability

Account Usability Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.8

AuthzId, AuthorizationIdentity

Authorization Identity Request Control, Object Identifier: 2.16.840.1.113730.3.4.16

Csn, ChangeNumber, ChangeSequenceNumber

Change Sequence Number Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.9

This is an internal DS server control.

EffectiveRights, GetEffectiveRights

Get Effective Rights Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.2

ManageDsaIt

Manage DSAIT Request Control, Object Identifier: 2.16.840.1.113730.3.4.2

Noop, No-Op

No-Op Request Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.2

PwPolicy, PasswordPolicy

Password Policy Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.8.5.1

PermissiveModify

Permissive Modify Request Control, Object Identifier: 1.2.840.113556.1.4.1413

PSearch, PersistentSearch

Persistent Search Request Control, Object Identifier: 2.16.840.1.113730.3.4.3

PostRead

Post Read Request Control, Object Identifier: 1.3.6.1.1.13.2

PreRead

Pre Read Request Control, Object Identifier: 1.3.6.1.1.13.1

ProxiedAuthV1

Proxied Authorization Request Control V1, Object Identifier: 2.16.840.1.113730.3.4.12

ProxiedAuth, ProxiedAuthV2

Proxied Authorization Request Control V2, Object Identifier: 2.16.840.1.113730.3.4.18

RealAttrsOnly, RealAttributesOnly

Real Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.17

RelaxRules

Relax Rules Request Control, Object Identifier: 1.3.6.1.4.1.4203.666.5.12

TreeDelete, SubTreeDelete

Subtree Delete Request Control, Object Identifier: 1.2.840.113556.1.4.805

Sort, ServerSideSort

Server Side Sort Request Control, Object Identifier: 1.2.840.113556.1.4.473

PagedResults, SimplePagedResults

Simple Paged Results Control, Object Identifier: 1.2.840.113556.1.4.319

SubEntries

Sub-Entries Request Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.1

TxnId, TransactionId

Transaction ID Control, Object Identifier: 1.3.6.1.4.1.36733.2.1.5.1

This is an internal ForgeRock control.

VirtualAttrsOnly, VirtualAttributesOnly

Virtual Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.19

Vlv, VirtualListView

Virtual List View Request Control, Object Identifier: 2.16.840.1.113730.3.4.9

-n | --dry-run

Show what would be done but do not perform any operation and do not contact the server.

Default: false

--numConnections {numConnections}

Number of connections.

Default: 1

--postReadAttributes {attrList}

Use the LDAP ReadEntry post-read control.

--preReadAttributes {attrList}

Use the LDAP ReadEntry pre-read control.

-Y | --proxyAs {authzID}

Use the proxied authorization control with the given authorization ID.

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default:

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server port number.

-q | --useStartTls

Use StartTLS to secure communication with the server.

Default: false

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

-Z | --useSsl

Use SSL for secure communication with the server.

Default: false

Utility input/output options:

--no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-v | --verbose

Use verbose mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.15.4. Exit Codes

0

The command completed successfully.

ldap-error

An LDAP error occurred while processing the operation.

LDAP result codes are described in RFC 4511. Also see the additional information for details.

89

An error occurred while parsing the command-line arguments.

11.15.5. Files

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

11.15.6. Examples

The following example demonstrates use of the command to add an entry to the directory:

$ cat newuser.ldif
dn: uid=newuser,ou=People,dc=example,dc=com
uid: newuser
facsimileTelephoneNumber: +1 408 555 1213
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: top
givenName: New
cn: New User
cn: Real Name
telephoneNumber: +1 408 555 1212
sn: Jensen
roomNumber: 1234
homeDirectory: /home/newuser
uidNumber: 10389
mail: newuser@example.com
l: South Pole
ou: Product Development
ou: People
gidNumber: 10636

$ ldapmodify -p 1389 -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery newuser.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

The following listing shows a UNIX shell script that adds a user entry:

#!/bin/sh
#
# Add a new user with the ldapmodify utility.
#

usage(){
        echo "Usage: $0 uid firstname lastname"
        exit 1
}
[[ $# -lt 3 ]] && usage

LDAPMODIFY=/path/to/opendj/bin/ldapmodify
HOST=opendj.example.com
PORT=1389
ADMIN=uid=kvaughan,ou=people,dc=example,dc=com
PWD=bribery

$LDAPMODIFY -h $HOST -p $PORT -D $ADMIN -w $PWD <<EOF
dn: uid=$1,ou=people,dc=example,dc=com
uid: $1
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: $2 $3
givenName: $2
sn: $3
mail: $1@example.com
EOF

The following example demonstrates adding a description attribute to the new user's entry:

$ cat newdesc.ldif
dn: uid=newuser,ou=People,dc=example,dc=com
changetype: modify
add: description
description: A new user's entry

$ ldapmodify -p 1389 -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery newdesc.ldif
Processing MODIFY request for uid=newuser,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=newuser,ou=People,dc=example,dc=com

The following example demonstrates changing the description attribute for the new user's entry:

$ cat moddesc.ldif
dn: uid=newuser,ou=People,dc=example,dc=com
changetype: modify
replace: description
description: Another description

$ ldapmodify -p 1389 -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery moddesc.ldif
Processing MODIFY request for uid=newuser,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=newuser,ou=People,dc=example,dc=com

The following example demonstrates deleting the new user's entry:

$ cat deluser.ldif
dn: uid=newuser,ou=People,dc=example,dc=com
changetype: delete

$ ldapmodify -p 1389 -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery deluser.ldif
Processing DELETE request for uid=newuser,ou=People,dc=example,dc=com
DELETE operation successful for DN uid=newuser,ou=People,dc=example,dc=com

Chapter 11.16. ldappasswordmodify — perform LDAP password modifications

11.16.1. Synopsis

ldappasswordmodify {options}

11.16.2. Description

This utility can be used to perform LDAP password modify operations in the Directory Server.

11.16.3. Options

The ldappasswordmodify command takes the following options:

Command options:

-a | --authzId {authzID}

Authorization ID for the user entry whose password should be changed. The authorization ID is a string having either the prefix "dn:" followed by the user's distinguished name, or the prefix "u:" followed by a user identifier that depends on the identity mapping used to match the user identifier to an entry in the directory. Examples include "dn:uid=bjensen,ou=People,dc=example,dc=com", and, if we assume that "bjensen" is mapped to Barbara Jensen's entry, "u:bjensen".

-c | --currentPassword {currentPassword}

Current password for the target user.

-C | --currentPasswordFile {file}

Path to a file containing the current password for the target user.

-F | --newPasswordFile {file}

Path to a file containing the new password to provide for the target user.

-J | --control {controloid[:criticality[:value|::b64value|:<filePath]]}

Use a request control with the provided information.

For some controloid values, you can replace object identifiers with user-friendly strings. The values are not case-sensitive:

Assertion, LdapAssertion

Assertion Request Control, Object Identifier: 1.3.6.1.1.12

AccountUsable, AccountUsability

Account Usability Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.8

AuthzId, AuthorizationIdentity

Authorization Identity Request Control, Object Identifier: 2.16.840.1.113730.3.4.16

Csn, ChangeNumber, ChangeSequenceNumber

Change Sequence Number Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.9

This is an internal DS server control.

EffectiveRights, GetEffectiveRights

Get Effective Rights Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.2

ManageDsaIt

Manage DSAIT Request Control, Object Identifier: 2.16.840.1.113730.3.4.2

Noop, No-Op

No-Op Request Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.2

PwPolicy, PasswordPolicy

Password Policy Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.8.5.1

PermissiveModify

Permissive Modify Request Control, Object Identifier: 1.2.840.113556.1.4.1413

PSearch, PersistentSearch

Persistent Search Request Control, Object Identifier: 2.16.840.1.113730.3.4.3

PostRead

Post Read Request Control, Object Identifier: 1.3.6.1.1.13.2

PreRead

Pre Read Request Control, Object Identifier: 1.3.6.1.1.13.1

ProxiedAuthV1

Proxied Authorization Request Control V1, Object Identifier: 2.16.840.1.113730.3.4.12

ProxiedAuth, ProxiedAuthV2

Proxied Authorization Request Control V2, Object Identifier: 2.16.840.1.113730.3.4.18

RealAttrsOnly, RealAttributesOnly

Real Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.17

RelaxRules

Relax Rules Request Control, Object Identifier: 1.3.6.1.4.1.4203.666.5.12

TreeDelete, SubTreeDelete

Subtree Delete Request Control, Object Identifier: 1.2.840.113556.1.4.805

Sort, ServerSideSort

Server Side Sort Request Control, Object Identifier: 1.2.840.113556.1.4.473

PagedResults, SimplePagedResults

Simple Paged Results Control, Object Identifier: 1.2.840.113556.1.4.319

SubEntries

Sub-Entries Request Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.1

TxnId, TransactionId

Transaction ID Control, Object Identifier: 1.3.6.1.4.1.36733.2.1.5.1

This is an internal ForgeRock control.

VirtualAttrsOnly, VirtualAttributesOnly

Virtual Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.19

Vlv, VirtualListView

Virtual List View Request Control, Object Identifier: 2.16.840.1.113730.3.4.9

-n | --newPassword {newPassword}

New password to provide for the target user.

-Y | --proxyAs {authzID}

Use the proxied authorization control with the given authorization ID.

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default:

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server port number.

-q | --useStartTls

Use StartTLS to secure communication with the server.

Default: false

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

-Z | --useSsl

Use SSL for secure communication with the server.

Default: false

Utility input/output options:

--no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-v | --verbose

Use verbose mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.16.4. Exit Codes

0

The command completed successfully.

ldap-error

An LDAP error occurred while processing the operation.

LDAP result codes are described in RFC 4511. Also see the additional information for details.

89

An error occurred while parsing the command-line arguments.

11.16.5. Files

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

11.16.6. Examples

The following example demonstrates a user changing their own password:

$ cat /tmp/currpwd.txt /tmp/newpwd.txt
bribery
secret12

$ ldappasswordmodify -p 1389 -C /tmp/currpwd.txt --newPasswordFile /tmp/newpwd.txt \
 -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery
The LDAP password modify operation was successful

Chapter 11.17. ldapsearch — perform LDAP search operations

11.17.1. Synopsis

ldapsearch {options} filter [attributes ...]

11.17.2. Description

This utility can be used to perform LDAP search operations in the Directory Server.

11.17.3. Options

The ldapsearch command takes the following options:

Command options:

-a | --dereferencePolicy {dereferencePolicy}

Alias dereference policy ('never', 'always', 'search', or 'find').

Default: never

-A | --typesOnly

Only retrieve attribute names but not their values.

Default: false

--assertionFilter {filter}

Use the LDAP assertion control with the provided filter.

-b | --baseDn {baseDN}

Search base DN.

-c | --continueOnError

Continue processing even if there are errors.

Default: false

-C | --persistentSearch ps[:changetype[:changesonly[:entrychgcontrols]]]

Use the persistent search control.

A persistent search allows the client to continue receiving new results whenever changes are made to data that is in the scope of the search, thus using the search as a form of change notification.

The optional changetype setting defines the kinds of updates that result in notification. If you do not set the changetype, the default behavior is to send notifications for all updates.

add: Send notifications for LDAP add operations.
del, delete: Send notifications for LDAP delete operations.
mod, modify: Send notifications for LDAP modify operations.
moddn, modrdn, modifydn: Send notifications for LDAP modify DN (rename and move) operations.
all, any: Send notifications for all LDAP update operations.

The optional changesonly setting defines whether the server returns existing entries as well as changes.

true

Do not return existing entries, but instead only notifications about changes.

This is the default setting.

false

Also return existing entries.

The optional entrychgcontrols setting defines whether the server returns an Entry Change Notification control with each entry notification. The Entry Change Notification control provides additional information about the change that caused the entry to be returned by the search. In particular, it indicates the change type, the change number if available, and the previous DN if the change type was a modify DN operation.

true

Do request the Entry Change Notification control.

This is the default setting.

false

Do not request the Entry Change Notification control.

--countEntries

Count the number of entries returned by the server.

Default: false

-e | --getEffectiveRightsAttribute {attribute}

Specifies geteffectiverights control specific attribute list.

-g | --getEffectiveRightsAuthzId {authzID}

Use geteffectiverights control with the provided authzid.

-G | --virtualListView {before:after:index:count | before:after:value}

Use the virtual list view control to retrieve the specified results page.

-J | --control {controloid[:criticality[:value|::b64value|:<filePath]]}

Use a request control with the provided information.

For some controloid values, you can replace object identifiers with user-friendly strings. The values are not case-sensitive:

Assertion, LdapAssertion

Assertion Request Control, Object Identifier: 1.3.6.1.1.12

AccountUsable, AccountUsability

Account Usability Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.8

AuthzId, AuthorizationIdentity

Authorization Identity Request Control, Object Identifier: 2.16.840.1.113730.3.4.16

Csn, ChangeNumber, ChangeSequenceNumber

Change Sequence Number Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.9

This is an internal DS server control.

EffectiveRights, GetEffectiveRights

Get Effective Rights Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.2

ManageDsaIt

Manage DSAIT Request Control, Object Identifier: 2.16.840.1.113730.3.4.2

Noop, No-Op

No-Op Request Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.2

PwPolicy, PasswordPolicy

Password Policy Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.8.5.1

PermissiveModify

Permissive Modify Request Control, Object Identifier: 1.2.840.113556.1.4.1413

PSearch, PersistentSearch

Persistent Search Request Control, Object Identifier: 2.16.840.1.113730.3.4.3

PostRead

Post Read Request Control, Object Identifier: 1.3.6.1.1.13.2

PreRead

Pre Read Request Control, Object Identifier: 1.3.6.1.1.13.1

ProxiedAuthV1

Proxied Authorization Request Control V1, Object Identifier: 2.16.840.1.113730.3.4.12

ProxiedAuth, ProxiedAuthV2

Proxied Authorization Request Control V2, Object Identifier: 2.16.840.1.113730.3.4.18

RealAttrsOnly, RealAttributesOnly

Real Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.17

RelaxRules

Relax Rules Request Control, Object Identifier: 1.3.6.1.4.1.4203.666.5.12

TreeDelete, SubTreeDelete

Subtree Delete Request Control, Object Identifier: 1.2.840.113556.1.4.805

Sort, ServerSideSort

Server Side Sort Request Control, Object Identifier: 1.2.840.113556.1.4.473

PagedResults, SimplePagedResults

Simple Paged Results Control, Object Identifier: 1.2.840.113556.1.4.319

SubEntries

Sub-Entries Request Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.1

TxnId, TransactionId

Transaction ID Control, Object Identifier: 1.3.6.1.4.1.36733.2.1.5.1

This is an internal ForgeRock control.

VirtualAttrsOnly, VirtualAttributesOnly

Virtual Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.19

Vlv, VirtualListView

Virtual List View Request Control, Object Identifier: 2.16.840.1.113730.3.4.9

-l | --timeLimit {timeLimit}

Maximum length of time in seconds to allow for the search.

Default: 0

--matchedValuesFilter {filter}

Use the LDAP matched values control with the provided filter.

-n | --dry-run

Show what would be done but do not perform any operation and do not contact the server.

Default: false

-s | --searchScope {searchScope}

Search scope ('base', 'one', 'sub', or 'subordinates'). Note: 'subordinates' is an LDAP extension that might not work with all LDAP servers.

Default: sub

-S | --sortOrder {sortOrder}

Use the server side sort control to have the server sort the results using the provided sort order. You can provide multiple comma separated sort keys. Sort key must respect the following pattern: "[-] attributeType [:OrderingRuleNameOrOID]". Minus character represent a descending sort order.

--simplePageSize {numEntries}

Use the simple paged results control with the given page size.

Default: 1000

--subEntries

Use subentries control to specify that subentries are visible and normal entries are not.

Default: false

-Y | --proxyAs {authzID}

Use the proxied authorization control with the given authorization ID.

-z | --sizeLimit {sizeLimit}

Maximum number of entries to return from the search.

Default: 0

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default:

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server port number.

-q | --useStartTls

Use StartTLS to secure communication with the server.

Default: false

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

-Z | --useSsl

Use SSL for secure communication with the server.

Default: false

Utility input/output options:

--no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-t | --wrapColumn {wrapColumn}

Maximum length of an output line (0 for no wrapping).

Default: 0

-v | --verbose

Use verbose mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.17.4. Filters

The filter argument is a string representation of an LDAP search filter as in (cn=Babs Jensen), (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*))), or (cn:caseExactMatch:=Fred Flintstone).

11.17.5. Attributes

The optional attribute list specifies the attributes to return in the entries found by the search. In addition to identifying attributes by name such as cn sn mail and so forth, you can use the following notations, too.

*: Return all user attributes such as cn, sn, and mail.
+: Return all operational attributes such as etag and pwdPolicySubentry.
@objectclass: Return all attributes of the specified object class, where objectclass is one of the object classes on the entries returned by the search.
1.1: Return no attributes, only the DNs of matching entries.

11.17.6. Exit Codes

0

The command completed successfully.

ldap-error

An LDAP error occurred while processing the operation.

LDAP result codes are described in RFC 4511. Also see the additional information for details.

89

An error occurred while parsing the command-line arguments.

11.17.7. Files

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

11.17.8. Examples

The following example searches for entries with UID containing jensen, returning DNs and UIDs:

$ ldapsearch -p 1389 -b 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)

You can also use @objectclass notation in the attribute list to return the attributes of a particular object class. The following example shows how to return attributes of the inetOrgPerson object class:

$ ldapsearch -p 1389 -b dc=example,dc=com "(uid=bjensen)" @inetorgperson
dn: uid=bjensen,ou=People,dc=example,dc=com
givenName: Barbara
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: top
uid: bjensen
cn: Barbara Jensen
cn: Babs Jensen
telephoneNumber: +1 408 555 1862
sn: Jensen
roomNumber: 0209
mail: bjensen@example.com
l: San Francisco
ou: Product Development
ou: People
facsimileTelephoneNumber: +1 408 555 1992

You can use + in the attribute list to return all operational attributes, as in the following example:

$ ldapsearch -p 1389 -b dc=example,dc=com "(uid=bjensen)" +
dn: uid=bjensen,ou=People,dc=example,dc=com
numSubordinates: 0
structuralObjectClass: inetOrgPerson
etag: 0000000073c29972
subschemaSubentry: cn=schema
hasSubordinates: false
entryDN: uid=bjensen,ou=people,dc=example,dc=com
entryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c

Chapter 11.18. ldifdiff — compare small LDIF files

11.18.1. Synopsis

ldifdiff {options} source target

11.18.2. Description

This utility can be used to compare two LDIF files and report the differences in LDIF format.

If standard input is used to specify source or target, end your input with EOF (Ctrl+D on UNIX, Ctrl+Z on Windows).

11.18.3. Options

The ldifdiff command takes the following options:

Command options:

-B | --excludeBranch {branchDN}

Base DN of a branch to exclude when comparing entries.

-e | --excludeAttribute {attribute}

Attribute to ignore when comparing entries.

-o | --outputLdif {file}

Write differences to {file} instead of stdout.

Default: stdout

Utility input/output options:

-t | --wrapColumn {wrapColumn}

Maximum length of an output line (0 for no wrapping).

Default: 0

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.18.4. Exit Codes

0: No differences were found.
1: Differences were found.
other: An error occurred.

11.18.5. Examples

The following example demonstrates use of the command with two small LDIF files:

$ cat /path/to/newuser.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
mail: newuser@example.com
userPassword: changeme

$ cat /path/to/neweruser.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
mail: newuser@example.com
userPassword: secret12
description: A new description.

$ ldifdiff /path/to/newuser.ldif /path/to/neweruser.ldif
dn: uid=newuser,ou=People,dc=example,dc=com
changetype: modify
add: userPassword
userPassword: secret12
-
delete: userPassword
userPassword: changeme
-
add: description
description: A new description.

Chapter 11.19. ldifmodify — apply LDIF changes to LDIF

11.19.1. Synopsis

ldifmodify {options} source_file [changes_files...]

11.19.2. Description

This utility can be used to apply a set of modify, add, and delete operations to entries contained in an LDIF file.

If standard input is used to specify source or changes, end your input with EOF (Ctrl+D on UNIX, Ctrl+Z on Windows).

11.19.3. Options

The ldifmodify command takes the following options:

Command options:

-c | --continueOnError

Continue processing even if there are errors.

Default: false

-o | --outputLdif {file}

Write updated entries to {file} instead of stdout.

Default: stdout

Utility input/output options:

-t | --wrapColumn {wrapColumn}

Maximum length of an output line (0 for no wrapping).

Default: 0

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.19.4. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.19.5. Examples

The following example demonstrates use of the command:

$ cat /path/to/newuser.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
mail: newuser@example.com
userPassword: changeme

$ cat /path/to/newdiff.ldif
dn: uid=newuser,ou=People,dc=example,dc=com
changetype: modify
add: userPassword
userPassword: secret12
-
delete: userPassword
userPassword: changeme
-
add: description
description: A new description.

$ ldifmodify -o neweruser.ldif /path/to/newuser.ldif /path/to/newdiff.ldif

$ cat neweruser.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
mail: newuser@example.com
userPassword: secret12
description: A new description.

Chapter 11.20. ldifsearch — search LDIF with LDAP filters

11.20.1. Synopsis

ldifsearch {options} source filter [attributes ...]

11.20.2. Description

This utility can be used to perform search operations against entries contained in an LDIF file.

If standard input is used to specify source, end your input with EOF (Ctrl+D on UNIX, Ctrl+Z on Windows).

11.20.3. Options

The ldifsearch command takes the following options:

Command options:

-A | --typesOnly

Only retrieve attribute names but not their values.

Default: false

-b | --baseDn {baseDN}

The base DN for the search. If no base DN is provided, then the root DSE will be used.

Default:

-l | --timeLimit {timeLimit}

Maximum length of time in seconds to allow for the search.

Default: 0

-o | --outputLdif {file}

Write search results to {file} instead of stdout.

Default: stdout

-s | --searchScope {searchScope}

Search scope ('base', 'one', 'sub', or 'subordinates'). Note: 'subordinates' is an LDAP extension that might not work with all LDAP servers.

Default: sub

-z | --sizeLimit {sizeLimit}

Maximum number of entries to return from the search.

Default: 0

Utility input/output options:

-t | --wrapColumn {wrapColumn}

Maximum length of an output line (0 for no wrapping).

Default: 0

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.20.4. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.20.5. Examples

The following example demonstrates use of the command:

$ ldifsearch -b dc=example,dc=com Example.ldif uid=bjensen
dn: uid=bjensen,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: top
uid: bjensen
userpassword: hifalutin
facsimiletelephonenumber: +1 408 555 1992
givenname: Barbara
cn: Barbara Jensen
cn: Babs Jensen
telephonenumber: +1 408 555 1862
sn: Jensen
roomnumber: 0209
homeDirectory: /home/bjensen
mail: bjensen@example.com
l: San Francisco
ou: Product Development
ou: People
uidNumber: 1076
gidNumber: 1000

Chapter 11.21. makeldif — generate test LDIF

11.21.1. Synopsis

makeldif {options} template-file-path

11.21.2. Description

This utility can be used to generate LDIF data based on a definition in a template file.

The template-file-path can be one of the following:

A full path to the template file such as /path/to/opendj/config/MakeLDIF/example.template.
A relative path to the template file such as ../../my-test-data.template.
A file name that specifies one of the template files, such as example.template, or people_and_groups.template.

The following default template and data files are provided:

cities: List of more than 200 cities.
example.template: Template to generate a base entry and users in a branch ou=people,[suffix], where the default setting for suffix is suffix=dc=example,dc=com.
first.names: List of more than 8000 first names.
last.names: List of more than 13000 last names.
people_and_groups.template: Template to generate a base entry, users, and groups.
states: List of US states by their two-character codes.
streets: List of more than 70 street names.

11.21.3. Options

The makeldif command takes the following options:

Command options:

-c | --constant {name=value}

A constant that overrides the value set in the template file.

-o | --outputLdif {file}

The path to the LDIF file to be written. If the filename ends in .gz, the output will be gzipped.

-r | --resourcePath {path}

Path to look for MakeLDIF resources (e.g., data files).

The utility looks for resources in the following locations in this order:

The current directory where the command is run.
The resource path directory.
The built-in files.

-s | --randomSeed {seed}

The seed to use to initialize the random number generator.

Default: 0

Utility input/output options:

-t | --wrapColumn {wrapColumn}

Maximum length of an output line (0 for no wrapping).

Default: 0

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.21.4. Exit Codes

0: The command completed successfully.
1: An error occurred.

11.21.5. Examples

The following example uses the default template to generate LDIF:

$ makeldif -o ../ldif/generated.ldif ../config/MakeLDIF/example.template
Processed 1000 entries
Processed 2000 entries
...
Processed 10000 entries
LDIF processing complete.  10003 entries written

11.21.6. See Also

"makeldif.template — template file for the makeldif command"

Chapter 11.22. makeldif.template — template file for the makeldif command

11.22.1. Synopsis

# Comment lines start with #.
#
# Notice that this synopsis includes blank lines after entries.
# In the same way you would use blank lines after entries in normal LDIF,
# leave empty lines after "entries" in template files.

# Optionally define constants used in the template.
# To reference constants later, put brackets around the name: [constant-name]
#
define constant-name=value
...

# Define branches by suffix DN, such as the following:
#
#  dc=example,dc=com
#  ou=People,dc=example,dc=com
#  ou=Groups,dc=example,dc=com
#
# makeldif generates the necessary object class definitions and RDNs.
#
# A branch can have subordinateTemplates that define templates to use for
# the branch entry. The optional number at the end
# of the subordinateTemplate specification defines how many entries to generate.
# If you do not specify a number, makeldif continues to generate entries
# indefinitely until you interrupt the command.
#
# A branch can have additional attributes generated on the branch entry. See
# the Description below for more information on specifying attribute values.
#
branch: suffix-dn
objectClass: top
objectClass: suffix-object-class
[subordinateTemplate: template-name[:number]
...]
[attribute: attr-value
...]

...

# Define entries using templates.
#
# A template can extend another template.
# A template defines the RDN attribute(s) used for generated entries.
# A template can have a subordinateTemplate that defines a template to use for
# the generated entries.
#
# A template then defines attributes. See the Description below for more
# information on specifying attribute values.
#
template: template-name
[extends: template-name]
rdnAttr: attribute[+attribute ...]
[subordinateTemplate: template-name:number]
[attribute: attr-value
...]

...

11.22.2. Description

Template files specify how to build LDIF. They allow you to define variables, insert random values from other files, and generally build arbitrarily large LDIF files for testing purposes. You pass template files to the makeldif command when generating LDIF.

The Synopsis above shows the layout for a makeldif template file. This section focuses on what you can do to specify entry attribute values, called attr-value in the Synopsis section.

Specifying Attribute Values

When specifying attribute values in makeldif templates, you can use static text and constants that you have defined, enclosing names for constants in brackets, [myConstant]. You can use more than one constant per line, as in the following example:

description: Description for [org] under [suffix]

You can also use two kinds of tags when specifying attribute values. One kind of tag is replaced with the value of another attribute in the generated entry. Such tags are delimited with braces, { }. For example, if your template includes definitions for first name and last name attributes, use:

givenName: <first>
sn: <last>

Then you can define a mail attribute that uses the values of both attributes, and an initials attribute that takes the first character of each:

mail: {givenName}.{sn}@[myDomain]
initials: {givenName:1}{sn:1}

The other kind of tag is delimited with < and >, as shown above in the example with <first> and <last>. Tag names are not case sensitive. Many tags can take arguments separated by colons, :, from the tag names within the tag.

Use backslashes to escape literal start tag characters (< [ {) as shown in the following example, and to escape literal end tag characters within tags (> ] }):

scimMail: \{"emails": \[\{"value": "{mail}", "type": "work", "primary": true}]}
xml: \<id>{uid}\</id>

The makeldif command supports the following tags:

<DateTime>

The DateTime tag is replaced by a timestamp.

The DateTime tag takes the form <DateTime[:offsetInSeconds[:formatString]]>, where:

offsetInSeconds is the offset in seconds from the current time.
The offset may be a positive or negative integer.
Default: 0 (seconds).
formatString is a date time pattern string. For details, see the Javadoc for the DateTimeFormat class.
Default: yyyyMMddHHmmss.SSS'Z'.

<DN>

The DN tag is replaced by the distinguished name of the current entry. An optional integer argument specifies the subcomponents of the DN to generate. For example, if the DN of the entry is uid=bjensen,ou=People,dc=example,dc=com, then <DN:1> is replaced by uid=bjensen, and <DN:-2> is replaced by dc=example,dc=com.

<File>

The File tag is replaced by a line from a text file you specify. The File tag takes a required argument, the path to the text file, and an optional second argument, either random or sequential. For the file argument, either specify an absolute path to the file such as <file:/path/to/myDescriptions>, or specify a path relative to the template file such as <file:streets>. For the second argument, if you specify sequential then lines from the file are read in sequential order. Otherwise, lines from the file are read in random order.

<First>

The first name tag is replaced by a random line from first.names. Combinations of generated first and last names are unique, with integers appended to the name strings if not enough combinations are available.

<GUID>

The GUID tag is replaced by a 128-bit, type 4 (random) universally unique identifier, such as f47ac10b-58cc-4372-a567-0e02b2c3d479.

<IfAbsent>

The IfAbsent tag takes as its first argument the name of another attribute, and optionally, as its second argument, a value to use. This tag causes the attribute to be generated only if the named attribute is not present on the generated entry. Use this tag when you have used <Presence> to define another attribute that is not always present on generated entries.

<IfPresent>

The IfPresent takes as its first argument the name of another attribute, and optionally, as its second argument, a value to use. This tag causes the attribute to be generated only if the named attribute is also present on the generated entry. Use this tag when you have used <Presence> to define another attribute that is sometimes present on generated entries.

<Last>

The last name tag is replaced by a random line from the last names template file, last.names. Combinations of generated first and last names are unique, with integers appended to the name strings if not enough combinations are available.

<List>

The List tag is replaced by one of the values from the list of arguments you provide. For example, <List:bronze:silver:gold> is replaced with bronze, silver, or gold.

You can weight arguments to ensure that some arguments are selected more often than others. For example, if you want two bronze for one silver and one gold, use <List:bronze;2:silver;1:gold;1>.

<ParentDN>

The ParentDN tag is replaced by the distinguished name of the parent entry. For example, if the DN of the entry is uid=bjensen,ou=People,dc=example,dc=com, <ParentDN> is replaced by ou=People,dc=example,dc=com.

<Presence>

The Presence tag takes a percent argument. It results in the attribute value being generated or not based on the percentage of entries you specify in the argument. For example, description: <Presence:50>A description generates description: A description on half the entries.

<Random>

The Random tag lets you generate a variety of random numbers and strings. The Random tag has the following subtypes, which you include as arguments, that is <Random:subtype>:

alpha:length
alpha:min-length:max-length
numeric:length
numeric:minvalue:maxvalue
numeric:minvalue:maxvalue:format, where format is a java.text.DecimalFormat pattern
alphanumeric:length
alphanumeric:min-length:max-length
chars:characters:length
chars:characters:min-length:max-length
hex:length
hex:min-length:max-length
base64:length
base64:min-length:max-length
month
month:max-length
telephone, a telephone number starting with the country code +1

<RDN>

The RDN tag is replaced with the RDN of the entry. Use this in the template after you have specified rdnAttr so that the RDN has already been generated when this tag is replaced.

An optional integer argument specifies the subcomponents of the RDN to generate.

<Sequential>

The Sequential tag is replaced by a sequentially increasing generated integer. The first optional integer argument specifies the starting number. The second optional boolean argument specifies whether to start over when generating entries for a new parent entry. For example, <Sequential>:42:true starts counting from 42, and starts over when the parent entry changes from o=Engineering to o=Marketing.

<_DN>

The _DN tag is replaced by the DN of the current entry with underscores in the place of commas.

<_ParentDN>

The _ParentDN tag is replaced by the DN the parent entry with underscores in the place of commas.

11.22.3. Examples

The following example generates 10 organization units, each containing 50 entries. Add it next to the supporting files, such as first.names and last.names needed to generate the output:

define suffix=dc=example,dc=com
define maildomain=example.com
define numusers=50
define numorgs=10

branch: [suffix]
objectClass: top
objectClass: domain

branch: ou=People,[suffix]
objectClass: top
objectClass: organizationalUnit
subordinateTemplate: orgunit:[numorgs]
description: This is the People container
telephoneNumber: +33 00010002

template: orgunit
subordinateTemplate: person:[numusers]
rdnAttr: ou
ou: Org-<sequential:0>
objectClass: top
objectClass: organizationalUnit
description: This is the {ou} organizational unit

template: person
rdnAttr: uid
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
givenName: <first>
sn: <last>
cn: {givenName} {sn}
initials: {givenName:1}<random:chars:ABCDEFGHIJKLMNOPQRSTUVWXYZ:1>{sn:1}
employeeNumber: <sequential:0>
uid: user.{employeeNumber}
mail: {uid}@[maildomain]
userPassword: password
telephoneNumber: <random:telephone>
homePhone: <random:telephone>
pager: <random:telephone>
mobile: <random:telephone>
street: <random:numeric:5> <file:streets> Street
l: <file:cities>
st: <file:states>
postalCode: <random:numeric:5>
postalAddress: {cn}${street}${l}, {st}  {postalCode}
description: This is the description for {cn}.

11.22.4. See Also

"makeldif — generate test LDIF", the server template file config/MakeLDIF/example.template

Chapter 11.23. manage-account — manage state of OpenDJ server accounts

11.23.1. Synopsis

manage-account {subcommand} {options}

11.23.2. Description

This utility can be used to retrieve and manipulate the values of password policy state variables.

11.23.3. Options

The manage-account command takes the following options:

Command options:

-b | --targetDn {targetDN}: The DN of the user entry for which to get and set password policy state information.

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default: cn=Directory Manager

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

Utility input/output options:

-n | --no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

-v | --verbose

Use verbose mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.23.4. Subcommands

The manage-account command supports the following subcommands:

11.23.4.1. manage-account add-authentication-failure-time

Add an authentication failure time to the user account. This should be used only for testing purposes.

11.23.4.1.1. Options

The manage-account add-authentication-failure-time command takes the following options:

-O | --operationValue {time}: A timestamp value using the generalized time syntax. Multiple timestamp values may be given by providing this argument multiple times.

11.23.4.2. manage-account add-grace-login-use-time

Add a grace login use time to the user account. This should be used only for testing purposes.

11.23.4.3. manage-account clear-account-expiration-time

Clear account expiration time information from the user account.

11.23.4.4. manage-account clear-account-is-disabled

Clear account disabled state information from the user account.

11.23.4.5. manage-account clear-authentication-failure-times

Clear authentication failure time information from the user's account. This should be used only for testing purposes.

11.23.4.8. manage-account clear-password-changed-by-required-time

Clear information about the required password change time with which the user last complied. This should be used only for testing purposes.

11.23.4.9. manage-account clear-password-changed-time

Clear information about the time that the user's password was last changed. This should be used only for testing purposes.

11.23.4.10. manage-account clear-password-expiration-warned-time

Clear information about the time that the user first received an expiration warning notice. This should be used only for testing purposes.

11.23.4.11. manage-account clear-password-history

Clear password history state values for the user. This should be used only for testing purposes.

11.23.4.12. manage-account clear-password-is-reset

Clear information about whether the user will be required to change his or her password on the next successful authentication. This should be used only for testing purposes.

11.23.4.13. manage-account get-account-expiration-time

Display when the user account will expire.

11.23.4.14. manage-account get-account-is-disabled

Display information about whether the user account has been administratively disabled.

11.23.4.15. manage-account get-all

Display all password policy state information for the user.

11.23.4.16. manage-account get-authentication-failure-times

Display the authentication failure times for the user.

11.23.4.19. manage-account get-password-changed-by-required-time

Display the required password change time with which the user last complied.

11.23.4.20. manage-account get-password-changed-time

Display the time that the user's password was last changed.

11.23.4.21. manage-account get-password-expiration-warned-time

Display the time that the user first received an expiration warning notice.

11.23.4.22. manage-account get-password-is-reset

Display information about whether the user will be required to change his or her password on the next successful authentication.

11.23.4.23. manage-account get-password-policy-dn

Display the DN of the password policy for the user.

11.23.4.24. manage-account get-remaining-authentication-failure-count

Display the number of remaining authentication failures until the user's account is locked.

11.23.4.26. manage-account get-seconds-until-account-expiration

Display the length of time in seconds until the user account expires.

11.23.4.27. manage-account get-seconds-until-authentication-failure-unlock

Display the length of time in seconds until the authentication failure lockout expires.

11.23.4.28. manage-account get-seconds-until-idle-lockout

Display the length of time in seconds until user's account is locked because it has remained idle for too long.

11.23.4.29. manage-account get-seconds-until-password-expiration

Display length of time in seconds until the user's password expires.

11.23.4.30. manage-account get-seconds-until-password-expiration-warning

Display the length of time in seconds until the user should start receiving password expiration warning notices.

11.23.4.31. manage-account get-seconds-until-password-reset-lockout

Display the length of time in seconds until user's account is locked because the user failed to change the password in a timely manner after an administrative reset.

11.23.4.32. manage-account get-seconds-until-required-change-time

Display the length of time in seconds that the user has remaining to change his or her password before the account becomes locked due to the required change time.

11.23.4.33. manage-account set-account-expiration-time

Specify when the user account will expire.

11.23.4.33.1. Options

The manage-account set-account-expiration-time command takes the following options:

-O | --operationValue {time}: A timestamp value using the generalized time syntax.

11.23.4.34. manage-account set-account-is-disabled

Specify whether the user account has been administratively disabled.

11.23.4.34.1. Options

The manage-account set-account-is-disabled command takes the following options:

-O | --operationValue {true|false}: 'true' to indicate that the account is disabled, or 'false' to indicate that it is not disabled.

11.23.4.35. manage-account set-authentication-failure-times

Specify the authentication failure times for the user. This should be used only for testing purposes.

11.23.4.35.1. Options

The manage-account set-authentication-failure-times command takes the following options:

-O | --operationValue {time}: A timestamp value using the generalized time syntax. Multiple timestamp values may be given by providing this argument multiple times.

11.23.4.36. manage-account set-grace-login-use-times

Specify the grace login use times for the user. This should be used only for testing purposes.

11.23.4.37. manage-account set-last-login-time

Specify the time that the user last authenticated to the server. This should be used only for testing purposes.

11.23.4.38. manage-account set-password-changed-by-required-time

Specify the required password change time with which the user last complied. This should be used only for testing purposes.

11.23.4.38.1. Options

The manage-account set-password-changed-by-required-time command takes the following options:

-O | --operationValue {time}: A timestamp value using the generalized time syntax.

11.23.4.39. manage-account set-password-changed-time

Specify the time that the user's password was last changed. This should be used only for testing purposes.

11.23.4.39.1. Options

The manage-account set-password-changed-time command takes the following options:

-O | --operationValue {time}: A timestamp value using the generalized time syntax.

11.23.4.40. manage-account set-password-expiration-warned-time

Specify the time that the user first received an expiration warning notice. This should be used only for testing purposes.

11.23.4.40.1. Options

The manage-account set-password-expiration-warned-time command takes the following options:

-O | --operationValue {time}: A timestamp value using the generalized time syntax.

11.23.4.41. manage-account set-password-is-reset

Specify whether the user will be required to change his or her password on the next successful authentication. This should be used only for testing purposes.

11.23.4.41.1. Options

The manage-account set-password-is-reset command takes the following options:

-O | --operationValue {true|false}: 'true' to indicate that the account is disabled, or 'false' to indicate that it is not disabled.

11.23.5. Exit Codes

0: The command completed successfully.
89: An error occurred while parsing the command-line arguments.

11.23.6. Examples

For the following examples the administrator, 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 have all access"; allow(all)
  groupdn = "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)

The following command disables a user account:

$ manage-account -p 4444 -D "uid=kvaughan,ou=people,dc=example,dc=com" \
 -w bribery set-account-is-disabled -O true \
 -b uid=bjensen,ou=people,dc=example,dc=com -X
Account Is Disabled:  true

The following command enables a disabled user account:

$ manage-account -p 4444 -D "uid=kvaughan,ou=people,dc=example,dc=com" \
 -w bribery clear-account-is-disabled \
 -b uid=bjensen,ou=people,dc=example,dc=com -X
Account Is Disabled:  false

Chapter 11.24. manage-tasks — manage server administration tasks

11.24.1. Synopsis

manage-tasks {options}

11.24.2. Description

This utility can be used to obtain a list of tasks scheduled to run within the Directory Server as well as information about individual tasks.

11.24.3. Options

The manage-tasks command takes the following options:

Command options:

-c | --cancel {taskID}

ID of a particular task to cancel.

-i | --info {taskID}

ID of a particular task about which this tool will display information.

-s | --summary

Print a summary of tasks.

Default: false

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default: cn=Directory Manager

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

Utility input/output options:

-n | --no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.24.4. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.24.5. Examples

The following example demonstrates use of the command with a server that does daily backups at 2:00 AM:

$ manage-tasks -p 4444 -h opendj.example.com -D "cn=Directory Manager" -w password -s

  ID                                Type    Status
  ---------------------------------------------------------------
  example-backup                    Backup  Recurring
  example-backup-<backupId>         Backup  Waiting on start time

Chapter 11.25. modrate — measure modification throughput and response time

11.25.1. Synopsis

modrate {options} [(attribute:value template string) ...]

11.25.2. Description

This utility can be used to measure modify throughput and response time of a directory service using user-defined modifications.

Example:

modrate -p 1389 -D 'cn=directory manager' -w password \

-F -c 4 -t 4 -b 'uid=user.{1},ou=people,dc=example,dc=com' \

-g 'rand(0,2000)' -g 'randstr(16)' 'description:{2}'

Before trying the example, import 2000 randomly generated users.

When you do not use the -f option to keep connections open and rebind on the connections, the tool can exhaust its available ports, causing the tool to crash. You can work around this problem on test systems by changing TCP settings on the system.

For example, on Linux systems, set the following parameters in the /etc/sysctl.conf file:

net.ipv4.tcp_fin_timeout = 30
net.ipv4.tcp_tw_recycle = 1
net.ipv4.tcp_tw_reuse = 1

The parameter net.ipv4.tcp_fin_timeout sets the length of time in seconds to wait for a final FIN packet before forcing a close of the socket. The default is 60 (seconds).

The parameter net.ipv4.tcp_tw_recycle enables fast recycling of TIME_WAIT sockets. The default is 0 (false). Enabling this can cause Network Address Translation (NAT) issues.

The parameter net.ipv4.tcp_tw_reuse enables reuse of TIME_WAIT sockets for new connections. The default is 0 (false).

These settings are recommended only for testing, and not for production systems.

After making the changes to /etc/sysctl.conf, reload the configuration with the sysctl command:

# sysctl -p

11.25.3. Options

The modrate command takes the following options:

Command options:

-b | --targetDn {targetDN}

Target entry DN template string.

-B | --warmUpDuration {warmUpDuration}

Warm up duration in seconds.

Default: 0

-c | --numConnections {numConnections}

Number of connections.

Default: 1

-d | --maxDuration {maxDuration}

Maximum duration in seconds, 0 for unlimited.

Default: 0

-e | --percentile {percentile}

Calculate max response time for a percentile of operations.

-f | --keepConnectionsOpen

Keep connections open.

Default: false

-F | --noRebind

Keep connections open and do not rebind.

Default: false

-g | --argument {generator function or static string}

Argument used to evaluate the template strings in program parameters (ie. Base DN, Search Filter). The set of all arguments provided form the argument list in order. Besides static string arguments, they can be generated per iteration with the following functions:

"inc({filename})" Consecutive, incremental line from file

"inc({min},{max})" Consecutive, incremental number

"rand({filename})" Random line from file

"rand({min},{max})" Random number

"randstr({length},_charSet_)" Random string of specified length and optionally from characters in the charSet string. A range of character can be specified with [start-end] charSet notation. If no charSet is specified, the default charSet of [A-Z][a-z][0-9] will be used.

-i | --statInterval {statInterval}

Display results each specified number of seconds.

Default: 5

-m | --maxIterations {maxIterations}

Max iterations, 0 for unlimited.

Default: 0

-M | --targetThroughput {targetThroughput}

Target average throughput to achieve.

Default: 0

-S | --scriptFriendly

Use script-friendly mode.

Default: false

-t | --numConcurrentRequests {numConcurrentRequests}

Number of concurrent requests per connection.

Default: 1

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default:

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server port number.

-q | --useStartTls

Use StartTLS to secure communication with the server.

Default: false

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

-Z | --useSsl

Use SSL for secure communication with the server.

Default: false

Utility input/output options:

-n | --no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-v | --verbose

Use verbose mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.25.4. Exit Codes

0: The command completed successfully.
89: An error occurred while parsing the command-line arguments.

11.25.5. Examples

The following example uses the modrate command to write random 16-character description values to user entries:

$ modrate -p 1389 -D "cn=Directory Manager" -w password -F -c 4 -t 4 \
 -b "uid=user.{1},ou=people,dc=example,dc=com" -g "rand(0,2000)" \
 -g "randstr(16)" 'description:{2}'
-------------------------------------------------------------------------------
|     Throughput    |                 Response Time                |          |
|    (ops/second)   |                (milliseconds)                |          |
|   recent  average |   recent  average    99.9%   99.99%  99.999% |  err/sec |
-------------------------------------------------------------------------------
|  11616.6  11616.6 |    1.360    1.360    21.23   156.24   484.44 |      0.0 |
|  38501.4  25059.0 |    0.410    0.630    14.29   155.19   484.44 |      0.0 |
|  47660.4  32592.8 |    0.331    0.484    10.94    28.05   350.22 |      0.0 |
|  46837.2  36153.9 |    0.337    0.437     9.37    23.07   270.53 |      0.0 |
|  41042.0  37131.5 |    0.385    0.425     8.59    27.00   329.25 |      0.0 |
|  46397.0  38675.8 |    0.340    0.408     7.63    22.02   329.25 |      0.0 |
^C

Chapter 11.26. rebuild-index — rebuild index after configuration change

11.26.1. Synopsis

rebuild-index {options}

11.26.2. Description

This utility can be used to rebuild index data within an indexed backend database.

11.26.3. Options

The rebuild-index command takes the following options:

Command options:

-b | --baseDn {baseDN}

Base DN of a backend supporting indexing. Rebuild is performed on indexes within the scope of the given base DN.

--clearDegradedState

Indicates that indexes do not need rebuilding because they are known to be empty and forcefully marks them as valid. This is an advanced option which must only be used in cases where a degraded index is known to be empty and does not therefore need rebuilding. This situation typically arises when an index is created for an attribute which has just been added to the schema.

Default: false

-i | --index {index}

Names of index(es) to rebuild. For an attribute index this is simply an attribute name. At least one index must be specified for rebuild. Cannot be used with the "--rebuildAll" option.

--offline

Indicates that the command must be run in offline mode.

Default: false

--rebuildAll

Rebuild all indexes, including any DN2ID, DN2URI, VLV and extensible indexes. Cannot be used with the "-i" option or the "--rebuildDegraded" option.

Default: false

--rebuildDegraded

Rebuild all degraded indexes, including any DN2ID, DN2URI, VLV and extensible indexes. Cannot be used with the "-i" option or the "--rebuildAll" option.

Default: false

--tmpDirectory {directory}

Path to temporary directory for index scratch files during index rebuilding.

Default: import-tmp

Task Scheduling Options

--completionNotify {emailAddress}

Email address of a recipient to be notified when the task completes. This option may be specified more than once.

--dependency {taskID}

ID of a task upon which this task depends. A task will not start execution until all its dependencies have completed execution.

--errorNotify {emailAddress}

Email address of a recipient to be notified if an error occurs when this task executes. This option may be specified more than once.

--failedDependencyAction {action}

Action this task will take should one if its dependent tasks fail. The value must be one of PROCESS,CANCEL,DISABLE. If not specified defaults to CANCEL.

--recurringTask {schedulePattern}

Indicates the task is recurring and will be scheduled according to the value argument expressed in crontab(5) compatible time/date pattern.

The schedule pattern for a recurring task supports only the following crontab features:

Time and Date Fields

Field	Allowed Values
minute	0-59
hour	0-23
day of month	1-31
month	1-12 (or names)
day of week	0-7 (0 or 7 is Sunday, or use names)

A field can contain an asterisk, *. An asterisk stands for first-last.

Fields can include ranges of numbers. A range is two numbers separated by a hyphen, and is inclusive. For example, 8-10 for an "hour" field means execution at hours 8, 9, and 10.

Fields can include lists. A list is a set of numbers or ranges separated by commas. For example, 4,8-10 for an "hour" field means execution at hours 4, 8, 9, and 10.

When using names for in "month" or "day of week" fields, use the first three letters of the particular month or day of the week. Case does not matter. Ranges and lists of names are not supported.

-t | --start {startTime}

Indicates the date/time at which this operation will start when scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC time or YYYYMMDDhhmmss for local time. A value of '0' will cause the task to be scheduled for immediate execution. When this option is specified the operation will be scheduled to start at the specified time after which this utility will exit immediately.

Task Backend Connection Options

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default: cn=Directory Manager

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

Utility input/output options:

-n | --no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.26.4. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.26.5. Examples

The following example schedules a task to start immediately that rebuilds the cn (common name) index:

$ rebuild-index -p 4444 -h opendj.example.com -D "cn=Directory Manager" \
 -w password -b dc=example,dc=com -i cn -t 0
Rebuild Index task <taskId> scheduled to start <date>

Chapter 11.27. restore — restore directory data backups

11.27.1. Synopsis

restore {options}

11.27.2. Description

This utility can be used to restore a backup of a Directory Server backend.

11.27.3. Options

The restore command takes the following options:

Command options:

-d | --backupDirectory {backupDir}

Path to the directory containing the backup file(s).

-I | --backupId {backupID}

Backup ID of the backup to restore.

-l | --listBackups

List available backups in the backup directory.

Default: false

-n | --dry-run

Verify the contents of the backup but do not restore it.

Default: false

--offline

Indicates that the command must be run in offline mode.

Default: false

Task Scheduling Options

--completionNotify {emailAddress}

Email address of a recipient to be notified when the task completes. This option may be specified more than once.

--dependency {taskID}

ID of a task upon which this task depends. A task will not start execution until all its dependencies have completed execution.

--errorNotify {emailAddress}

Email address of a recipient to be notified if an error occurs when this task executes. This option may be specified more than once.

--failedDependencyAction {action}

Action this task will take should one if its dependent tasks fail. The value must be one of PROCESS,CANCEL,DISABLE. If not specified defaults to CANCEL.

--recurringTask {schedulePattern}

Indicates the task is recurring and will be scheduled according to the value argument expressed in crontab(5) compatible time/date pattern.

The schedule pattern for a recurring task supports only the following crontab features:

Time and Date Fields

Field	Allowed Values
minute	0-59
hour	0-23
day of month	1-31
month	1-12 (or names)
day of week	0-7 (0 or 7 is Sunday, or use names)

A field can contain an asterisk, *. An asterisk stands for first-last.

Fields can include ranges of numbers. A range is two numbers separated by a hyphen, and is inclusive. For example, 8-10 for an "hour" field means execution at hours 8, 9, and 10.

Fields can include lists. A list is a set of numbers or ranges separated by commas. For example, 4,8-10 for an "hour" field means execution at hours 4, 8, 9, and 10.

When using names for in "month" or "day of week" fields, use the first three letters of the particular month or day of the week. Case does not matter. Ranges and lists of names are not supported.

-t | --start {startTime}

Indicates the date/time at which this operation will start when scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC time or YYYYMMDDhhmmss for local time. A value of '0' will cause the task to be scheduled for immediate execution. When this option is specified the operation will be scheduled to start at the specified time after which this utility will exit immediately.

Task Backend Connection Options

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default: cn=Directory Manager

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

Utility input/output options:

--no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.27.4. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.27.5. Examples

The following example schedules a restore as a task to begin immediately while the server is online:

$ restore -p 4444 -D "cn=Directory Manager" -w password -d /backups -I <backupId> -t 0
Restore task <taskId> scheduled to start <date>

The following example restores data while the server is offline:

$ stop-ds
Stopping Server...

$ restore --backupDirectory /backups/userRoot --listBackups --offline
Backup ID:          <backupId>
Backup Date:        <date>
Is Incremental:     false
Is Compressed:      false
Is Encrypted:       false
Has Unsigned Hash:  false
Has Signed Hash:    false
Dependent Upon:     none

$ restore --backupDirectory /path/to/opendj/bak/userRoot --backupID <backupId> --offline
... msg=Restored: 00000000.jdb (size 355179)

$ start-ds
... The Directory Server has started successfully

Chapter 11.28. searchrate — measure search throughput and response time

11.28.1. Synopsis

searchrate {options} [filter template string] [attributes ...]

11.28.2. Description

This utility can be used to measure search throughput and response time of a directory service using user-defined searches.

Example:

searchrate -p 1389 -D 'cn=directory manager' -w password \

-F -c 4 -t 4 -b 'dc=example,dc=com' -g 'rand(0,2000)' '(uid=user.{})'

Before trying the example, import 2000 randomly generated users.

When you do not use the -f option to keep connections open and rebind on the connections, the tool can exhaust its available ports, causing the tool to crash. You can work around this problem on test systems by changing TCP settings on the system.

For example, on Linux systems, set the following parameters in the /etc/sysctl.conf file:

net.ipv4.tcp_fin_timeout = 30
net.ipv4.tcp_tw_recycle = 1
net.ipv4.tcp_tw_reuse = 1

The parameter net.ipv4.tcp_fin_timeout sets the length of time in seconds to wait for a final FIN packet before forcing a close of the socket. The default is 60 (seconds).

The parameter net.ipv4.tcp_tw_recycle enables fast recycling of TIME_WAIT sockets. The default is 0 (false). Enabling this can cause Network Address Translation (NAT) issues.

The parameter net.ipv4.tcp_tw_reuse enables reuse of TIME_WAIT sockets for new connections. The default is 0 (false).

These settings are recommended only for testing, and not for production systems.

After making the changes to /etc/sysctl.conf, reload the configuration with the sysctl command:

# sysctl -p

11.28.3. Options

The searchrate command takes the following options:

Command options:

-a | --dereferencePolicy {dereferencePolicy}

Alias dereference policy ('never', 'always', 'search', or 'find').

Default: never

-b | --baseDn {baseDN}

Base DN template string.

-B | --warmUpDuration {warmUpDuration}

Warm up duration in seconds.

Default: 0

-c | --numConnections {numConnections}

Number of connections.

Default: 1

-d | --maxDuration {maxDuration}

Maximum duration in seconds, 0 for unlimited.

Default: 0

-e | --percentile {percentile}

Calculate max response time for a percentile of operations.

-f | --keepConnectionsOpen

Keep connections open.

Default: false

-F | --noRebind

Keep connections open and do not rebind.

Default: false

-g | --argument {generator function or static string}

Argument used to evaluate the template strings in program parameters (ie. Base DN, Search Filter). The set of all arguments provided form the argument list in order. Besides static string arguments, they can be generated per iteration with the following functions:

"inc({filename})" Consecutive, incremental line from file

"inc({min},{max})" Consecutive, incremental number

"rand({filename})" Random line from file

"rand({min},{max})" Random number

"randstr({length},_charSet_)" Random string of specified length and optionally from characters in the charSet string. A range of character can be specified with [start-end] charSet notation. If no charSet is specified, the default charSet of [A-Z][a-z][0-9] will be used.

-i | --statInterval {statInterval}

Display results each specified number of seconds.

Default: 5

-m | --maxIterations {maxIterations}

Max iterations, 0 for unlimited.

Default: 0

-M | --targetThroughput {targetThroughput}

Target average throughput to achieve.

Default: 0

-s | --searchScope {searchScope}

Search scope ('base', 'one', 'sub', or 'subordinates'). Note: 'subordinates' is an LDAP extension that might not work with all LDAP servers.

Default: sub

-S | --scriptFriendly

Use script-friendly mode.

Default: false

-t | --numConcurrentRequests {numConcurrentRequests}

Number of concurrent requests per connection.

Default: 1

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default:

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server port number.

-q | --useStartTls

Use StartTLS to secure communication with the server.

Default: false

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

-Z | --useSsl

Use SSL for secure communication with the server.

Default: false

Utility input/output options:

-n | --no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-v | --verbose

Use verbose mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.28.4. Exit Codes

0: The command completed successfully.
89: An error occurred while parsing the command-line arguments.

11.28.5. Examples

The following example measures search performance:

$ searchrate -p 1389 -b dc=example,dc=com -F -c 4 -t 4 -g "rand(0,2000)" "(uid=user.{})"
--------------------------------------------------------------------------------------------
|     Throughput    |                 Response Time                |       Additional      |
|    (ops/second)   |                (milliseconds)                |       Statistics      |
|   recent  average |   recent  average    99.9%   99.99%  99.999% |  err/sec Entries/Srch |
--------------------------------------------------------------------------------------------
|  38515.0  38515.0 |    0.410    0.410     9.57    19.66    26.61 |      0.0          1.0 |
|  47742.4  43128.7 |    0.332    0.367     7.18    15.93    25.56 |      0.0          1.0 |
|  48027.6  44761.7 |    0.330    0.353     6.26    14.55    23.07 |      0.0          1.0 |
|  47773.6  45514.7 |    0.331    0.348     5.80    13.30    22.81 |      0.0          1.0 |
|  47833.8  45978.5 |    0.331    0.344     5.34    12.32    22.02 |      0.0          1.0 |
|  47891.2  46297.3 |    0.331    0.342     4.98    11.99    21.23 |      0.0          1.0 |
|  46579.8  46337.6 |    0.340    0.341     4.82    11.80    20.97 |      0.0          1.0 |
^C

Chapter 11.29. setup — install OpenDJ server

11.29.1. Synopsis

setup {subcommand} {options}

11.29.2. Description

This utility can be used to install an OpenDJ instance either as a directory server, a replication server or a proxy server.

11.29.3. Options

The setup command takes the following options:

Command options:

--acceptLicense

Automatically accepts the product license (if present).

Default: false

--adminConnectorPort {port}

Port on which the Administration Connector should listen for communication.

-D | --rootUserDn {rootUserDN}

DN for the initial root user for the Directory Server.

Default: cn=Directory Manager

--instancePath {path}

Path were the instance should be set up.

Default: /tmp

-j | --rootUserPasswordFile {rootUserPasswordFile}

Path to a file containing the password for the initial root user for the Directory Server.

--monitorUserDn {monitorUserDn}

DN of the default user allowed to query monitoring information.

Default: uid=Monitor

--monitorUserPassword {monitorUserPassword}

Password of the default user allowed to query monitoring information.

--monitorUserPasswordFile {monitorUserPasswordFile}

Path to a file containing the password for the default user allowed to query monitoring information.

-N | --certNickname {nickname}

Nickname of a keystore entry containing a certificate that the server should use when negotiating secure connections using StartTLS or SSL. Multiple keystore entries may be provided by using this option multiple times.

-O | --doNotStart

Do not start the server when the configuration is completed.

Default: false

--productionMode

Harden default configuration for production use.

Default: false

-Q | --quiet

Use quiet mode.

Default: false

-S | --skipPortCheck

Skip the check to determine whether the specified ports are usable.

Default: false

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password. The keystore password is required when you specify an existing file-based keystore (JKS, JCEKS, PKCS#12).

--useJavaKeyStore {keyStorePath}

Path of a JKS keystore containing the certificate(s) that the server should use when negotiating secure connections using StartTLS or SSL.

--useJceKeyStore {keyStorePath}

Path of a JCEKS keystore containing the certificate(s) that the server should use when negotiating secure connections using StartTLS or SSL.

--usePkcs11KeyStore

Use certificate(s) in a PKCS#11 token that the server should use when accepting SSL-based connections or performing StartTLS negotiation.

Default: false

--usePkcs12KeyStore {keyStorePath}

Path of a PKCS#12 keystore containing the certificate(s) that the server should use when negotiating secure connections using StartTLS or SSL.

-w | --rootUserPassword {rootUserPassword}

Password for the initial root user for the Directory Server.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.29.4. Subcommands

The setup command supports the following subcommands:

11.29.4.1. setup directory-server

Install an OpenDJ directory server instance. See "setup directory-server --help" for specific options.

11.29.4.1.1. Options

The setup directory-server command takes the following options:

-q | --enableStartTls

Enable StartTLS to allow secure communication with the server using the LDAP port.

Default: false

-p | --ldapPort {port}

Port on which the Directory Server should listen for LDAP communication.

-Z | --ldapsPort {port}

Port on which the Directory Server should listen for LDAPS communication. The LDAPS port will be configured and SSL will be enabled only if this argument is explicitly specified.

-a | --addBaseEntry

Indicates whether to create the base entry in the Directory Server database.

Default: false

-b | --baseDn {baseDN}

Base DN for user information in the Directory Server. Multiple base DNs may be provided by using this option multiple times.

--help-profiles

Display all available profiles.

Default: false

--help-profile {name[:version]}

Display profile parameters.

-l | --ldifFile {ldifFile}

Path to an LDIF file containing data that should be added to the Directory Server database. Multiple LDIF files may be provided by using this option multiple times.

-R | --rejectFile {rejectFile}

Write rejected entries to the specified file.

-d | --sampleData {numEntries}

Specifies that the database should be populated with the specified number of sample entries.

--skipFile {skipFile}

Write skipped entries to the specified file.

--profile {name[:version]}

Setup profile to apply when initially configuring the server. If the version is not specified, it defaults to the same version as DS. Use this option multiple times to apply multiple profiles. This option cannot be combined with data import options. There are no setup profiles available for this DS version.

--set {[profileName/]parameterName:value}

Assign a value to a setup profile parameter. Setup profile parameters are listed in the parameters.groovy file for the profile. Setup profiles are found in the /tmp/template/setup-profiles directory. Profile name must be provided if multiple profiles are provided. When applying multiple profiles having the same parameter names, indicate the profile that a parameter applies to by using the profileName/parameterName format. Parameter values can contain commons configuration expressions for property value substitution.

-h | --hostname {host}

The fully-qualified directory server host name that will be used when generating self-signed certificates for LDAP SSL/StartTLS, the administration connector, and replication.

Default: localhost.localdomain

--httpPort {port}

Port on which the server should listen for HTTP communication.

--httpsPort {port}

Port on which the server should listen for HTTPS communication.

11.29.4.2. setup proxy-server

Install an OpenDJ proxy server instance. There are two ways to specify the servers to be contacted by the proxy. They can either be listed exhaustively or retrieved from an existing replication topology. See "setup proxy-server --help" for specific options.

11.29.4.2.1. Options

The setup proxy-server command takes the following options:

-q | --enableStartTls

Enable StartTLS to allow secure communication with the server using the LDAP port.

Default: false

-p | --ldapPort {port}

Port on which the Directory Server should listen for LDAP communication.

-Z | --ldapsPort {port}

Port on which the Directory Server should listen for LDAPS communication. The LDAPS port will be configured and SSL will be enabled only if this argument is explicitly specified.

--usePkcs12TrustStore {trustStorePath}

Use existing PKCS12 truststore file to trust the remote server certificates.

--useJceTrustStore {trustStorePath}

Use existing JCEKS truststore file to trust the remote server certificates.

--useJavaTrustStore {trustStorePath}

Use existing JKS truststore file to trust the remote server certificates.

--useJvmTrustStore

Use the JVM truststore for validating remote server certificates.

Default: false

-X | --trustAll

Trust all server SSL certificates.

Default: false

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-U | --trustStorePasswordFile {path}

Path to a file containing the truststore password.

--loadBalancingAlgorithm {algorithm}

Algorithm to use to load balance between servers. Available algorithms are 'affinity, least-requests'.

Default: affinity

--staticPrimaryServer {host:port}

Static server to contact when available before contacting secondary servers. Multiple servers may be provided by using this option multiple times.

--proxyUserBindDn {proxyBindDN}

The bind DN for forwarding LDAP requests to remote servers. This bind DN must be present on all the remote servers.

Default: cn=proxy

--proxyUserBindPassword {proxyBindPassword}

Password associated with the proxy bind DN. The bind password must be the same on all the remote servers.

--proxyUserBindPasswordFile {proxyBindPasswordFile}

Path to a file containing the password associated with the proxy bind DN. The bind password must be the same on all the remote servers.

--replicationBindDn {bindDN}

The bind DN for periodically reading replication server configurations. The bind DN must be present on all replication servers and directory servers, it must be able to read the server configuration.

--replicationBindPassword {bindPassword}

The bind password for periodically reading replication server configurations. The bind password must be the same on all replication and directory servers.

--replicationBindPasswordFile {bindPasswordFile}

Path to a file containing the bind password for periodically reading replication server configurations. The bind password must be the same on all replication and directory servers.

--replicationPreferredGroupId {domainGroupIDNumber}

Replication domain group ID number of directory server replicas to contact when available before contacting other replicas. If this option is not specified then all replicas will be treated the same.

--replicationServer {host:port}

Replication server to contact periodically in order to discover backend servers. Multiple replication servers may be provided by using this option multiple times.

--baseDn {baseDN}

Base DN for user information in the Proxy Server. Multiple base DNs may be provided by using this option multiple times. If no base DNs are defined then the proxy will forward requests to all public naming contexts of the remote servers.

--staticSecondaryServer {host:port}

Static server to contact when all primary servers are unavailable. Multiple servers may be provided by using this option multiple times.

--proxyUsingSsl

Use SSL to secure communications with remote servers.

Default: false

--proxyUsingStartTls

Use Start TLS to secure communication with remote servers.

Default: false

-h | --hostname {host}

The fully-qualified directory server host name that will be used when generating self-signed certificates for LDAP SSL/StartTLS, the administration connector, and replication.

Default: localhost.localdomain

--httpPort {port}

Port on which the server should listen for HTTP communication.

--httpsPort {port}

Port on which the server should listen for HTTPS communication.

11.29.4.3. setup replication-server

Install OpenDJ as a standalone replication server. The server can be the first of a new replication topology (default behavior) or it can join an existing topology. See "setup replication-server --help" for specific options.

11.29.4.3.1. Options

The setup replication-server command takes the following options:

--usePkcs12TrustStore {trustStorePath}

Use existing PKCS12 truststore file to trust certificates from other replication servers in the topology.

--useJceTrustStore {trustStorePath}

Use existing JCEKS truststore file to trust certificates from other replication servers in the topology.

--useJavaTrustStore {trustStorePath}

Use existing JKS truststore file to trust certificates from other replication servers in the topology.

--useJvmTrustStore

Use the JVM truststore to trust certificates from other replication servers in the topology.

Default: false

-X | --trustAll

Trust all server SSL certificates.

Default: false

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-U | --trustStorePasswordFile {path}

Path to a file containing the truststore password.

--replicationServer {host:port}

Replication server in the topology to be joined. This server must be online during setup. To bind to the remote server, this server uses the global administrator account for the topology. The global administrator account must have ID 'admin', and must use the same password as the root user password for this server.

--replicationPort {port}

Port used for replication protocol communications with other servers.

--secureReplication

Specifies whether the communication through the replication port should be secured. This option is enforced if the --productionMode option is used.

Default: false

-b | --baseDn {baseDN}

Base DN(s) of the data to be replicated. Multiple base DNs can be provided by using this option multiple times. Leave this option empty to replicate all available base DNs in the topology.

-h | --hostname {host}

The fully-qualified directory server host name that will be used when generating self-signed certificates for LDAP SSL/StartTLS, the administration connector, and replication.

Default: localhost.localdomain

--httpPort {port}

Port on which the server should listen for HTTP communication.

--httpsPort {port}

Port on which the server should listen for HTTPS communication.

11.29.5. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.29.6. Examples

The following command installs a directory server, enables StartTLS and imports 100 example entries:

$ /path/to/opendj/setup directory-server --adminConnectorPort 4444 -b dc=example,dc=com -d 100 \
 -D "cn=Directory Manager" -w password -h opendj.example.com -p 1389 --enableStartTLS


Validating parameters..... Done
Configuring certificates..... Done
Configuring server..... Done
Importing automatically-generated data (100 entries)......... Done
Starting directory server............... Done

To see basic server status and configuration, you can launch
/path/to/opendj/bin/status

Chapter 11.30. start-ds — start OpenDJ server

11.30.1. Synopsis

start-ds {options}

11.30.2. Description

This utility can be used to start the Directory Server, as well as to obtain the server version and other forms of general server information.

11.30.3. Options

The start-ds command takes the following options:

Command options:

-L | --useLastKnownGoodConfig

Attempt to start using the configuration that was in place at the last successful startup (if it is available) rather than using the current active configuration.

Default: false

-N | --noDetach

Do not detach from the terminal and continue running in the foreground. This option cannot be used with the -t, --timeout option.

Default: false

-s | --systemInfo

Display general system information.

Default: false

-t | --timeout {seconds}

Maximum time (in seconds) to wait before the command returns (the server continues the startup process, regardless). A value of '0' indicates an infinite timeout, which means that the command returns only when the server startup is completed. The default value is 60 seconds. This option cannot be used with the -N, --nodetach option.

Default: 200

Utility input/output options:

-Q | --quiet

Use quiet mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.30.4. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.30.5. Examples

The following command starts the server without displaying information about the startup process:

$ start-ds -Q

Chapter 11.31. status — display basic OpenDJ server information

11.31.1. Synopsis

status {options}

11.31.2. Description

This utility can be used to display basic server information.

11.31.3. Options

The status command takes the following options:

Command options:

--offline

Indicates that the command must be run in offline mode.

Default: false

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default: cn=Directory Manager

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

Utility input/output options:

-n | --no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-r | --refresh {period}

When this argument is specified, the status command will display its contents periodically. Used to specify the period (in seconds) between two displays of the status.

-s | --script-friendly

Use script-friendly mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.31.4. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.31.5. Examples

The following command displays the status of a running directory server:

$ status -p 4444 -h opendj.example.com -D "cn=Directory Manager" -w password -X
>>>> General details

Version                        : ForgeRock Directory Services 6.5.6
Installation and instance path : /path/to/opendj
Run status                     : Started
Host name                      : <fqdn>
Administration port (LDAPS)    : 4444
Open connections               : 1


>>>> Running server Java details

Java version       : <version>
Java vendor        : <vendor>
JVM available CPUs : <cores>
JVM max heap size  : <size>


>>>> Connection handlers

Name  : Port : Protocol : Security  : Status   : Load m1 rate : Load m5 rate
------:------:----------:-----------:----------:--------------:-------------
HTTP  : 8080 : HTTP     : Unsecured : Enabled  : 0.0          : 0.0
HTTPS : 8443 : HTTP     : SSL       : Enabled  : 0.0          : 0.0
LDAP  : 1389 : LDAP     : Unsecured : Enabled  : 0.0          : 0.0
LDAPS : 1636 : LDAP     : SSL       : Enabled  : 0.0          : 0.0
LDIF  : -    : LDIF     : -         : Disabled : -            : -
SNMP  : 161  : SNMP     : -         : Disabled : -            : -


>>>> Local backends

Base DN              : Entries : Replication : Backend     : Type                           : Status
---------------------:---------:-------------:-------------:--------------------------------:--------
uid=Monitor          : 1       : -           : monitorUser : LDIF                           : Enabled
cn=Directory Manager : 1       : -           : rootUser    : LDIF                           : Enabled
dc=example,dc=com    : 180     : -           : userRoot    : DB (<size> active cache size)  : Enabled


>>>> Disk space

Disk space : State  : Free space
-----------:--------:-----------
/          : normal : <size>

Chapter 11.32. stop-ds — stop OpenDJ server

11.32.1. Synopsis

stop-ds {options}

11.32.2. Description

This utility can be used to request that the Directory Server stop running or perform a restart. When run without explicit connection options, this utility sends a signal to the OpenDJ process to stop the server. When run with explicit connection options, this utility connects to the OpenDJ administration port and creates a shutdown task to stop the server.

11.32.3. Options

The stop-ds command takes the following options:

Command options:

-r | --stopReason {stopReason}

Reason the server is being stopped or restarted.

-R | --restart

Attempt to automatically restart the server once it has stopped.

Default: false

-t | --stopTime {stopTime}

Indicates the date/time at which the shutdown operation will begin as a server task expressed in format YYYYMMDDhhmmssZ for UTC time or YYYYMMDDhhmmss for local time. A value of '0' will cause the shutdown to be scheduled for immediate execution. When this option is specified the operation will be scheduled to start at the specified time after which this utility will exit immediately.

-Y | --proxyAs {authzID}

Use the proxied authorization control with the given authorization ID.

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default: cn=Directory Manager

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

-u | --keyStorePasswordFile {keyStorePasswordFile}

Path to a file containing the keystore password.

-U | --trustStorePasswordFile {path}

Certificate trust store PIN file.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Use -w - to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

Utility input/output options:

-n | --no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-Q | --quiet

Use quiet mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.32.4. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.32.5. Examples

The following example restarts a server:

$ stop-ds --restart
Stopping Server...
...The Directory Server has started successfully

Chapter 11.33. supportextract — extract support data

11.33.1. Synopsis

supportextract {options}

11.33.2. Description

This tool collects support data from the OpenDJ instance it is bound to.

11.33.3. Options

The supportextract command takes the following options:

Command options:

-d | --outputDirectory {directory}

The folder into which the files will be placed into.

--logsAfterDate {date}

Collect log files after this date. Format "YYYYMMDDhhmmss" like "20161123143612" = 23 November 2016, 14:36 12s. Overrides --maxLogFiles.

--maxLogFiles {number}

Maximum number of log files to collect. Ignored if --logsAfterDate is provided.

Default: 100

--needJavaHeapDump

Specifies whether a Java Heap Dump (using jmap) should be produced. The binary file is generated at the same location as the ZIP archive before being added to it; please make sure that the target directory's volume has sufficient capacity.

Default: false

--noAuditFiles

Specifies whether audit files are excluded.

Default: false

--noKeystoreFiles

Specifies whether keystore files are excluded.

Default: false

--noServerInteraction

Specifies that the tool should not interact with the server, that is no LDAP operation, and no jstack sampling.

Default: false

--serverPID {pid}

When the server is embedded in OpenAM, there is no PID file. Therefore this option indicates the server PID of the OpenAM application server.

-t | --jdkToolsDirectory {directory}

Path to the JDK utility binaries directory such as jstack.

Default: /opt/jdk8u222-b10/bin

LDAP connection options:

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default:

-j | --bindPasswordFile {bindPasswordFile}

Bind password file.

-w | --bindPassword {password}

Password to use to bind to the server.

General options:

-V | --version

Display Directory Server version information.

Default: false

11.33.4. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.33.5. Examples

The following example creates a support archive in a custom directory:

$ supportextract -D "cn=Directory Manager" -w password -d /path/to/output/directory

 2018-10-17 11:45:08 INFO   The instance is running
 2018-10-17 11:45:08 INFO   No value was provided for --jdkToolsDirectory, JDK tool directory is set to /Library/Java/JavaVirtualMachines/jdk1.8.0_144.jdk/Contents/Home/bin
 2018-10-17 11:45:08 INFO   VERSION: 6.5.0.180cf3870bac7496cdc446ea0767b55139ffcbe7
 2018-10-17 11:45:10 INFO   Collecting the monitoring info from cn=monitor
 2018-10-17 11:45:10 INFO   Collecting process statistics
 2018-10-17 11:45:10 INFO    * Generating stack dump, sample number : 1
 2018-10-17 11:45:12 INFO    * Generating stack dump, sample number : 2
 2018-10-17 11:45:13 INFO    * Generating stack dump, sample number : 3
 2018-10-17 11:45:14 INFO    * Generating stack dump, sample number : 4
 2018-10-17 11:45:15 INFO    * Generating stack dump, sample number : 5
 2018-10-17 11:45:17 INFO    * Generating stack dump, sample number : 6
 2018-10-17 11:45:18 INFO    * Generating stack dump, sample number : 7
 2018-10-17 11:45:19 INFO    * Generating stack dump, sample number : 8
 2018-10-17 11:45:20 INFO    * Generating stack dump, sample number : 9
 2018-10-17 11:45:21 INFO    * Generating stack dump, sample number : 10
 2018-10-17 11:45:22 INFO   Collecting the configuration files
 2018-10-17 11:45:22 INFO   Adding config.ldif
 2018-10-17 11:45:22 INFO   Adding admin-backend.ldif
 2018-10-17 11:45:22 INFO   Adding java.properties
 2018-10-17 11:45:22 INFO   Adding tasks.ldif
 2018-10-17 11:45:22 INFO   Adding build info
 2018-10-17 11:45:22 INFO   - Adding schema files
 2018-10-17 11:45:23 INFO   - Adding HTTP configuration file(s)
 2018-10-17 11:45:23 INFO   - Listing the security stores
 2018-10-17 11:45:23 INFO     * config/keystore
 2018-10-17 11:45:23 INFO     * db/ads-truststore/ads-truststore
 2018-10-17 11:45:23 INFO   Collecting system node information
 2018-10-17 11:45:23 INFO   - OS information
 2018-10-17 11:45:23 INFO   - Network information
 2018-10-17 11:45:53 INFO   - Disk information
 2018-10-17 11:45:53 INFO   - Processor information
 2018-10-17 11:45:53 INFO   Collecting backend statistics
 2018-10-17 11:45:53 INFO    - userRoot: total jdb files 1
 2018-10-17 11:45:53 INFO    - Adding je.info.0, je.config.csv and je.stat.csv
 2018-10-17 11:45:53 INFO   Collecting the log files
 2018-10-17 11:45:53 INFO    * /path/to/opendj/logs/access *
 2018-10-17 11:45:53 INFO    * /path/to/opendj/logs/http-access *
 2018-10-17 11:45:53 INFO    * /path/to/opendj/logs/ldap-access.audit.json *
 2018-10-17 11:45:53 INFO    * /path/to/opendj/logs/ldap-access.audit.json *
 2018-10-17 11:45:53 INFO    * /path/to/opendj/logs/http-access.audit.json *
 2018-10-17 11:45:53 INFO    * /path/to/opendj/logs/audit *
 2018-10-17 11:45:53 INFO    * /path/to/opendj/logs/errors *
 2018-10-17 11:45:53 INFO    * /path/to/opendj/logs/replication *
 2018-10-17 11:45:53 INFO    * /path/to/opendj/logs/debug *
 2018-10-17 11:45:53 INFO   Skipping GC logs collection because GC logging is not enabled

 The following archive has been created :
 /path/to/output/directory/opendj-support-data-20181017-114508.zip

Chapter 11.34. upgrade — upgrade OpenDJ configuration and application data

11.34.1. Synopsis

upgrade {options}

11.34.2. Description

Upgrades OpenDJ configuration and application data so that it is compatible with the installed binaries.

This tool should be run immediately after upgrading the OpenDJ binaries and before restarting the server.

NOTE: this tool does not provide backup or restore capabilities. Therefore, it is the responsibility of the OpenDJ administrator to take necessary precautions before performing the upgrade.

This utility performs only part of the upgrade process, which includes the following phases for a single server:

Get and unpack a newer version of the software.
Stop the current server.
Overwrite existing binary and script files with those of the newer version, and then run this utility before restarting the server.
Start the upgraded server.

Important

This utility does not back up your data before you upgrade, nor does it restore your data if the utility fails. In order to revert a failed upgrade, make sure you back up directory data before you overwrite existing binary and script files.

By default this utility requests confirmation before making important configuration changes. You can use the --no-prompt option to run the command non-interactively.

When using the --no-prompt option, if this utility cannot complete because it requires confirmation for a potentially very long or critical task, then it exits with an error and a message about how to finish making the changes. You can add the --force option to force a non-interactive upgrade to continue in this case, also performing long running and critical tasks.

After upgrading, see the resulting upgrade.log file for a full list of operations performed.

11.34.3. Options

The upgrade command takes the following options:

Command options:

--acceptLicense

Automatically accepts the product license (if present).

Default: false

--dataOnly

Upgrades only application data. OpenDJ configuration must have been upgraded before.

Default: false

--force

Forces a non-interactive upgrade to continue even if it requires user interaction. In particular, long running or critical upgrade tasks, such as re-indexing, which require user confirmation will be skipped. This option may only be used with the 'no-prompt' option.

Default: false

--ignoreErrors

Ignores any errors which occur during the upgrade. This option should be used with caution and may be useful in automated deployments where potential errors are known in advance and resolved after the upgrade has completed.

Default: false

Utility input/output options:

-n | --no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

-Q | --quiet

Use quiet mode.

Default: false

-v | --verbose

Use verbose mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.34.4. Exit Codes

0

The command completed successfully.

2

The command was run in non-interactive mode, but could not complete because confirmation was required to run a long or critical task.

See the error message or the log for details.

other

An error occurred.

Chapter 11.35. verify-index — check index for consistency or errors

11.35.1. Synopsis

verify-index {options}

11.35.2. Description

This utility ensures that index data is consistent within an indexed backend database. Stop the server before running this tool.

11.35.3. Options

The verify-index command takes the following options:

Command options:

-b | --baseDn {baseDN}

Base DN of a backend supporting indexing. Verification is performed on indexes within the scope of the given base DN.

-c | --clean

Specifies that a single index should be verified to ensure it is clean. An index is clean if each index value references only entries containing that value. Only one index at a time may be verified in this way.

Default: false

--countErrors

Count the number of errors found during the verification and return that value as the exit code (values > 255 will be reduced to 255 due to exit code restrictions).

Default: false

-i | --index {index}

Name of an index to be verified. For an attribute index this is simply an attribute name. Multiple indexes may be verified for completeness, or all indexes if no indexes are specified. An index is complete if each index value references all entries containing that value.

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

11.35.4. Exit Codes

0

The command completed successfully.

1

The command was run in non-interactive mode, but could not complete because confirmation was required to run a long or critical task.

See the error message or the log for details.

0-255

The number of errors in the index, as indicated for the --countErrors option.

11.35.5. Examples

The following example shows how to verify the sn (surname) index for completeness and for errors:

$ verify-index -b dc=example,dc=com -i sn --clean --countErrors
... msg=Maximum number of entries referenced by any record is 32

Chapter 11.36. windows-service — register DS as a Windows Service

11.36.1. Synopsis

windows-service options

11.36.2. Description

This utility can be used to run the server as a Windows Service.

11.36.3. Service Options

-c, --cleanupService serviceName: Disable the service and clean up the windows registry information associated with the provided service name
-d, --disableService: Disable the server as a Windows service and stop the server
-e, --enableService: Enable the server as a Windows service
-s, --serviceState: Provide information about the state of the server as a Windows service

11.36.4. General Options

-V, --version: Display version information
-?, -H, --help: Display usage information

11.36.5. Exit Codes

0: The command completed successfully.
> 0: An error occurred.

11.36.6. Example

The following command registers the server as a Windows Service:

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

After running this command, you can manage the service using Windows administration tools.

Appendix A. Getting Support

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.

ForgeRock has staff members around the globe who support our international customers and partners. For details on ForgeRock's support offering, including support plans and service level agreements (SLAs), visit https://www.forgerock.com/support.

ForgeRock publishes comprehensive documentation online:

The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.
While many articles are visible to community members, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.
ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

Glossary

Abandon operation

LDAP operation to stop processing of a request in progress, after which the server drops the connection without a reply to the client application.

Access control

Control to grant or to deny access to a resource.

Access control instruction (ACI)

Instruction added as a directory entry attribute for fine-grained control over what a given user or group member is authorized to do in terms of LDAP operations and access to user data.

ACIs are implemented independently from privileges, which apply to administrative operations.

Reference for ForgeRock® Directory Services, including bundled tools.

Preface

Chapter 1. REST to LDAP Configuration

1.1. Gateway Configuration File

Caution

1.2. Gateway REST2LDAP Configuration File

1.3. Mapping Configuration File

Chapter 2. Request Handling

2.1. Requests to Servers

2.2. Requests to Gateways

Chapter 3. LDAP Result Codes

Chapter 4. File Layout

Chapter 5. Ports Used

Chapter 6. Standards, RFCs, and Internet-Drafts

Chapter 7. LDAP Controls

Chapter 8. LDAP Extended Operations

Chapter 9. Localization

9.1. DS Languages

Note

9.2. Directory Support For Locales and Language Subtypes

Chapter 10. Monitoring Metrics

10.1. Metric Types

10.2. LDAP Metrics

Note

10.3. Prometheus Metrics

Note

Part 11. Tools Reference

Chapter 11.1. addrate — measure add and delete throughput and response time

11.1.1. Synopsis

11.1.2. Description

11.1.3. Options

11.1.4. Exit Codes

11.1.5. Examples

Chapter 11.2. authrate — measure bind throughput and response time

11.2.1. Synopsis

11.2.2. Description

11.2.3. Options

11.2.4. Exit Codes

11.2.5. Examples

Chapter 11.3. backendstat — gather OpenDJ backend debugging information

11.3.1. Synopsis

11.3.2. Description

11.3.3. Options

11.3.4. Subcommands

11.3.4.1. backendstat dump-index

11.3.4.1.1. Options

11.3.4.2. backendstat dump-raw-db

11.3.4.2.1. Options

11.3.4.3. backendstat list-backends

11.3.4.4. backendstat list-base-dns

11.3.4.4.1. Options

11.3.4.5. backendstat list-indexes

11.3.4.5.1. Options

11.3.4.6. backendstat list-raw-dbs

11.3.4.6.1. Options

11.3.4.7. backendstat show-index-status

11.3.4.7.1. Options

11.3.5. Exit Codes

11.3.6. Examples

Chapter 11.4. backup — back up directory data

11.4.1. Synopsis

11.4.2. Description

11.4.3. Options

11.4.4. Exit Codes

11.4.5. Examples

Chapter 11.5. base64 — encode and decode base64 strings

11.5.1. Synopsis

11.5.2. Description

11.5.3. Options

11.5.4. Subcommands

11.5.4.1. base64 decode

11.5.4.1.1. Options

11.5.4.2. base64 encode

11.5.4.2.1. Options

11.5.5. Exit Codes

11.5.6. Examples

Chapter 11.6. changelogstat — debug changelog and changenumber files

11.6.1. Synopsis

11.6.2. Description

11.6.3. Options