--- title: dsconfig description: dsconfig — manage PingDS server configuration component: pingds version: 8.1 page_id: pingds:tools-reference:dsconfig canonical_url: https://docs.pingidentity.com/pingds/8.1/tools-reference/dsconfig.html section_ids: synopsis: Synopsis dsconfig-description: Description dsconfig-options: Options dsconfig-subcommands: Subcommands exit_codes: Exit codes dsconfig-examples: Examples --- # dsconfig `dsconfig` — manage PingDS server configuration ## Synopsis `dsconfig {subcommand} {options}` ## 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 * `--keyStorePath {keyStorePath}` The keystore containing the certificate which should be used for SSL client authentication. * `--keyStoreProviderArg {argument}` Configuration argument for the key store provider. * `--keyStoreProviderClass {class}` Full class name of the key store provider. * `--keyStoreProviderName {name}` Name of the key store provider. * `--keyStoreType {keyStoreType}` The type of the keystore (e.g. \[JKS|JCEKS|PKCS12|PKCS11|\]). * `-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. * `--trustStorePath {trustStorePath}` Use this truststore for validating server certificate. * `--trustStoreProviderArg {argument}` Configuration argument for the trust store provider. * `--trustStoreProviderClass {class}` Full class name of the trust store provider. * `--trustStoreProviderName {name}` Name of the trust store provider. * `--trustStoreType {trustStoreType}` The type of the truststore (e.g. \[JKS|JCEKS|JVM|PKCS12|\]). * `--usePasswordPolicyControl` Use the password policy request control. Default: false * `-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. ## Exit codes * 0 The command completed successfully. * \> 0 An error occurred. ## 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 ```