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:

  1. If the client request has an Authorization header, and policies include oauth2, the server attempts to apply the OAuth 2.0 policy.

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

  3. 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
PropertyDescription

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
PropertyDescription

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
PropertyDescription

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 CodeNameDescription

-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 DirectoryDescription
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
ProtocolsConventional PortsActive 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:

TypeDescription
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
NameSyntaxDescription
ds-mon-abandoned-requestsCounter metric

Total number of abandoned operations since startup

ds-mon-active-connections-countInteger

Number of active client connections

ds-mon-active-persistent-searchesInteger

Number of active persistent searches

ds-mon-aliveBoolean

Indicates whether the server is alive

ds-mon-alive-errorsDirectory String

Lists server errors preventing the server from operating correctly that require administrative action

ds-mon-approx-oldest-change-not-synchronizedGeneralized Time

Approximate date and time of the oldest change not yet synchronized

ds-mon-approximate-delayDuration in milli-seconds

Approximate delay between this server and the connected replica

ds-mon-backend-degraded-index-countInteger

Number of degraded indexes in the backend

ds-mon-backend-degraded-indexDirectory String

Backend degraded index

ds-mon-backend-entry-countInteger

Number of entries contained in the backend

ds-mon-backend-filter-use-indexedInteger

Number of indexed searches performed against the backend

ds-mon-backend-filter-use-start-timeGeneralized Time

Time when recording started for statistical information about the simple search filters processed against the backend

ds-mon-backend-filter-use-unindexedInteger

Number of unindexed searches performed against the backend

ds-mon-backend-filter-useJson

Information about the simple search filter processed against the backend

ds-mon-backend-is-privateBoolean

Whether the base DNs of this backend should be considered public or private

ds-mon-backend-proxy-base-dnDN

Base DNs routed to remote LDAP servers by the proxy backend

ds-mon-backend-proxy-shardSummary metric

Remote LDAP servers that the proxy backend forwards requests to

ds-mon-backend-ttl-entries-deletedSummary metric

Summary for entries purged by time-to-live

ds-mon-backend-ttl-is-runningBoolean

Indicates whether time-to-live is in the process of purging expired entries

ds-mon-backend-ttl-last-run-timeGeneralized Time

Last date and time when time-to-live finished purging expired entries

ds-mon-backend-ttl-queue-sizeInteger

Number of entries queued for purging by the time-to-live service

ds-mon-backend-ttl-thread-countInteger

Number of active time-to-live threads

ds-mon-backend-writability-modeDirectory String

Current backend behavior when processing write operations, can either be "disabled", "enabled" or "internal-only"

ds-mon-base-dn-entry-countInteger

Number of subordinate entries of the base DN, including the base DN

ds-mon-base-dnDN

Base DN handled by a backend

ds-mon-build-numberInteger

Build number of the Directory Server

ds-mon-build-timeGeneralized Time

Build date and time of the Directory Server

ds-mon-bytes-readSummary metric

Network bytes read summary

ds-mon-bytes-writtenSummary metric

Network bytes written summary

ds-mon-cache-entry-countInteger

Current number of entries held in this cache

ds-mon-cache-max-entry-countInteger

Maximum number of entries allowed in this cache

ds-mon-cache-max-size-bytesSize in bytes

Memory limit for this cache

ds-mon-cache-missesSummary metric

Number of attempts to retrieve an entry that was not held in this cache

ds-mon-cache-total-triesSummary metric

Number of attempts to retrieve an entry from this cache

ds-mon-certificate-expires-atGeneralized Time

Certificate expiration date and time

ds-mon-certificate-issuer-dnDN

Certificate issuer DN

ds-mon-certificate-serial-numberInteger

Certificate serial number

ds-mon-certificate-subject-dnDN

Certificate subject DN

ds-mon-compact-versionDirectory String

Compact version of the Directory Server

ds-mon-config-dnDN

DN of the configuration entry

ds-mon-connected-to-server-hostportHost port

Host and replication port of the server that this server is connected to

ds-mon-connected-to-server-idInteger

Identifier of the server that this server is connected to

ds-mon-connectionJson

Client connection summary information

ds-mon-connectionsSummary metric

Connection summary

ds-mon-current-connectionsInteger

Number of client connections currently established with the Directory Server

ds-mon-current-delayDuration in milli-seconds

Current local delay in replaying replicated operations

ds-mon-current-receive-windowInteger

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-windowInteger

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-timeGeneralized Time

Current date and time

ds-mon-db-cache-evict-internal-nodes-countInteger

Number of internal nodes evicted from the database cache

ds-mon-db-cache-evict-leaf-nodes-countInteger

Number of leaf nodes (data records) evicted from the database cache

ds-mon-db-cache-misses-internal-nodesInteger

Number of internal nodes requested by btree operations that were not in the database cache

ds-mon-db-cache-misses-leaf-nodesInteger

Number of leaf nodes (data records) requested by btree operations that were not in the database cache

ds-mon-db-cache-size-activeSize in bytes

Size of the database cache

ds-mon-db-cache-size-totalSize in bytes

Maximum size of the database cache

ds-mon-db-cache-total-tries-internal-nodesInteger

Number of internal nodes requested by btree operations

ds-mon-db-cache-total-tries-leaf-nodesInteger

Number of leaf nodes (data records) requested by btree operations

ds-mon-db-checkpoint-countInteger

Number of checkpoints run so far

ds-mon-db-log-cleaner-file-deletion-countInteger

Number of cleaner file deletions

ds-mon-db-log-files-openInteger

Number of files currently open in the database file cache

