dsconfig — manage OpenDJ 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: /mnt/scratch/workspaces/workspace/ds-release_sustaining_7.0.x/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 {trustStorePassword}

Truststore cleartext password.

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

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 "uid=admin" \
 --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 "uid=admin" \
 --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
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 on the default port of the current host:

$ dsconfig --hostname opendj.example.com --port 4444 --bindDn "uid=admin" --bindPassword 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)  Mail Server
    6)   Backend                              27)  Password Generator
    7)   Backend Index                        28)  Password Policy
    8)   Backend VLV Index                    29)  Password Storage Scheme
    9)   Certificate Mapper                   30)  Password Validator
    10)  Connection Handler                   31)  Plugin
    11)  Crypto Manager                       32)  Plugin Root
    12)  Debug Target                         33)  Replication Domain
    13)  Entry Cache                          34)  Replication Server
    14)  Extended Operation Handler           35)  Root DSE Backend
    15)  External Changelog Domain            36)  SASL Mechanism Handler
    16)  Global Access Control Policy         37)  Schema Provider
    17)  Global Configuration                 38)  Service Discovery Mechanism
    18)  Group Implementation                 39)  Synchronization Provider
    19)  HTTP Authorization Mechanism         40)  Trust Manager Provider
    20)  HTTP Endpoint                        41)  Virtual Attribute
    21)  Identity Mapper                      42)  Work Queue

    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 "uid=admin" \
 --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 uid=admin \
          --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 uid=admin \
          --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
uid=admin
--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.

dsconfig — manage OpenDJ server configuration

Synopsis

Description

Options

Subcommands

Exit Codes

Examples

Mark Craig