dsctl Commands for Managing 389 Directory Server Instances

After dscreate finishes, confirm which instances exist on the host and whether ns-slapd is accepting connections.

dsctl -l

Sample output:

slapd-ldap1
slapd-localhost

The lines show the configuration directory prefix (slapd-NAME). Pass only the short instance name to later commands:

dsctl ldap1 status

Sample output:

Instance "ldap1" is running

status reports the local process state. It does not prove remote LDAP clients can reach port 389 — verify listeners separately with ss -lntp or an ldapsearch against the suffix.

Automation tools can parse -j output instead of scraping plain text. Place -j before the instance name.

dsctl -j ldap1 status

Sample output:

{
    "type": "result",
    "running": true
}

A running value of false means ns-slapd is stopped or failed — check journalctl -u dirsrv@ldap1 next.

Offline exports, reindexing, and index-check require a stopped instance. Stop cleanly before touching database files.

dsctl ldap1 stop

Sample output:

Instance "ldap1" has been stopped

Confirm the process is gone:

dsctl ldap1 status

Sample output:

Instance "ldap1" is not running

Bring the server back when maintenance finishes:

dsctl ldap1 start

Sample output:

Instance "ldap1" has been started

db2ldif reads the on-disk database files directly while the server is stopped. Use it when you need an LDIF export without an online export task. For LDIF export on a running server, use dsconf ldap1 backend export instead — see import and export LDIF.

dsctl ldap1 stop

dsctl ldap1 db2ldif userroot /var/lib/dirsrv/slapd-ldap1/ldif/cs-export.ldif

Sample output:

ldiffile: /var/lib/dirsrv/slapd-ldap1/ldif/cs-export.ldif
db2ldif successful

List LDIF files the tool tracks:

dsctl ldap1 ldifs

Sample output:

cs-export.ldif (dc=example,dc=com), Created (2026-07-15 13:45:59), Size (8.0K)

Restart the instance before clients connect again:

dsctl ldap1 start

healthcheck is read-only and safe on a running instance. It inspects local configuration, backends, TLS, logs, and replication state.

dsctl ldap1 healthcheck

Sample output (tail):

Checking tls:certificate_expiration ...
Checking logs:notes ...
Checking tunables:thp ...
Healthcheck complete.
No issues found.

List individual checks when you want to run a subset:

dsctl ldap1 healthcheck --list-checks

Sample output (trimmed):

config:accesslog_buffering
backends:userroot:search
encryption:check_tls_version
fschecks:file_perms

Before clients trust LDAPS, confirm which CA and server certificate the instance presents.

dsctl ldap1 tls list-ca

Sample output:

Self-Signed-CA

Show the active server certificate:

dsctl ldap1 tls show-server-cert

Sample output (trimmed):

Certificate:
    Data:
        Version: 3 (0x2)
        Subject: "CN=ldap1.example.com,..."
        Validity:
            Not Before: Wed Jul 15 08:12:48 2026
            Not After : Sat Jul 15 08:12:48 2028

For production certificates, generate a CSR with dsctl ldap1 tls generate-server-cert-csr, sign it with your CA, import the CA with import-ca (server signing chain) or import-client-ca (client authentication trust), then import the signed cert with import-server-cert or import-server-key-cert. Export with export-cert NICKNAME --output-file /path/to/out.pem.

Importing a certificate updates the instance NSS database, but you must also ensure that the intended certificate is selected and active. Follow the TLS chapter for trust flags and certificate selection. Restart the instance when your workflow does not perform online certificate refresh — newer Red Hat Directory Server builds also support online TLS refresh through dsconf.

ldifgen builds LDIF you can import with ldapadd or offline ldif2db. See the ldifgen test-data guide for all generators (users, groups, mod-load, nested, and more). For ldif2db, write the file directly under the instance LDIF directory so ownership and SELinux labels match what Red Hat documents for imports.

dsctl ldap1 ldifgen users --number 2 --suffix dc=example,dc=com --generic --ldif-file /var/lib/dirsrv/slapd-ldap1/ldif/cs-users.ldif

Sample output:

Generating LDIF with the following options:
 - number=2
 - suffix=dc=example,dc=com
 - generic=True
 ...
Writing LDIF ...
Successfully created LDIF file: /var/lib/dirsrv/slapd-ldap1/ldif/cs-users.ldif

The --generic flag creates uid=user#### entries compatible with ldclt load tools. Add --parent ou=people,dc=example,dc=com when you want a fixed organizational unit.

If you generate under /tmp for ldapadd instead, copy the file into /var/lib/dirsrv/slapd-ldap1/ldif/ with install as the dirsrv user and run restorecon before ldif2db.

The .dsrc file stores default connection settings for dsconf, dsidm, and other 389 DS CLI tools so you type less on repeat logins.

dsctl ldap1 dsrc create --basedn dc=example,dc=com --binddn "cn=Directory Manager" --pwdfile /root/dm.pw --do-it

Sample output:

Updating "/root/.dsrc" with:

    [ldap1]
    basedn = dc=example,dc=com
    binddn = cn=Directory Manager
    pwdfile = /root/dm.pw
Successfully updated: /root/.dsrc

Display the result:

dsctl ldap1 dsrc display

Sample output:

[ldap1]
basedn = dc=example,dc=com
binddn = cn=Directory Manager
pwdfile = /root/dm.pw

Protect the password file (chmod 600) and remove it when the lab ends.

remove without --do-it only prints what would happen. This prevents accidental destruction of a production instance.

dsctl ldap1 remove

Sample output:

Not removing: if you are sure, add --do-it

Only add --do-it on lab systems you intend to delete completely. Recreate the instance afterward with dscreate from-file if you still need a directory on the host.