ds-mon-db-log-files-openedInteger

Number of times a log file has been opened

ds-mon-db-log-size-activeSize 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-totalSize in bytes

Size used by all data files on disk

ds-mon-db-log-utilization-maxInteger

Current maximum (upper bound) log utilization as a percentage

ds-mon-db-log-utilization-minInteger

Current minimum (lower bound) log utilization as a percentage

ds-mon-db-versionDirectory String

Database version used by the backend

ds-mon-disk-dirFilesystem path

A monitored directory containing data that may change over time

ds-mon-disk-freeSize in bytes

Amount of free disk space

ds-mon-disk-full-thresholdSize in bytes

Effective full disk space threshold

ds-mon-disk-low-thresholdSize in bytes

Effective low disk space threshold

ds-mon-disk-rootFilesystem path

Monitored disk root

ds-mon-disk-stateDirectory String

Current disk state, can be either "normal", "low" or "full"

ds-mon-domain-generation-idInteger

Replication domain generation identifier

ds-mon-domain-nameDN

Replication domain name

ds-mon-entries-awaiting-updates-countDuration in milli-seconds

Number of entries for which an update operation has been received but not replayed yet by this replica

ds-mon-fix-idsDirectory String

IDs of issues that have been fixed in this Directory Server build

ds-mon-full-versionDirectory String

Full version of the Directory Server

ds-mon-healthyBoolean

Indicates whether the server is able to handle requests

ds-mon-healthy-errorsDirectory String

Lists transient server errors preventing the server from temporarily handling requests

ds-mon-install-pathFilesystem path

Directory Server root installation path

ds-mon-instance-pathFilesystem path

Directory Server instance path

ds-mon-jvm-architectureDirectory String

Java virtual machine architecture (e.g. 32-bit, 64-bit)

ds-mon-jvm-argumentsDirectory String

Input arguments passed to the Java virtual machine

ds-mon-jvm-available-cpusInteger

Number of processors available to the Java virtual machine

ds-mon-jvm-class-pathFilesystem path

Path used to find directories and JAR archives containing Java class files

ds-mon-jvm-classes-loadedInteger

Number of classes loaded since the Java virtual machine started

ds-mon-jvm-classes-unloadedInteger

Number of classes unloaded since the Java virtual machine started

ds-mon-jvm-garbage-collector-concurrent-mark-sweep-countInteger

Number of collections performed by the "concurrent mark sweep" garbage collection algorithm

ds-mon-jvm-garbage-collector-concurrent-mark-sweep-timeDuration in milli-seconds

Approximate accumulated time taken by the "concurrent mark sweep" garbage collection algorithm

ds-mon-jvm-garbage-collector-copy-countInteger

Number of collections performed by the "copy" garbage collection algorithm

ds-mon-jvm-garbage-collector-copy-timeDuration in milli-seconds

Approximate accumulated time taken by the "copy" garbage collection algorithm

ds-mon-jvm-garbage-collector-g1-old-generation-countInteger

Number of collections performed by the "g1 old generation" garbage collection algorithm

ds-mon-jvm-garbage-collector-g1-old-generation-timeDuration in milli-seconds

Approximate accumulated time taken by the "g1 old generation" garbage collection algorithm

ds-mon-jvm-garbage-collector-g1-young-generation-countInteger

Number of collections performed by the "g1 young generation" garbage collection algorithm

ds-mon-jvm-garbage-collector-g1-young-generation-timeDuration in milli-seconds

Approximate accumulated time taken by the "g1 young generation" garbage collection algorithm

ds-mon-jvm-garbage-collector-mark-sweep-compact-countInteger

Number of collections performed by the "mark sweep compact" garbage collection algorithm

ds-mon-jvm-garbage-collector-mark-sweep-compact-timeDuration in milli-seconds

Approximate accumulated time taken by the "mark sweep compact" garbage collection algorithm

ds-mon-jvm-garbage-collector-par-new-countInteger

Number of collections performed by the "par new" garbage collection algorithm

ds-mon-jvm-garbage-collector-par-new-timeDuration in milli-seconds

Approximate accumulated time taken by the "par new" garbage collection algorithm

ds-mon-jvm-garbage-collector-ps-mark-sweep-countInteger

Number of collections performed by the "parallel scavenge mark sweep" garbage collection algorithm

ds-mon-jvm-garbage-collector-ps-mark-sweep-timeDuration in milli-seconds

Approximate accumulated time taken by the "parallel scavenge mark sweep" garbage collection algorithm

ds-mon-jvm-garbage-collector-ps-scavenge-countInteger

Number of collections performed by the "parallel scavenge" garbage collection algorithm

ds-mon-jvm-garbage-collector-ps-scavenge-timeDuration in milli-seconds

Approximate accumulated time taken by the "parallel scavenge" garbage collection algorithm

ds-mon-jvm-java-homeFilesystem path

Installation directory for Java runtime environment (JRE)

ds-mon-jvm-java-vendorDirectory String

Java runtime environment (JRE) vendor

ds-mon-jvm-java-versionDirectory String

Java runtime environment (JRE) version

ds-mon-jvm-memory-heap-initSize in bytes

Amount of heap memory that the Java virtual machine initially requested from the operating system

ds-mon-jvm-memory-heap-maxSize in bytes

Maximum amount of heap memory that the Java virtual machine will attempt to use

ds-mon-jvm-memory-heap-reservedSize in bytes

Amount of heap memory that is committed for the Java virtual machine to use

ds-mon-jvm-memory-heap-usedSize in bytes

