Directory Services 7.4.3

Maintenance tools

Server commands

  • Add DS server command-line tools to your PATH:

    • Bash

    • PowerShell

    $ export PATH=/path/to/opendj/bin:$\{PATH}
    PS C:\path\to> $env:PATH += ";C:\path\to\opendj\bat"

  • For reference information, use the --help option with any DS tool.

  • All commands call Java programs. This means every command starts a JVM, so it takes longer to start than a native binary.

  • The DS bash-completion command generates a completion script for the Bash shell that makes it easier to write other DS commands.

    The completion script depends on support for bash-completion, which is not included by default on macOS.

    To set up Bash completion for DS commands, source the output of the script:

    • Bash 4

    • Bash 3.2 macOS

    source <(/path/to/opendj/bin/bash-completion)
    # First, install bash-completion support.
# Next:
eval "$( /path/to/opendj/bin/bash-completion )"

    You can make completion available in any new interactive shell by adding it to your ~/.bash_profile file, or ~/.bashrc file if it is loaded by the new shell.

DS running on…​ DS installed from…​ Default path to tools…​

Linux distributions

.zip

/path/to/opendj/bin

Linux distributions

.deb, .rpm

/opt/opendj/bin

Microsoft Windows

.zip

C:\path\to\opendj\bat

The installation and upgrade tools, setup, and upgrade, are found in the parent directory of the other tools. These tools are not used for everyday administration.

Commands Constraints

dsbackup
dsconfig
export-ldif
import-ldif
rebuild-index
setup
setup-profile
start-ds

When the server is offline, or when running commands in offline mode, these commands can modify server files. They must, therefore, access server files as a user who has the same filesystem permissions as the user who installs and runs the server.

For most systems, the simplest way to achieve this is to run the command as the same user who installs and runs the server. When following best practices for auditing and separation of duty, provision administrative and server user accounts with compatible group or access control list permissions.

backendstat
create-rc-script
encode-password
setup
setup-profile
start-ds
supportextract
upgrade
windows-service

These commands must be used with the local DS server in the same installation as the tools.

These commands are not useful with non-DS servers.

dsbackup
changelogstat
dsconfig
dsrepl
encode-password
export-ldif
import-ldif
manage-account
manage-tasks
rebuild-index
status
stop-ds
verify-index

These commands must be used with DS servers having the same version as the command.

These commands are not useful with non-DS servers.

makeldif

This command depends on template files. The template files can make use of configuration files installed with DS servers under config/MakeLDIF/.

The LDIF output can be used with any directory server.

base64
ldapcompare
ldapdelete
ldapmodify
ldappasswordmodify
ldapsearch
ldifdiff
ldifmodify
ldifsearch

These commands can be used independently of DS servers, and are not tied to a specific version.
Command(1) Description

addrate

Measure add and delete throughput and response time.

authrate

Measure bind throughput and response time.

backendstat

Debug databases for pluggable backends.

base64

Encode and decode data in base64 format.

Base64-encoding represents binary data in ASCII, and can be used to encode character strings in LDIF, for example.

bash-completion

Generate a completion script for use with Bash shell. Requires bash-completion support.

changelogstat

Debug file-based changelog databases.

create-rc-script (Linux)

Generate a systemd service to start, stop, and restart the server, either directly or at system boot and shutdown.

This lets you register and manage DS servers as services on Linux systems.

dsbackup

Back up or restore directory data.

dskeymgr

Generate a deployment ID, a shared master key, a private CA certificate based on a deployment ID and password, or a key pair with the certificate signed by the private CA.

dsconfig

The dsconfig command is the primary command-line tool for viewing and editing DS server configurations. When started without arguments, dsconfig prompts you for administration connection information. Once connected to a running server, it presents you with a menu-driven interface to the server configuration.

To edit the configuration when the server is not running, use the --offline command.

Some advanced properties are not visible by default when you run the dsconfig command interactively. Use the --advanced option to access advanced properties.

When you pass connection information, subcommands, and additional options to dsconfig, the command runs in script mode, so it is not interactive.

You can prepare dsconfig batch scripts with the --commandFilePath option in interactive mode, then read 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 with the --batch option.

dsrepl

Manage data replication between directory servers to keep their contents in sync.

encode-password

Encode a plaintext password according to one of the available storage schemes.

export-ldif

Export directory data to LDIF, the standard, portable, text-based representation of directory content.

import-ldif

Load LDIF content into the directory, which overwrites existing data. It cannot be used to append data to the backend database.

ldapcompare

Compare the attribute values you specify with those stored on entries in the directory.

ldapdelete

Delete one entry or an entire branch of subordinate entries in the directory.

ldapmodify

Modify the specified attribute values for the specified entries.

ldappasswordmodify

Modify user passwords.

ldapsearch

Search a branch of directory data for entries that match the LDAP filter you specify.

ldifdiff

Display differences between two LDIF files. The output is LDIF.

ldifmodify

Similar to the ldapmodify command, modify specified attribute values for specified entries in an LDIF file.

ldifsearch

Similar to the ldapsearch command, search a branch of data in LDIF for entries matching the LDAP filter you specify.

makeldif

Generate directory data in LDIF based on templates that define how the data should appear.

The makeldif command generates test data that mimics data expected in production, and does not compromise real, potentially private information.

manage-account

Lock and unlock user accounts, and view and manipulate password policy state information.

manage-tasks

View information about tasks scheduled to run in the server, and cancel specified tasks.

modrate

Measure modification throughput and response time.

rebuild-index

Rebuild an index stored in an indexed backend.

searchrate

Measure search throughput and response time.

setup-profile

Configure a setup profile after initial installation.

start-ds

Start one DS server.

status

Display information about the server.

stop-ds

Stop one DS server.

supportextract

Collect troubleshooting information for technical support purposes.

verify-index

Verify that an index stored in an indexed backend is not corrupt.

windows-service (Windows)

Register and manage one DS server as a Windows service.

(1) Linux names for the commands. Equivalent Windows commands have .bat extensions.

Trusted certificates

When a client tool initiates a secure connection to a server, the server presents its digital certificate.

The tool must decide whether it does trust the server certificate and continues to negotiate a secure connection, or doesn’t trust the server certificate and drops the connection. To trust the server certificate, the tool’s truststore must contain the trusted certificate. The trusted certificate is a CA certificate, or the self-signed server certificate.

The following table explains how the tools locate the truststore.

Truststore Option Truststore Used

None

The default truststore, user.home/.opendj/keystore, where user.home is the Java system property. user.home is $HOME on Linux and %USERPROFILE% on Windows. The keystore password is OpenDJ. Do not change the file name or the password.

  • In interactive mode, DS command-line tools prompt for approval to trust an unrecognized certificate, and whether to store it in the default truststore for future use.

  • In silent mode, the tools rely on the default truststore.

--use<Type>TrustStore {trustStorePath}

DS only uses the specified truststore. The <Type> in the option name reflects the trust store type.

The tool fails with an error if it can’t trust the server certificate.

Default settings

You can set defaults in the ~/.opendj/tools.properties file, as in the following example:

hostname=localhost
port=4444
bindDN=editable:dsAdminDN["uid=admin"]
bindPassword\:file=/path/to/.pwd
useSsl=true
trustAll=true

When you use an option with a colon, such as bindPassword:file, escape the colon with a backslash (\:) in the properties file.

The file location on Windows is %UserProfile%\.opendj\tools.properties.