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:
--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.
--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
--displayCommand
Display the equivalent non-interactive argument in the standard output when this command is run in interactive mode.
Default: false
--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 back-ends.
Default: false
--help-logging
Display subcommands relating to logging.
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
Configuration Options
--advanced
Allows 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 | --reportAuthzID
Use 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.
--usePasswordPolicyControl
Use 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 | --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
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-component
s
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.