Amount of heap memory used by the Java virtual machine

ds-mon-jvm-memory-initSize in bytes

Amount of memory that the Java virtual machine initially requested from the operating system

ds-mon-jvm-memory-maxSize in bytes

Maximum amount of memory that the Java virtual machine will attempt to use

ds-mon-jvm-memory-non-heap-initSize in bytes

Amount of non-heap memory that the Java virtual machine initially requested from the operating system

ds-mon-jvm-memory-non-heap-maxSize in bytes

Maximum amount of non-heap memory that the Java virtual machine will attempt to use

ds-mon-jvm-memory-non-heap-reservedSize in bytes

Amount of non-heap memory that is committed for the Java virtual machine to use

ds-mon-jvm-memory-non-heap-usedSize in bytes

Amount of non-heap memory used by the Java virtual machine

ds-mon-jvm-memory-pools-code-cache-initSize 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-maxSize in bytes

Maximum amount of "code cache" memory that the Java virtual machine will attempt to use

ds-mon-jvm-memory-pools-code-cache-reservedSize in bytes

Amount of "code cache" memory that is committed for the Java virtual machine to use

ds-mon-jvm-memory-pools-code-cache-usedSize in bytes

Amount of "code cache" memory used by the Java virtual machine

ds-mon-jvm-memory-pools-compressed-class-space-initSize 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-maxSize 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-reservedSize 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-usedSize in bytes

Amount of "compressed class space" memory used by the Java virtual machine

ds-mon-jvm-memory-pools-metaspace-initSize in bytes

Amount of "metaspace" memory that the Java virtual machine initially requested from the operating system

ds-mon-jvm-memory-pools-metaspace-maxSize in bytes

Maximum amount of "metaspace" memory that the Java virtual machine will attempt to use

ds-mon-jvm-memory-pools-metaspace-reservedSize in bytes

Amount of "metaspace" memory that is committed for the Java virtual machine to use

ds-mon-jvm-memory-pools-metaspace-usedSize in bytes

Amount of "metaspace" memory used by the Java virtual machine

ds-mon-jvm-memory-pools-ps-eden-space-initSize 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-maxSize 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-reservedSize 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-gcSize 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-usedSize in bytes

Amount of "parallel scavenge eden space" memory used by the Java virtual machine

ds-mon-jvm-memory-pools-ps-old-gen-initSize 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-maxSize 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-reservedSize 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-gcSize 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-usedSize in bytes

Amount of "parallel scavenge old generation" memory used by the Java virtual machine

ds-mon-jvm-memory-pools-ps-survivor-space-initSize 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-maxSize 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-reservedSize 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-gcSize 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-usedSize in bytes

Amount of "parallel scavenge survivor space" memory used by the Java virtual machine

ds-mon-jvm-memory-reservedSize in bytes

Amount of memory that is committed for the Java virtual machine to use

ds-mon-jvm-memory-usedSize in bytes

Amount of memory used by the Java virtual machine

ds-mon-jvm-supported-tls-ciphersDirectory String

Transport Layer Security (TLS) cipher suites supported by this Directory Server

ds-mon-jvm-supported-tls-protocolsDirectory String

Transport Layer Security (TLS) protocols supported by this Directory Server

ds-mon-jvm-threads-blocked-countInteger

Number of threads in the BLOCKED state

ds-mon-jvm-threads-countInteger

Number of live threads including both daemon and non-daemon threads

ds-mon-jvm-threads-daemon-countInteger

Number of live daemon threads

ds-mon-jvm-threads-deadlock-countInteger

Number of deadlocked threads

ds-mon-jvm-threads-deadlocksDirectory String

Diagnostic stack traces for deadlocked threads

ds-mon-jvm-threads-new-countInteger

Number of threads in the NEW state

ds-mon-jvm-threads-runnable-countInteger

Number of threads in the RUNNABLE state

ds-mon-jvm-threads-terminated-countInteger

Number of threads in the TERMINATED state

ds-mon-jvm-threads-timed-waiting-countInteger

Number of threads in the TIMED_WAITING state

ds-mon-jvm-threads-waiting-countInteger

Number of threads in the WAITING state

ds-mon-jvm-vendorDirectory String

Java virtual machine vendor

ds-mon-jvm-versionDirectory String

Java virtual machine version

ds-mon-listen-addressDirectory String

Host and port

ds-mon-lost-connectionsDuration in milli-seconds

Number of times the replica lost its connection to the replication server

ds-mon-major-versionInteger

Major version number of the Directory Server

ds-mon-max-connectionsInteger

Maximum number of simultaneous client connections that have been established with the Directory Server

ds-mon-max-receive-windowInteger

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-windowInteger

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-versionInteger

Minor version number of the Directory Server

ds-mon-missing-changesInteger

Missing changes for replication

ds-mon-newest-change-numberInteger

Newest change number present in the change number index database

ds-mon-newest-csn-timestampGeneralized Time

Timestamp of the newest CSN present in the replica database

ds-mon-newest-csnCSN (Change Sequence Number)

Newest CSN present in the replica database

ds-mon-oldest-change-numberInteger

Oldest change number present in the change number index database

ds-mon-oldest-csn-timestampGeneralized Time

Timestamp of the oldest CSN present in the replica database

ds-mon-oldest-csnCSN (Change Sequence Number)

Oldest CSN present in the replica database

ds-mon-os-architectureDirectory String

Operating system architecture

ds-mon-os-nameDirectory String

Operating system name

ds-mon-os-versionDirectory String

Operating system version

ds-mon-point-versionInteger

Point version number of the Directory Server

