PingDirectory

About the dsconfig configuration tool

The dsconfig tool is the text-based management tool used to configure the underlying server configuration.

The dsconfig tool has three operational modes: interactive mode, non-interactive mode, and batch mode.

The dsconfig tool offers an offline mode using the --offline option, in which the server does not have to be running to interact with the configuration. In most cases, you should keep the server running when you access the configuration for the server to give the user feedback about the validity of the configuration.

To view the options for the dsconfig tool, change to the PingDirectory/bin directory, and enter ./dsconfig --help. Example output is shown below.

./dsconfig --help

View and edit the Directory Server configuration.
This utility offers three primary modes of operation, the interactive mode, the non-interactive mode
and batch mode.  The interactive mode supports viewing and editing the configuration via an intuitive,
menu driven environment.  Running dsconfig in interactive command-line mode provides a user-friendly,
menu-driven interface for accessing and configuring the server. To start dsconfig in interactive
command-line mode, simply invoke the dsconfig shell script or batch file without any arguments.

The dsconfig non-interactive command-line mode provides a simple way to make arbitrary changes to the
Ping Identity Directory Server by invoking it on the command-line. If you want to use administrative
scripts to automate the configuration process, then run the dsconfig command in non-interactive mode.

The dsconfig tool provides a batching mechanism that reads multiple dsconfig invocations from a file
and executes them sequentially.  The batch file provides advantages over standard scripting in that it
minimizes LDAP connections and JVM invocations that normally occur with each dsconfig call.  You can
view the logs/config-audit.log file to review the configuration changes made to the Ping Identity
Directory Server and use them in the batch file.

Subcommands

  See the Usage section for instructions on viewing the list of supported subcommands.

Usage:  dsconfig  {options}
        where {options} include:

    --applyChangeTo [server-group|server-group-force|single-server]
        Controls whether changes apply to a single server or all servers in the configuration server group
    --offline
        Interact with the local configuration while the server is offline.  Not for use while the server
        is running
    -r, --reason {reason}
        A string describing the reason for the configuration change
    --help-classifications
        Display subcommands relating to connection and operation classification
    --help-core-server
        Display subcommands relating to core
    --help-database
        Display subcommands relating to backends, indexing, and caching
    --help-logging
        Display subcommands relating to logging, monitoring, and notifications
    --help-replication
        Display subcommands relating to replication
    --help-security
        Display subcommands relating to security and authorization
    --help-topology
        Display subcommands relating to topology
    --help-user-management
        Display subcommands relating to authentication and password management
    --help-web
        Display subcommands relating to web services and applications
    --help-subcommands
        Display all subcommands

  Configuration Options

    --advanced
        Allow the configuration of advanced components and properties

  LDAP Connection Options

    -Z, --useSSL
        Use SSL for secure communication with the server
    -q, --useStartTLS
        Use StartTLS to secure communication with the server
    --useNoSecurity
        Use no security when communicating with the server
    -h, --hostname {host}  [Default: localhost]
        Directory Server hostname or IP address
    -p, --port {port}  [Default: 389]
        Directory Server port number
    -D, --bindDN {bindDN}  [Default: cn=Directory Manager]
        DN used to bind to the server
    -w, --bindPassword {bindPassword}
        Password used to bind to the server
    -j, --bindPasswordFile {bindPasswordFile}
        Bind password file
    -o, --saslOption {name=value}
        SASL bind options (can be specified multiple times)
    -X, --trustAll
        Trust all server SSL certificates
    -P, --trustStorePath {truststorePath}  [Default: /Users/rowannabobo/Desktop/PingDirectory_9.2/config/truststore]
        Certificate truststore path
    -T, --trustStorePassword {truststorePassword}
        Certificate truststore PIN
    -U, --trustStorePasswordFile {path}
        Certificate truststore PIN file
    --trustStoreFormat {trustStoreFormat}
        Certificate truststore format
    -K, --keyStorePath {keystorePath}
        Certificate keystore path
    -W, --keyStorePassword {keystorePassword}
        Certificate keystore PIN
    -u, --keyStorePasswordFile {keystorePasswordFile}
        Certificate keystore PIN file
    --keyStoreFormat {keyStoreFormat}
        Certificate keystore format
    -N, --certNickname {nickname}
        Nickname of the certificate for SSL client authentication

  Utility Input/Output Options

    -v, --verbose
        Use verbose mode
    -Q, --quiet
        Use quiet mode
    -n, --no-prompt
        Use non-interactive mode.  If data in the command is missing, you will not be prompted and the
        tool will fail
    -F, --batch-file {batchFilePath}
        Path to a file containing a sequence of dsconfig commands to run
    --batch-continue-on-error
        Force the execution of all commands in the batch file on the server even if prevalidation fails.
        Execution will also continue even if one of the commands fails.
        Please note that commands affecting multiple servers can still fail to execute unless the
        --applyChangeTo argument is provided with the value server-group-force. Only applies if the batch
        file argument is also supplied.
    --dry-run
        Validate configuration changes but do not apply them. This option can only be used along with the
        -F/--batch-file option
    --propertiesFilePath {propertiesFilePath}
        Path to the file that contains default property values used for command-line arguments
    --noPropertiesFile
        Specify that no properties file will be used to get default command-line argument values
    --script-friendly
        Use script-friendly mode

  General Options

    -V, --version
        Display Directory Server version information
    -?, -H, --help
        Display general usage information
    --help-ldap
        Display help for using LDAP options
    --help-sasl
        Display help for using SASL options
    --help-debug
        Display help for using debug options

Examples

  Start dsconfig in interactive mode:

    dsconfig

  Use non-interactive mode to change the amount memory used for caching database contents and to specify
  common parent DNs that should be compacted in the underlying database:

    dsconfig --no-prompt --bindDN uid=admin,dc=example,dc=com \
         --bindPassword password set-backend-prop --backend-name userRoot \
         --set db-cache-percent:40 \
         --add compact-common-parent-dn:ou=accts,dc=example,dc=com \
         --add compact-common-parent-dn:ou=subs,dc=example,dc=com

  Use batch mode to read and execute a series of commands in a batch file:

    dsconfig --bindDN uid=admin,dc=example,dc=com --bindPassword password \
         --no-prompt --batch-file /path/to/config-batch.txt

  List information about all available configuration properties for all objects, including inherited properties:

    dsconfig list-properties --offline --inherited

  For examples and help with LDAP options see --help-ldap.  For help with SASL authentication, see --help-sasl