dsconfig — manage OpenDJ directory server configuration
dsconfig {subcommand} {options}
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 OpenDJ 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 OpenDJ directory 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.
The dsconfig command takes the following options:
Command options:
--batchReads 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.
--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
--displayCommandDisplay the equivalent non-interactive argument in the standard output when this command is run in interactive mode.
Default: false
--help-allDisplay all subcommands.
Default: false
--help-core-serverDisplay subcommands relating to core server.
Default: false
--help-databaseDisplay subcommands relating to caching and back-ends.
Default: false
--help-loggingDisplay subcommands relating to logging.
Default: false
--help-replicationDisplay subcommands relating to replication.
Default: false
--help-securityDisplay subcommands relating to authentication and authorization.
Default: false
--help-service-discoveryDisplay subcommands relating to service discovery mechanism.
Default: false
--help-user-managementDisplay subcommands relating to user management.
Default: false
Configuration Options
--advancedAllows the configuration of advanced components and properties.
Default: false
LDAP connection options:
-D | --bindDN {bindDN}DN to use to bind to the server.
Default: cn=Directory Manager
-E | --reportAuthzIDUse the authorization identity control.
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
-j | --bindPasswordFile {bindPasswordFile}Bind password file.
-K | --keyStorePath {keyStorePath}Certificate key store path.
-N | --certNickname {nickname}Nickname of the certificate that the server should use when accepting SSL-based connections or performing StartTLS negotiation.
-o | --saslOption {name=value}SASL bind options.
-p | --port {port}Directory server administration port number.
Default: 4444
-P | --trustStorePath {trustStorePath}Certificate trust store path.
-T | --trustStorePassword {trustStorePassword}Certificate trust store PIN.
-u | --keyStorePasswordFile {keyStorePasswordFile}Certificate key store PIN file. A PIN is required when you specify to use an existing certificate as server certificate.
-U | --trustStorePasswordFile {path}Certificate trust store PIN file.
--usePasswordPolicyControlUse the password policy request control.
Default: false
-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}Certificate key store PIN. A PIN is required when you specify to use an existing certificate as server certificate.
-X | --trustAllTrust 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-promptUse non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.
Default: false
--noPropertiesFileNo 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 | --quietUse quiet mode.
Default: false
-s | --script-friendlyUse script-friendly mode.
Default: false
-v | --verboseUse verbose mode.
Default: false
General options:
-V | --versionDisplay Directory Server version information.
Default: false
-H | --helpDisplay this usage information.
Default: false
The dsconfig command provides many subcommands.
Subcommands let you create, list, and delete entire configuration components, and also let you get and set component properties. Subcommands therefore 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.
$ dsconfig \
list-log-publishers \
--hostname opendj.example.com \
--port 4444 \
--bindDN "cn=Directory Manager" \
--bindPassword password \
--trustAll
Log Publisher : Type : enabled
------------------------------:------------------------:--------
File-Based Access Logger : file-based-access : true
File-Based Audit Logger : file-based-audit : false
File-Based Debug Logger : file-based-debug : false
File-Based Error Logger : file-based-error : true
File-Based HTTP Access Logger : file-based-http-access : false
Replication Repair Logger : file-based-error : true
$ dsconfig \
get-log-publisher-prop \
--publisher-name "File-Based Access Logger" \
--property rotation-policy \
--hostname opendj.example.com \
--port 4444 \
--bindDN "cn=Directory Manager" \
--bindPassword password \
--trustAll
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 following options to view help for subcommands.
Display all subcommands
Display subcommands relating to core server
Display subcommands relating to caching and back-ends
Display subcommands relating to logging
Display subcommands relating to replication
Display subcommands relating to authentication and authorization
Display subcommands relating to user management
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.
The dsconfig command supports the following subcommands:
dsconfig create-access-log-filtering-criteria: Creates Access Log Filtering Criteria
dsconfig create-account-status-notification-handler: Creates Account Status Notification Handlers
dsconfig create-alert-handler: Creates Alert Handlers
dsconfig create-backend: Creates Backends
dsconfig create-backend-index: Creates Backend Indexes
dsconfig create-backend-vlv-index: Creates Backend VLV Indexes
dsconfig create-certificate-mapper: Creates Certificate Mappers
dsconfig create-connection-handler: Creates Connection Handlers
dsconfig create-debug-target: Creates Debug Targets
dsconfig create-entry-cache: Creates Entry Caches
dsconfig create-extended-operation-handler: Creates Extended Operation Handlers
dsconfig create-group-implementation: Creates Group Implementations
dsconfig create-http-authorization-mechanism: Creates HTTP Authorization Mechanisms
dsconfig create-http-endpoint: Creates HTTP Endpoints
dsconfig create-identity-mapper: Creates Identity Mappers
dsconfig create-key-manager-provider: Creates Key Manager Providers
dsconfig create-log-publisher: Creates Log Publishers
dsconfig create-log-retention-policy: Creates Log Retention Policies
dsconfig create-log-rotation-policy: Creates Log Rotation Policies
dsconfig create-monitor-provider: Creates Monitor Providers
dsconfig create-password-generator: Creates Password Generators
dsconfig create-password-policy: Creates Authentication Policies
dsconfig create-password-storage-scheme: Creates Password Storage Schemes
dsconfig create-password-validator: Creates Password Validators
dsconfig create-plugin: Creates Plugins
dsconfig create-replication-domain: Creates Replication Domains
dsconfig create-replication-server: Creates Replication Servers
dsconfig create-sasl-mechanism-handler: Creates SASL Mechanism Handlers
dsconfig create-schema-provider: Creates Schema Providers
dsconfig create-service-discovery-mechanism: Creates Service Discovery Mechanisms
dsconfig create-synchronization-provider: Creates Synchronization Providers
dsconfig create-trust-manager-provider: Creates Trust Manager Providers
dsconfig create-virtual-attribute: Creates Virtual Attributes
dsconfig delete-access-log-filtering-criteria: Deletes Access Log Filtering Criteria
dsconfig delete-account-status-notification-handler: Deletes Account Status Notification Handlers
dsconfig delete-alert-handler: Deletes Alert Handlers
dsconfig delete-backend: Deletes Backends
dsconfig delete-backend-index: Deletes Backend Indexes
dsconfig delete-backend-vlv-index: Deletes Backend VLV Indexes
dsconfig delete-certificate-mapper: Deletes Certificate Mappers
dsconfig delete-connection-handler: Deletes Connection Handlers
dsconfig delete-debug-target: Deletes Debug Targets
dsconfig delete-entry-cache: Deletes Entry Caches
dsconfig delete-extended-operation-handler: Deletes Extended Operation Handlers
dsconfig delete-group-implementation: Deletes Group Implementations
dsconfig delete-http-authorization-mechanism: Deletes HTTP Authorization Mechanisms
dsconfig delete-http-endpoint: Deletes HTTP Endpoints
dsconfig delete-identity-mapper: Deletes Identity Mappers
dsconfig delete-key-manager-provider: Deletes Key Manager Providers
dsconfig delete-log-publisher: Deletes Log Publishers
dsconfig delete-log-retention-policy: Deletes Log Retention Policies
dsconfig delete-log-rotation-policy: Deletes Log Rotation Policies
dsconfig delete-monitor-provider: Deletes Monitor Providers
dsconfig delete-password-generator: Deletes Password Generators
dsconfig delete-password-policy: Deletes Authentication Policies
dsconfig delete-password-storage-scheme: Deletes Password Storage Schemes
dsconfig delete-password-validator: Deletes Password Validators
dsconfig delete-plugin: Deletes Plugins
dsconfig delete-replication-domain: Deletes Replication Domains
dsconfig delete-replication-server: Deletes Replication Servers
dsconfig delete-sasl-mechanism-handler: Deletes SASL Mechanism Handlers
dsconfig delete-schema-provider: Deletes Schema Providers
dsconfig delete-service-discovery-mechanism: Deletes Service Discovery Mechanisms
dsconfig delete-synchronization-provider: Deletes Synchronization Providers
dsconfig delete-trust-manager-provider: Deletes Trust Manager Providers
dsconfig delete-virtual-attribute: Deletes Virtual Attributes
dsconfig get-access-control-handler-prop: Shows Access Control Handler properties
dsconfig get-access-log-filtering-criteria-prop: Shows Access Log Filtering Criteria properties
dsconfig get-account-status-notification-handler-prop: Shows Account Status Notification Handler properties
dsconfig get-administration-connector-prop: Shows Administration Connector properties
dsconfig get-alert-handler-prop: Shows Alert Handler properties
dsconfig get-backend-index-prop: Shows Backend Index properties
dsconfig get-backend-prop: Shows Backend properties
dsconfig get-backend-vlv-index-prop: Shows Backend VLV Index properties
dsconfig get-certificate-mapper-prop: Shows Certificate Mapper properties
dsconfig get-connection-handler-prop: Shows Connection Handler properties
dsconfig get-crypto-manager-prop: Shows Crypto Manager properties
dsconfig get-debug-target-prop: Shows Debug Target properties
dsconfig get-entry-cache-prop: Shows Entry Cache properties
dsconfig get-extended-operation-handler-prop: Shows Extended Operation Handler properties
dsconfig get-external-changelog-domain-prop: Shows External Changelog Domain properties
dsconfig get-global-configuration-prop: Shows Global Configuration properties
dsconfig get-group-implementation-prop: Shows Group Implementation properties
dsconfig get-http-authorization-mechanism-prop: Shows HTTP Authorization Mechanism properties
dsconfig get-http-endpoint-prop: Shows HTTP Endpoint properties
dsconfig get-identity-mapper-prop: Shows Identity Mapper properties
dsconfig get-key-manager-provider-prop: Shows Key Manager Provider properties
dsconfig get-log-publisher-prop: Shows Log Publisher properties
dsconfig get-log-retention-policy-prop: Shows Log Retention Policy properties
dsconfig get-log-rotation-policy-prop: Shows Log Rotation Policy properties
dsconfig get-monitor-provider-prop: Shows Monitor Provider properties
dsconfig get-password-generator-prop: Shows Password Generator properties
dsconfig get-password-policy-prop: Shows Authentication Policy properties
dsconfig get-password-storage-scheme-prop: Shows Password Storage Scheme properties
dsconfig get-password-validator-prop: Shows Password Validator properties
dsconfig get-plugin-prop: Shows Plugin properties
dsconfig get-plugin-root-prop: Shows Plugin Root properties
dsconfig get-replication-domain-prop: Shows Replication Domain properties
dsconfig get-replication-server-prop: Shows Replication Server properties
dsconfig get-root-dn-prop: Shows Root DN properties
dsconfig get-root-dse-backend-prop: Shows Root DSE Backend properties
dsconfig get-sasl-mechanism-handler-prop: Shows SASL Mechanism Handler properties
dsconfig get-schema-provider-prop: Shows Schema Provider properties
dsconfig get-service-discovery-mechanism-prop: Shows Service Discovery Mechanism properties
dsconfig get-synchronization-provider-prop: Shows Synchronization Provider properties
dsconfig get-trust-manager-provider-prop: Shows Trust Manager Provider properties
dsconfig get-virtual-attribute-prop: Shows Virtual Attribute properties
dsconfig get-work-queue-prop: Shows Work Queue properties
dsconfig list-access-log-filtering-criteria: Lists existing Access Log Filtering Criteria
dsconfig list-account-status-notification-handlers: Lists existing Account Status Notification Handlers
dsconfig list-alert-handlers: Lists existing Alert Handlers
dsconfig list-backend-indexes: Lists existing Backend Indexes
dsconfig list-backend-vlv-indexes: Lists existing Backend VLV Indexes
dsconfig list-backends: Lists existing Backends
dsconfig list-certificate-mappers: Lists existing Certificate Mappers
dsconfig list-connection-handlers: Lists existing Connection Handlers
dsconfig list-debug-targets: Lists existing Debug Targets
dsconfig list-entry-caches: Lists existing Entry Caches
dsconfig list-extended-operation-handlers: Lists existing Extended Operation Handlers
dsconfig list-group-implementations: Lists existing Group Implementations
dsconfig list-http-authorization-mechanisms: Lists existing HTTP Authorization Mechanisms
dsconfig list-http-endpoints: Lists existing HTTP Endpoints
dsconfig list-identity-mappers: Lists existing Identity Mappers
dsconfig list-key-manager-providers: Lists existing Key Manager Providers
dsconfig list-log-publishers: Lists existing Log Publishers
dsconfig list-log-retention-policies: Lists existing Log Retention Policies
dsconfig list-log-rotation-policies: Lists existing Log Rotation Policies
dsconfig list-monitor-providers: Lists existing Monitor Providers
dsconfig list-password-generators: Lists existing Password Generators
dsconfig list-password-policies: Lists existing Password Policies
dsconfig list-password-storage-schemes: Lists existing Password Storage Schemes
dsconfig list-password-validators: Lists existing Password Validators
dsconfig list-plugins: Lists existing Plugins
dsconfig list-properties: Describes managed objects and their properties
dsconfig list-replication-domains: Lists existing Replication Domains
dsconfig list-replication-server: Lists existing Replication Server
dsconfig list-sasl-mechanism-handlers: Lists existing SASL Mechanism Handlers
dsconfig list-schema-providers: Lists existing Schema Providers
dsconfig list-service-discovery-mechanisms: Lists existing Service Discovery Mechanisms
dsconfig list-synchronization-providers: Lists existing Synchronization Providers
dsconfig list-trust-manager-providers: Lists existing Trust Manager Providers
dsconfig list-virtual-attributes: Lists existing Virtual Attributes
dsconfig set-access-control-handler-prop: Modifies Access Control Handler properties
dsconfig set-access-log-filtering-criteria-prop: Modifies Access Log Filtering Criteria properties
dsconfig set-account-status-notification-handler-prop: Modifies Account Status Notification Handler properties
dsconfig set-administration-connector-prop: Modifies Administration Connector properties
dsconfig set-alert-handler-prop: Modifies Alert Handler properties
dsconfig set-backend-index-prop: Modifies Backend Index properties
dsconfig set-backend-prop: Modifies Backend properties
dsconfig set-backend-vlv-index-prop: Modifies Backend VLV Index properties
dsconfig set-certificate-mapper-prop: Modifies Certificate Mapper properties
dsconfig set-connection-handler-prop: Modifies Connection Handler properties
dsconfig set-crypto-manager-prop: Modifies Crypto Manager properties
dsconfig set-debug-target-prop: Modifies Debug Target properties
dsconfig set-entry-cache-prop: Modifies Entry Cache properties
dsconfig set-extended-operation-handler-prop: Modifies Extended Operation Handler properties
dsconfig set-external-changelog-domain-prop: Modifies External Changelog Domain properties
dsconfig set-global-configuration-prop: Modifies Global Configuration properties
dsconfig set-group-implementation-prop: Modifies Group Implementation properties
dsconfig set-http-authorization-mechanism-prop: Modifies HTTP Authorization Mechanism properties
dsconfig set-http-endpoint-prop: Modifies HTTP Endpoint properties
dsconfig set-identity-mapper-prop: Modifies Identity Mapper properties
dsconfig set-key-manager-provider-prop: Modifies Key Manager Provider properties
dsconfig set-log-publisher-prop: Modifies Log Publisher properties
dsconfig set-log-retention-policy-prop: Modifies Log Retention Policy properties
dsconfig set-log-rotation-policy-prop: Modifies Log Rotation Policy properties
dsconfig set-monitor-provider-prop: Modifies Monitor Provider properties
dsconfig set-password-generator-prop: Modifies Password Generator properties
dsconfig set-password-policy-prop: Modifies Authentication Policy properties
dsconfig set-password-storage-scheme-prop: Modifies Password Storage Scheme properties
dsconfig set-password-validator-prop: Modifies Password Validator properties
dsconfig set-plugin-prop: Modifies Plugin properties
dsconfig set-plugin-root-prop: Modifies Plugin Root properties
dsconfig set-replication-domain-prop: Modifies Replication Domain properties
dsconfig set-replication-server-prop: Modifies Replication Server properties
dsconfig set-root-dn-prop: Modifies Root DN properties
dsconfig set-root-dse-backend-prop: Modifies Root DSE Backend properties
dsconfig set-sasl-mechanism-handler-prop: Modifies SASL Mechanism Handler properties
dsconfig set-schema-provider-prop: Modifies Schema Provider properties
dsconfig set-service-discovery-mechanism-prop: Modifies Service Discovery Mechanism properties
dsconfig set-synchronization-provider-prop: Modifies Synchronization Provider properties
dsconfig set-trust-manager-provider-prop: Modifies Trust Manager Provider properties
dsconfig set-virtual-attribute-prop: Modifies Virtual Attribute properties
dsconfig set-work-queue-prop: Modifies Work Queue properties
Much of the OpenDJ Administration Guide consists of dsconfig examples with text in between. This section therefore remains short.
The following example starts dsconfig 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) Log Publisher
2) Access Log Filtering Criteria 23) Log Retention Policy
3) Account Status Notification Handler 24) Log Rotation Policy
4) Administration Connector 25) Monitor Provider
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 DN
14) Extended Operation Handler 35) Root DSE Backend
15) External Changelog Domain 36) SASL Mechanism Handler
16) Global Configuration 37) Schema Provider
17) Group Implementation 38) Synchronization Provider
18) HTTP Authorization Mechanism 39) Trust Manager Provider
19) HTTP Endpoint 40) Virtual Attribute
20) Identity Mapper 41) Work Queue
21) Key Manager Provider
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: 19/Oct/2011:08:52:22 +0000
# Session operation number: 1
# Operation date: 19/Oct/2011:08:55:06 +0000
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 dsconfig,
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.