ds-mon-product-nameDirectory String

Full name of the Directory Server

ds-mon-protocolDirectory String

Network protocol

ds-mon-replayed-updates-conflicts-resolvedCounter metric

Number of updates replayed on this replica for which replication naming conflicts have been resolved

ds-mon-replayed-updates-conflicts-unresolvedCounter metric

Number of updates replayed on this replica for which replication naming conflicts have not been resolved

ds-mon-replayed-updatesTimer metric

Timer for updates that have been replayed on this replica

ds-mon-requests-abandonTimer metric

Abandon request timer

ds-mon-requests-addTimer metric

Add request timer

ds-mon-requests-bindTimer metric

Bind request timer

ds-mon-requests-compareTimer metric

Compare request timer

ds-mon-requests-deleteTimer metric

Delete request timer

ds-mon-requests-extendedTimer metric

Extended request timer

ds-mon-requests-failure-client-invalid-requestTimer 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-redirectTimer metric

Timer for requests that could not complete because further action is required (associated HTTP status codes: redirection (3xx))

ds-mon-requests-failure-client-referralTimer 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-limitTimer 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-securityTimer 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-serverTimer 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-uncategorizedTimer metric

Timer for requests that failed due to uncategorized reasons

ds-mon-requests-getTimer metric

GET request timer

ds-mon-requests-in-queueInteger

Number of requests in the work queue that have not yet been picked up for processing

ds-mon-requests-modify-dnTimer metric

Modify DN request timer

ds-mon-requests-modifyTimer metric

Modify request timer

ds-mon-requests-patchTimer metric

PATCH request timer

ds-mon-requests-postTimer metric

POST request timer

ds-mon-requests-putTimer metric

PUT request timer

ds-mon-requests-rejected-queue-fullSummary metric

Summary for operations that have been rejected because the work queue was already at its maximum capacity

ds-mon-requests-search-baseTimer metric

Base object search request timer

ds-mon-requests-search-oneTimer metric

One level search request timer

ds-mon-requests-search-subTimer metric

Subtree search request timer

ds-mon-requests-submittedSummary metric

Summary for operations that have been successfully submitted to the work queue

ds-mon-requests-unbindTimer metric

Unbind request timer

ds-mon-requests-uncategorizedTimer metric

Uncategorized request timer

ds-mon-revisionDirectory String

Revision ID in the source repository from which the Directory Server is build

ds-mon-sent-updatesCounter metric

Number of replication updates sent by this replica

ds-mon-server-hostportHost port

Host and port of a server

ds-mon-server-idInteger

Server identifier

ds-mon-server-stateCSN (Change Sequence Number)

Replication server state

ds-mon-short-nameDirectory String

Short name of the Directory Server

ds-mon-ssl-encryptionBoolean

Whether SSL encryption is used when exchanging messages with this server

ds-mon-start-timeGeneralized Time

Start date and time for the Directory Server

ds-mon-status-last-changedGeneralized Time

Last date and time the replication status of the local replica changed

ds-mon-statusDirectory String

Replication status of the local replica, can either be "Invalid", "Not connected", "Normal", "Degraded", "Full update", "Bad generation id"

ds-mon-system-nameDirectory String

Fully qualified domain name of the system where the Directory Server is running

ds-mon-total-connectionsInteger

Total number of client connections that have been established with the Directory Server since it started

ds-mon-updates-inbound-queueInteger

Number of remote updates received from the replication server but not replayed yet on this replica

ds-mon-updates-outbound-queueInteger

Number of local updates that are waiting to be sent to the replication server once they complete

ds-mon-updates-totals-per-replay-threadJson

JSON array of the number of updates replayed per replay thread

ds-mon-vendor-nameDirectory String

Vendor name of the Directory Server

ds-mon-version-qualifierDirectory String

Version qualifier of the Directory Server

ds-mon-working-directoryFilesystem 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
NameTypeDescription
ds_all_entry_caches_cache_entry_countGauge

Current number of entries held in this cache

ds_all_entry_caches_cache_misses_countSummary

Number of attempts to retrieve an entry that was not held in this cache

ds_all_entry_caches_cache_misses_totalSummary

Number of attempts to retrieve an entry that was not held in this cache

ds_all_entry_caches_cache_total_tries_countSummary

Number of attempts to retrieve an entry from this cache

ds_all_entry_caches_cache_total_tries_totalSummary

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_connectionsGauge

Number of client connections currently established with the Directory Server

ds_current_time_secondsGauge

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_aliveGauge

Indicates whether the server is alive

ds_health_status_healthyGauge

Indicates whether the server is able to handle requests

ds_jvm_available_cpusGauge

Number of processors available to the Java virtual machine

ds_jvm_classes_loadedGauge

Number of classes loaded since the Java virtual machine started

ds_jvm_classes_unloadedGauge

Number of classes unloaded since the Java virtual machine started

ds_jvm_garbage_collector_ps_mark_sweep_countGauge

Number of collections performed by the "parallel scavenge mark sweep" garbage collection algorithm

ds_jvm_garbage_collector_ps_mark_sweep_time_secondsGauge

Approximate accumulated time taken by the "parallel scavenge mark sweep" garbage collection algorithm

ds_jvm_garbage_collector_ps_scavenge_countGauge

Number of collections performed by the "parallel scavenge" garbage collection algorithm

ds_jvm_garbage_collector_ps_scavenge_time_secondsGauge

Approximate accumulated time taken by the "parallel scavenge" garbage collection algorithm

ds_jvm_memory_heap_init_bytesGauge

