dsconfig
dsconfig — manage OpenDJ server configuration
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.
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: /path/to/opendj/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: uid=admin
-E | --reportAuthzId-
Use the authorization identity control. Default: false
-h | --hostname {host}-
Fully-qualified server host name or IP address. Default: localhost.localdomain
-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[:env|:file] {trustStorePassword}-
Truststore password which will be used as the cleartext configuration value.
--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 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[:env|:file] {bindPassword}-
Password to use to bind to the server. Omit this option while providing the bind DN to ensure that the command prompts for the password, rather than entering the password as a command argument.
-W | --keyStorePassword[:env|:file] {keyStorePassword}-
Keystore password which will be used as the cleartext configuration value.
-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
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- 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:
# Get the log publishers' names:
$ dsconfig \
list-log-publishers \
--hostname localhost \
--port 4444 \
--bindDN uid=admin \
--bindPassword password \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePassword:file /path/to/opendj/config/keystore.pin \
--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 localhost \
--port 4444 \
--bindDN uid=admin \
--bindPassword password \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePassword:file /path/to/opendj/config/keystore.pin \
--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 -
y: years
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.
Examples
The following example starts the dsconfig command in interactive, menu-driven mode:
$ dsconfig \
--hostname localhost \
--port 4444 \
--bindDn "uid=admin" \
--bindPassword password \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePassword:file /path/to/opendj/config/keystore.pin
>>>> OpenDJ configuration console main menu
What do you want to configure?
1) Access Control Handler 21) Log Publisher
2) Access Log Filtering Criteria 22) Log Retention Policy
3) Account Status Notification Handler 23) Log Rotation Policy
4) Administration Connector 24) Mail Server
5) Alert Handler 25) Password Generator
6) Backend 26) Password Policy
7) Backend Index 27) Password Storage Scheme
8) Backend VLV Index 28) Password Validator
9) Certificate Mapper 29) Plugin
10) Connection Handler 30) Plugin Root
11) Crypto Manager 31) Replication Domain
12) Debug Target 32) Replication Server
13) Entry Cache 33) Root DSE Backend
14) Extended Operation Handler 34) SASL Mechanism Handler
15) Global Access Control Policy 35) Schema Provider
16) Global Configuration 36) Service Discovery Mechanism
17) HTTP Authorization Mechanism 37) Synchronization Provider
18) HTTP Endpoint 38) Trust Manager Provider
19) Identity Mapper 39) Virtual Attribute
20) Key Manager Provider 40) Work Queue
a) show advanced components and properties
q) quit
Enter choice:
Use the interactive mode to discover the commands that you can reuse to script configuration changes. When you apply a change in interactive mode, the dsconfig command displays the corresponding command.
When the server is stopped, you can run the commands offline, and batch them together. The following example sets global properties, and creates a logger that writes messages to the console:
dsconfig --offline --no-prompt --batch << END_OF_COMMAND_INPUT
set-global-configuration-prop --set "server-id:&{ds.server.id|evaluation-only}"
set-global-configuration-prop --set "group-id:&{ds.group.id|default}"
set-global-configuration-prop --set "advertised-listen-address:&{ds.advertised.listen.address|localhost}"
create-log-publisher --type console-error --publisher-name "Console Error Logger" --set enabled:true
END_OF_COMMAND_INPUT