Directory Services 7.4.3

dsconfig

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: /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.

--providerArg {argument}

Configuration argument for the PKCS#11 provider.

--providerClass {class}

Full class name of the PKCS#11 provider.

--providerName {name}

Name of the PKCS#11 provider.

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

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