Amount of heap memory that the Java virtual machine initially requested from the operating system

ds_jvm_memory_heap_max_bytesGauge

Maximum amount of heap memory that the Java virtual machine will attempt to use

ds_jvm_memory_heap_reserved_bytesGauge

Amount of heap memory that is committed for the Java virtual machine to use

ds_jvm_memory_heap_used_bytesGauge

Amount of heap memory used by the Java virtual machine

ds_jvm_memory_init_bytesGauge

Amount of memory that the Java virtual machine initially requested from the operating system

ds_jvm_memory_max_bytesGauge

Maximum amount of memory that the Java virtual machine will attempt to use

ds_jvm_memory_non_heap_init_bytesGauge

Amount of non-heap memory that the Java virtual machine initially requested from the operating system

ds_jvm_memory_non_heap_max_bytesGauge

Maximum amount of non-heap memory that the Java virtual machine will attempt to use

ds_jvm_memory_non_heap_reserved_bytesGauge

Amount of non-heap memory that is committed for the Java virtual machine to use

ds_jvm_memory_non_heap_used_bytesGauge

Amount of non-heap memory used by the Java virtual machine

ds_jvm_memory_pools_code_cache_init_bytesGauge

Amount of "code cache" memory that the Java virtual machine initially requested from the operating system

ds_jvm_memory_pools_code_cache_max_bytesGauge

Maximum amount of "code cache" memory that the Java virtual machine will attempt to use

ds_jvm_memory_pools_code_cache_reserved_bytesGauge

Amount of "code cache" memory that is committed for the Java virtual machine to use

ds_jvm_memory_pools_code_cache_used_bytesGauge

Amount of "code cache" memory used by the Java virtual machine

ds_jvm_memory_pools_compressed_class_space_init_bytesGauge

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_bytesGauge

Maximum amount of "compressed class space" memory that the Java virtual machine will attempt to use

ds_jvm_memory_pools_compressed_class_space_reserved_bytesGauge

Amount of "compressed class space" memory that is committed for the Java virtual machine to use

ds_jvm_memory_pools_compressed_class_space_used_bytesGauge

Amount of "compressed class space" memory used by the Java virtual machine

ds_jvm_memory_pools_metaspace_init_bytesGauge

Amount of "metaspace" memory that the Java virtual machine initially requested from the operating system

ds_jvm_memory_pools_metaspace_max_bytesGauge

Maximum amount of "metaspace" memory that the Java virtual machine will attempt to use

ds_jvm_memory_pools_metaspace_reserved_bytesGauge

Amount of "metaspace" memory that is committed for the Java virtual machine to use

ds_jvm_memory_pools_metaspace_used_bytesGauge

Amount of "metaspace" memory used by the Java virtual machine

ds_jvm_memory_pools_ps_eden_space_init_bytesGauge

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_bytesGauge

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_bytesGauge

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_bytesGauge

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_bytesGauge

Amount of "parallel scavenge eden space" memory used by the Java virtual machine

ds_jvm_memory_pools_ps_old_gen_init_bytesGauge

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_bytesGauge

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_bytesGauge

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_bytesGauge

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_bytesGauge

Amount of "parallel scavenge old generation" memory used by the Java virtual machine

ds_jvm_memory_pools_ps_survivor_space_init_bytesGauge

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_bytesGauge

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_bytesGauge

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_bytesGauge

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_bytesGauge

Amount of "parallel scavenge survivor space" memory used by the Java virtual machine

ds_jvm_memory_reserved_bytesGauge

Amount of memory that is committed for the Java virtual machine to use

ds_jvm_memory_used_bytesGauge

Amount of memory used by the Java virtual machine

ds_jvm_threads_blocked_countGauge

Number of threads in the BLOCKED state

ds_jvm_threads_countGauge

Number of live threads including both daemon and non-daemon threads

ds_jvm_threads_daemon_countGauge

Number of live daemon threads

ds_jvm_threads_deadlock_countGauge

Number of deadlocked threads

ds_jvm_threads_new_countGauge

Number of threads in the NEW state

ds_jvm_threads_runnable_countGauge

Number of threads in the RUNNABLE state

ds_jvm_threads_terminated_countGauge

Number of threads in the TERMINATED state

ds_jvm_threads_timed_waiting_countGauge

Number of threads in the TIMED_WAITING state

ds_jvm_threads_waiting_countGauge

Number of threads in the WAITING state

ds_max_connectionsGauge

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_numberGauge

Newest change number present in the change number index database

ds_replication_changelog_oldest_change_numberGauge

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_windowGauge

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_windowGauge

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_idGauge

Replication domain generation identifier

ds_replication_replica_entries_awaiting_updates_countGauge

Number of entries for which an update operation has been received but not replayed yet by this replica

ds_replication_replica_lost_connectionsGauge

Number of times the replica lost its connection to the replication server

ds_replication_replica_max_receive_windowGauge

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_windowGauge

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_resolvedCounter

Number of updates replayed on this replica for which replication naming conflicts have been resolved

ds_replication_replica_replayed_updates_conflicts_unresolvedCounter

Number of updates replayed on this replica for which replication naming conflicts have not been resolved

ds_replication_replica_replayed_updates_countSummary

Timer for updates that have been replayed on this replica

ds_replication_replica_replayed_updates_seconds_totalSummary

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_updatesCounter

Number of replication updates sent by this replica

ds_replication_replica_ssl_encryptionGauge

Whether SSL encryption is used when exchanging messages with this server

ds_replication_replica_status_last_changed_secondsGauge

Last date and time the replication status of the local replica changed

ds_replication_replica_updates_inbound_queueGauge

Number of remote updates received from the replication server but not replayed yet on this replica

ds_replication_replica_updates_outbound_queueGauge

Number of local updates that are waiting to be sent to the replication server once they complete

ds_start_time_secondsGauge

Start date and time for the Directory Server

ds_total_connectionsGauge

Total number of client connections that have been established with the Directory Server since it started

ds_work_queue_requests_in_queueGauge

Number of requests in the work queue that have not yet been picked up for processing

ds_work_queue_requests_rejected_queue_full_countSummary

Summary for operations that have been rejected because the work queue was already at its maximum capacity

ds_work_queue_requests_rejected_queue_full_totalSummary

Summary for operations that have been rejected because the work queue was already at its maximum capacity

ds_work_queue_requests_submitted_countSummary

Summary for operations that have been successfully submitted to the work queue

ds_work_queue_requests_submitted_totalSummary

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:

  1. The current directory where the command is run.

  2. The resource path directory.

  3. 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
FieldAllowed Values
minute0-59
hour0-23
day of month1-31
month1-12 (or names)
day of week0-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
FieldAllowed Values
minute0-59
hour0-23
day of month1-31
month1-12 (or names)
day of week0-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
FieldAllowed Values
minute0-59
hour0-23
day of month1-31
month1-12 (or names)
day of week0-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
FieldAllowed Values
minute0-59
hour0-23
day of month1-31
month1-12 (or names)
day of week0-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:

  1. The current directory where the command is run.

  2. The resource path directory.

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

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.2.1. Options

The manage-account add-grace-login-use-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.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.6. manage-account clear-grace-login-use-times

Clear the set of grace login use times for the user. This should be used only for testing purposes.

11.23.4.7. manage-account clear-last-login-time

Clear the time that the user last authenticated to the server. 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.17. manage-account get-grace-login-use-times

Display the grace login use times for the user.

11.23.4.18. manage-account get-last-login-time

Display the time that the user last authenticated to the server.

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.25. manage-account get-remaining-grace-login-count

Display the number of grace logins remaining for the user.

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.36.1. Options

The manage-account set-grace-login-use-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.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.37.1. Options

The manage-account set-last-login-time command takes the following options:

-O | --operationValue {time}

A timestamp value using the generalized time syntax.

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
FieldAllowed Values
minute0-59
hour0-23
day of month1-31
month1-12 (or names)
day of week0-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
FieldAllowed Values
minute0-59
hour0-23
day of month1-31
month1-12 (or names)
day of week0-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:

  1. Get and unpack a newer version of the software.

  2. Stop the current server.

  3. Overwrite existing binary and script files with those of the newer version, and then run this utility before restarting the server.

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

See also Privilege.

Access control list (ACL)

An access control list connects a user or group of users to one or more security entitlements. For example, users in group sales are granted the entitlement read-only to some financial data.

access log

Server log tracing the operations the server processes including timestamps, connection information, and information about the operation itself.

Account lockout

The act of making an account temporarily or permanently inactive after successive authentication failures.

Active user

A user that has the ability to authenticate and use the services, having valid credentials.

Add operation

LDAP operation to add a new entry or entries to the directory.

Anonymous

A user that does not need to authenticate, and is unknown to the system.

Anonymous bind

A bind operation using simple authentication with an empty DN and an empty password, allowing anonymous access such as reading public information.

Approximate index

Index is used to match values that "sound like" those provided in the filter.

Attribute

Properties of a directory entry, stored as one or more key-value pairs. Typical examples include the common name (cn) to store the user's full name and variations of the name, user ID (uid) to store a unique identifier for the entry, and mail to store email addresses.

audit log

Type of access log that dumps changes in LDIF.

Authentication

The process of verifying who is requesting access to a resource; the act of confirming the identity of a principal.

Authorization

The process of determining whether access should be granted to an individual based on information about that individual; the act of determining whether to grant or to deny a principal access to a resource.

Backend

Repository that stores directory data. Different implementations with different capabilities exist.

Binary copy

Binary backup archive of one directory server that can be restored on another directory server.

Bind operation

LDAP authentication operation to determine the client's identity in LDAP terms, the identity which is later used by the server to authorize (or not) access to directory data that the client wants to lookup or change.

Branch

The distinguished name (DN) of a non-leaf entry in the Directory Information Tree (DIT), and also that entry and all its subordinates taken together.

Some administrative operations allow you to include or exclude branches by specifying the DN of the branch.

See also Suffix.

Collective attribute

A standard mechanism for defining attributes that appear on all the entries in a particular subtree.

Compare operation

LDAP operation to compare a specified attribute value with the value stored on an entry in the directory.

Control

Information added to an LDAP message to further specify how an LDAP operation should be processed. DS supports many LDAP controls.

Database cache

Memory space set aside to hold database content.

debug log

Server log tracing details needed to troubleshoot a problem in the server.

Delete operation

LDAP operation to remove an existing entry or entries from the directory.

Directory

A directory is a network service which lists participants in the network such as users, computers, printers, and groups. The directory provides a convenient, centralized, and robust mechanism for publishing and consuming information about network participants.

Directory hierarchy

A directory can be organized into a hierarchy in order to make it easier to browse or manage. Directory hierarchies normally represent something in the physical world, such as organizational hierarchies or physical locations. For example, the top level of a directory may represent a company, the next level down divisions, the next level down departments, and down the hierarchy. Alternately, the top level may represent the world, the next level down countries, next states or provinces, and next cities.

Directory Information Tree (DIT)

A set of directory entries organized hierarchically in a tree structure, where the vertices are the entries and the arcs between vertices define relationships between entries

Directory manager

Default directory superuser who has privileges to do full administration of the DS server, including bypassing access control evaluation, changing access controls, and changing administrative privileges.

See also Superuser.

Directory object

A directory object is an item in a directory. Example objects include users, user groups, computers, and more. Objects may be organized into a hierarchy and contain identifying attributes.

See also Entry.

Directory proxy server

Server that forwards LDAP requests to remote directory servers. A standalone directory proxy server does not store user data.

See also Directory server.

Directory server

Server application for centralizing information about network participants. A highly available directory service consists of multiple directory servers configured to replicate directory data.

See also Directory, Replication.

Directory Services Markup Language (DSML)

Standard language to access directory services using XML. DMSL v1 defined an XML mapping of LDAP objects, while DSMLv2 maps the LDAP Protocol and data model to XML.

Distinguished name (DN)

Fully qualified name for a directory entry, such as uid=bjensen,ou=People,dc=example,dc=com, built by concatenating the entry RDN (uid=bjensen) with the DN of the parent entry (ou=People,dc=example,dc=com).

Domain

A replication domain consists of several directory servers sharing the same synchronized set of data.

The base DN of a replication domain specifies the base DN of the replicated data.

DSML gateway

Standalone web application that translates DSML requests from client applications to LDAP requests to a directory service, and LDAP responses from a directory service to DSML responses to client applications.

Dynamic group

Group that specifies members using LDAP URLs.

Entry

As generic and hierarchical data stores, directories always contain different kinds of entries, either nodes (or containers) or leaf entries. An entry is an object in the directory, defined by one of more object classes and their related attributes. At startup, DS servers report the number of entries contained in each suffix.

Entry cache

Memory space set aside to hold frequently accessed, large entries, such as static groups.

Equality index

Index used to match values that correspond exactly (though generally without case sensitivity) to the value provided in the search filter.

errors log

Server log tracing server events, error conditions, and warnings, categorized and identified by severity.

Export

Save directory data in an LDIF file.

Extended operation

Additional LDAP operation not included in the original standards. DS servers support several standard LDAP extended operations.

Extensible match index

Index for a matching rule other than approximate, equality, ordering, presence, substring or VLV, such as an index for generalized time.

External user

An individual that accesses company resources or services but is not working for the company. Typically a customer or partner.

Etime

Elapsed time within the server to process a request, starting from the moment the decoded operation is available to be processed by a worker thread.

Filter

An LDAP search filter is an expression that the server uses to find entries that match a search request, such as (mail=*@example.com) to match all entries having an email address in the example.com domain.

Group

Entry identifying a set of members whose entries are also in the directory.

Idle time limit

Defines how long DS allows idle connections to remain open.

Import

Read in and index directory data from an LDIF file.

Inactive user

An entry in the directory that once represented a user but which is now no longer able to be authenticated.

Index

Directory server backend feature to allow quick lookup of entries based on their attribute values.

See also Approximate index, Equality index, Extensible match index, Ordering index, Presence index, Substring index, Virtual list view (VLV) index, Index entry limit.

Index entry limit

When the number of entries that an index key points to exceeds the index entry limit, DS stops maintaining the list of entries for that index key.

Internal user

An individual who works within the company either as an employee or as a contractor.

LDAP Data Interchange Format (LDIF)

Standard, portable, text-based representation of directory content. See RFC 2849.

LDAP URL

LDAP Uniform Resource Locator such as ldap://directory.example.com:389/dc=example,dc=com??sub?(uid=bjensen). See RFC 2255.

LDAPS

LDAP over SSL.

Lightweight Directory Access Protocol (LDAP)

A simple and standardized network protocol used by applications to connect to a directory, search for objects and add, edit or remove objects. See RFC 4510.

Lookthrough limit

Defines the maximum number of candidate entries DS considers when processing a search.

Matching rule

Defines rules for performing matching operations against assertion values. Matching rules are frequently associated with an attribute syntax and are used to compare values according to that syntax. For example, the distinguishedNameEqualityMatch matching rule can be used to determine whether two DNs are equal and can ignore unnecessary spaces around commas and equal signs, differences in capitalization in attribute names, and other discrepancies.

Modify DN operation

LDAP modification operation to request that the server change the distinguished name of an entry.

Modify operation

LDAP modification operation to request that the server change one or more attributes of an entry.

Naming context

Base DN under which client applications can look for user data.

Object class

Identifies entries that share certain characteristics. Most commonly, an entry's object classes define the attributes that must and may be present on the entry. Object classes are stored on entries as values of the objectClass attribute. Object classes are defined in the directory schema, and can be abstract (defining characteristics for other object classes to inherit), structural (defining the basic structure of an entry, one structural inheritance per entry), or auxiliary (for decorating entries already having a structural object class with other required and optional attributes).

Object identifier (OID)

String that uniquely identifies an object, such as 0.9.2342.19200300.100.1.1 for the user ID attribute or 1.3.6.1.4.1.1466.115.121.1.15 for DirectoryString syntax.

Operational attribute

An attribute that has a special (operational) meaning for the server, such as pwdPolicySubentry or modifyTimestamp.

Ordering index

Index used to match values for a filter that specifies a range.

Password policy

A set of rules regarding what sequence of characters constitutes an acceptable password. Acceptable passwords are generally those that would be too difficult for another user or an automated program to guess and thereby defeat the password mechanism. Password policies may require a minimum length, a mixture of different types of characters (lowercase, uppercase, digits, punctuation marks, and other characters), avoiding dictionary words or passwords based on the user's name, and other attributes. Password policies may also require that users not reuse old passwords and that users change their passwords regularly.

Password reset

Password change performed by a user other than the user who owns the entry.

Password storage scheme

Mechanism for encoding user passwords stored on directory entries. DS implements a number of password storage schemes.

Password validator

Mechanism for determining whether a proposed password is acceptable for use. DS implements a number of password validators.

Plugin

Java library with accompanying configuration that implements a feature through processing that is not essential to the core operation of DS servers.

As the name indicates, plugins can be plugged in to an installed server for immediate configuration and use without recompiling the server.

DS servers invoke plugins at specific points in the lifecycle of a client request. The DS configuration framework lets directory administrators manage plugins with the same tools used to manage the server.

Presence index

Index used to match the fact that an attribute is present on the entry, regardless of the value.

Principal

Entity that can be authenticated, such as a user, a device, or an application.

Privilege

Server configuration settings controlling access to administrative operations such as exporting and importing data, restarting the server, performing password reset, and changing the server configuration.

Privileges are implemented independently from access control instructions (ACI), which apply to LDAP operations and user data.

See also Access control instruction (ACI).

Referential integrity

Ensuring that group membership remains consistent following changes to member entries.

referint log

Server log tracing referential integrity events, with entries similar to the errors log.

Referral

Reference to another directory location, which can be another directory server running elsewhere or another container on the same server, where the current operation can be processed.

Relative distinguished name (RDN)

Initial portion of a DN that distinguishes the entry from all other entries at the same level, such as uid=bjensen in uid=bjensen,ou=People,dc=example,dc=com.

Replica

Directory server this is configured to use replication.

Replication

Data synchronization that ensures all directory servers participating eventually share a consistent set of directory data.

replication log

Server log tracing replication events, with entries similar to the errors log.

Replication server

Server dedicated to transmitting replication messages. A standalone replication server does not store user data.

REST to LDAP gateway

Standalone web application that translates RESTful HTTP requests from client applications to LDAP requests to directory services, and LDAP responses from directory services to HTTP responses to client applications.

Root DSE

The directory entry with distinguished name "" (empty string), where DSE is an acronym for DSA-Specific Entry. DSA is an acronym for Directory Server Agent, a single directory server. The root DSE serves to expose information over LDAP about what the directory server supports in terms of LDAP controls, auth password schemes, SASL mechanisms, LDAP protocol versions, naming contexts, features, LDAP extended operations, and other information.

Schema

LDAP schema defines the object classes, attributes types, attribute value syntaxes, matching rules and other constrains on entries held by the directory server.

Search filter

See Filter.

Search operation

LDAP lookup operation where a client requests that the server return entries based on an LDAP filter and a base DN under which to search.

Simple authentication

Bind operation performed with a user's entry DN and user's password. Use simple authentication only if the network connection is secure.

Size limit

Sets the maximum number of entries returned for a search.

Static group

Group that enumerates member entries.

Subentry

An entry, such as a password policy entry, that resides with the user data but holds operational data, and is not visible in search results unless explicitly requested.

Substring index

Index used to match values specified with wildcards in the filter.

Suffix

The distinguished name (DN) of a root entry in the Directory Information Tree (DIT), and also that entry and all its subordinates taken together as a single object of administrative tasks such as export, import, indexing, and replication.

Superuser

User with privileges to perform unconstrained administrative actions on DS server. This account is analogous to the UNIX root and Windows Administrator accounts.

Superuser privileges include the following:

  • bypass-acl: The holder is not subject to access control.

  • privilege-change: The holder can edit administrative privileges.

  • proxied-auth: The holder can make requests on behalf of another user, including directory superusers.

The default superuser is cn=Directory Manager. You can create additional superuser accounts, each with different administrative privileges.

See also Directory manager, Privilege.

Task

Mechanism to provide remote access to server administrative functions. DS software supports tasks to back up and restore backends, to import and export LDIF files, and to stop and restart the server.

Time limit

Defines the maximum processing time DS devotes to a search operation.

Unbind operation

LDAP operation to release resources at the end of a session.

Unindexed search

Search operation for which no matching index is available. If no indexes are applicable, then the directory server potentially has to go through all entries to look for candidate matches. For this reason, the unindexed-search privilege, which allows users to request searches for which no applicable index exists, is reserved for the directory manager by default.

User

An entry that represents an individual that can be authenticated through credentials contained or referenced by its attributes. A user may represent an internal user or an external user, and may be an active user or an inactive user.

User attribute

An attribute for storing user data on a directory entry such as mail or givenname.

Virtual attribute

An attribute with dynamically generated values that appear in entries but are not persistently stored in the backend.

Virtual directory

An application that exposes a consolidated view of multiple physical directories over an LDAP interface. Consumers of the directory information connect to the virtual directory's LDAP service. Behind the scenes, requests for information and updates to the directory are sent to one or more physical directories where the actual information resides. Virtual directories enable organizations to create a consolidated view of information that for legal or technical reasons cannot be consolidated into a single physical copy.

Virtual list view (VLV) index

Browsing index designed to help the directory server respond to client applications that need, for example, to browse through a long list of results a page at a time in a GUI.

Virtual static group

DS group that lets applications see dynamic groups as what appear to be static groups.

X.500

A family of standardized protocols for accessing, browsing and maintaining a directory. X.500 is functionally similar to LDAP, but is generally considered to be more complex, and has consequently not been widely adopted.

Read a different version of :