dsconf Commands and Examples for 389 Directory Server

Use dsconf to manage a running 389 Directory Server: backends, indexes, replication, plug-ins, logs, security, schema, monitoring, and online backups.

Published Jul 15, 2026

Updated Jul 15, 2026

Author Rohan Timalsina

Read time 13 min read

Reviewed Jul 15, 2026 byDeepak Prasad

About	Use dsconf to manage a running 389 Directory Server: backends, indexes, replication, plug-ins, logs, security, schema, monitoring, and online backups.
Tested on	Rocky Linux 10.2; 389 Directory Server 3.2.0; instance ldap1; suffix dc=example,dc=com
Package	389-ds-base (apt/deb) · 389-ds-base (dnf/rpm)
Man page	dsconf(8)
Privilege	root for local LDAPI autobind, or Directory Manager/equivalent configuration access
Distros	RHEL, Rocky Linux, AlmaLinux, Fedora: 389-ds-base. Debian and Ubuntu: 389-ds-base. The optional 389-ds metapackage also installs the Cockpit administration interface.
Related guide	Install 389 Directory Server 389 Directory Server tutorial dsctl local instance operations Replication overview

dsconf is the online configuration tool for 389 Directory Server. It connects to a running ns-slapd process and reads or writes cn=config, backend settings, replication agreements, plug-ins, logging, security policy, and schema. Local start/stop and offline exports belong to dsctl; users and groups belong to dsidm. This cheat sheet supports the 389 Directory Server tutorial.

Tested on: Rocky Linux 10.2; 389 Directory Server 3.2.0; instance ldap1; suffix dc=example,dc=com.

dsconf — quick reference

Commands containing <options> or other placeholder tokens are syntax reminders rather than complete copy-and-run examples. Use dsconf INSTANCE COMMAND --help before making changes.

Connection and global options

When you pass a local instance name, dsconf normally connects through that instance's LDAPI socket. If LDAPI autobind is enabled and you run the command as an authorized operating-system user, typically root, no bind password is required. Otherwise, provide credentials with -D and -W, a password file, SASL settings, or .dsrc. For remote administration, use an LDAP URL; credentials and TLS settings can also come from .dsrc or SASL configuration — the CLI loads .dsrc before applying command-line overrides.

When to use	Command
Target a local instance by short name	`dsconf ldap1 COMMAND`
Target a remote server by URL	`dsconf ldap://ldap1.example.com:389 COMMAND`
Bind as a specific identity	`dsconf -D "cn=Directory Manager" -W ldap1 COMMAND`
Read bind password from a file	`dsconf -y /root/dm.pw ldap1 COMMAND`
Set the base DN/root naming context for the connection	`dsconf -b dc=example,dc=com ldap1 COMMAND`
Require StartTLS on the connection	`dsconf -Z ldap://host:389 COMMAND`
JSON output for scripts	`dsconf -j ldap1 backend suffix list`
Verbose/debug output	`dsconf -v ldap1 config get`

An LDAP URL only identifies the connection target; it does not encrypt the session. Use ldaps://, StartTLS with -Z, or an appropriate SASL mechanism before transmitting administrative credentials over a network.

Backend and suffix (`backend`)

When to use	Command
List suffixes and backend names	`dsconf ldap1 backend suffix list`
Read backend entry for `userroot`	`dsconf ldap1 backend suffix get userroot`
Display the suffix tree	`dsconf ldap1 backend get-tree`
Monitor one suffix	`dsconf ldap1 backend monitor --suffix dc=example,dc=com`
List indexes on a backend	`dsconf ldap1 backend index list userroot`
Online LDIF import task	`dsconf ldap1 backend import userroot /path/to/file.ldif`
Online LDIF export task	`dsconf ldap1 backend export userroot -l /var/lib/dirsrv/slapd-ldap1/ldif/out.ldif`
Compact the database environment and replication changelog	`dsconf ldap1 backend compact-db`
Compact only the replication changelog	`dsconf ldap1 backend compact-db --only-changelog`

For online export, pass the output file with -l or --ldif. Without -l, Directory Server writes a timestamped LDIF under the instance ldif/ directory. The destination must be writable by dirsrv; systemd PrivateTmp can block paths such as /tmp, /var/tmp, and /root.

IMPORTANT

Backend import replaces the existing contents of the target backend. Take a tested backup first. Store the LDIF under /var/lib/dirsrv/slapd-INSTANCE/ldif/, ensure dirsrv can read it, and restore its SELinux context before starting the import. The import path is on the Directory Server host, not on the workstation where you typed the command.

Server configuration (`config`)

When to use	Command
Read all or selected `cn=config` attributes	`dsconf ldap1 config get`
Read specific attributes	`dsconf ldap1 config get nsslapd-port nsslapd-localhost`
Add a multi-valued attribute	`dsconf ldap1 config add attribute=value`
Replace an attribute value	`dsconf ldap1 config replace attribute=newvalue`
Delete one attribute value	`dsconf ldap1 config delete attribute=value`
Remove an entire attribute	`dsconf ldap1 config delete attribute`

Monitoring (`monitor`)

When to use	Command
Server connections and operation counters	`dsconf ldap1 monitor server`
All database statistics	`dsconf ldap1 monitor dbmon`
LMDB cache and page stats	`dsconf ldap1 monitor ldbm`
Per-backend monitor entry	`dsconf ldap1 monitor backend userroot`
Disk space for DB and logs	`dsconf ldap1 monitor disk`

Logging (`logging`)

When to use	Command
Read access log settings	`dsconf ldap1 logging access get`
Read error log settings	`dsconf ldap1 logging error get`
Read audit log settings	`dsconf ldap1 logging audit get`
Read security log settings	`dsconf ldap1 logging security get`

Plug-ins (`plugin`)

When to use	Command
List installed plug-ins	`dsconf ldap1 plugin list`
Show one plug-in by display name	`dsconf ldap1 plugin show "MemberOf Plugin"`
Enable or tune a plug-in	`dsconf ldap1 plugin memberof <options>` (see plug-in subcommand)

Password policy (`pwpolicy`, `localpwp`)

When to use	Command
Read global password policy	`dsconf ldap1 pwpolicy get`
List password storage schemes	`dsconf ldap1 pwpolicy list-schemes`
List subtree or user policies	`dsconf ldap1 localpwp list`
Attach policy to a subtree	`dsconf ldap1 localpwp addsubtree <options>`

Replication (`replication`, `repl-agmt`, `repl-tasks`, `repl-conflict`)

When to use	Command
List replicated suffixes	`dsconf ldap1 replication list`
Enable replication on a suffix	`dsconf ldap1 replication enable --suffix <SUFFIX_DN> --role <supplier/hub/consumer> <additional-options>`
Agreement status for a suffix	`dsconf ldap1 replication status --suffix dc=example,dc=com`
List replication agreements	`dsconf ldap1 repl-agmt list --suffix dc=example,dc=com`
Initialize a consumer	`dsconf ldap1 repl-agmt init <options>`
List replication conflict entries	`dsconf ldap1 repl-conflict list --suffix dc=example,dc=com`
CleanAllRUV task	`dsconf ldap1 repl-tasks cleanallruv <options>`

Security, SASL, and schema

When to use	Command
Read TLS and security settings	`dsconf ldap1 security get`
Disable plain LDAP port	`dsconf ldap1 security disable_plain_port`
List accepted SASL mechanisms	`dsconf ldap1 sasl get-mechs`
List SASL mappings	`dsconf ldap1 sasl list`
List schema elements	`dsconf ldap1 schema list`
Reload schema from disk	`dsconf ldap1 schema reload`
Import OpenLDAP schema LDIF	`dsconf ldap1 schema import-openldap-file /path/to/schema.ldif --confirm`
Preview OpenLDAP schema migration (no changes)	`dsconf ldap1 schema import-openldap-file /path/to/schema.ldif`

Online backup and chaining

When to use	Command
Online backup to a directory	`dsconf ldap1 backup create /var/lib/dirsrv/slapd-ldap1/bak/my-backup`
Restore from online backup	`dsconf ldap1 backup restore /path/to/backup`
List database chaining links	`dsconf ldap1 chaining link-list`

IMPORTANT

Restoring an online backup clears the replication changelog. In a replicated topology, plan to reinitialize the affected replica after restore. Follow the dedicated backup and recovery chapter rather than running this command directly on a production supplier. The backup path is on the Directory Server host and must be accessible to the dirsrv service account.

Directory Manager

When to use	Command
Change Directory Manager password	`dsconf ldap1 directory_manager password_change`

dsconf — command syntax

Synopsis from dsconf -h on the tested host:

text


usage: dsconf [-h] [-v] [-j] [-D BINDDN] [-w BINDPW] [-W] [-y PWDFILE]
              [-b BASEDN] [-Z]
              instance
              {backend,backup,chaining,config,directory_manager,logging,monitor,plugin,pwpolicy,localpwp,replication,repl,repl-agmt,repl-winsync-agmt,repl-tasks,repl-conflict,sasl,security,schema}
              ...

The instance argument is either a local short name (ldap1) or an LDAP URL (ldap://host:389). Subcommands map to major configuration areas in cn=config and the replicated suffix entries.

dsconf updates live server configuration. For process control or offline file operations, use dsctl.

dsconf — command examples

Essential List suffixes and read backend settings

After dscreate, confirm which suffix the userroot backend serves before you add indexes or replication.

bash

dsconf ldap1 backend suffix list

Sample output:

output

dc=example,dc=com (userroot)

The parenthesized name is the backend identifier for further backend subcommands. Read cache and read-only flags:

bash

dsconf ldap1 backend suffix get userroot

Sample output (trimmed):

output

dn: cn=userroot,cn=ldbm database,cn=plugins,cn=config
nsslapd-cachememsize: 939524096
nsslapd-readonly: off
nsslapd-suffix: dc=example,dc=com

nsslapd-suffix must match the naming context clients search.

Essential Read server configuration attributes

config get without arguments dumps the main cn=config entry. Filter to the listeners you care about when hardening the server.

bash

dsconf ldap1 config get nsslapd-port nsslapd-localhost

Sample output:

output

nsslapd-port: 389
nsslapd-localhost: ldap1.example.com

Cross-check with ss -lntp on the host. Changing ports requires matching firewall and client URI updates.

Common Inspect live server statistics

The monitor backend exposes connection counts, operation rates, and build version without parsing log files.

bash

dsconf ldap1 monitor server

Sample output (trimmed):

output

dn: cn=monitor
version: 389-Directory/3.2.0 B2026.177.0000
threads: 18
currentconnections: 2
totalconnections: 27
opsinitiated: 155
opscompleted: 154

Rising currentconnectionsatmaxthreads on a busy server may mean you need tuning — see the monitoring chapter.

Common Inspect a plug-in by its config name

plugin list prints display names. plugin show expects the complete plug-in cn. Copy the full name from plugin list, for example MemberOf Plugin; the abbreviated selector memberof does not identify that entry.

bash

dsconf ldap1 plugin list | grep -i member

Sample output:

output

MemberOf Plugin

Show the plug-in entry:

bash

dsconf ldap1 plugin show "MemberOf Plugin"

Sample output (trimmed):

output

dn: cn=MemberOf Plugin,cn=plugins,cn=config
cn: MemberOf Plugin
memberofattr: memberOf
nsslapd-pluginEnabled: off
nsslapd-pluginPath: libmemberof-plugin

On this lab instance MemberOf is disabled. Enable and tune it in the dedicated MemberOf plug-in chapter — not with raw ldapmodify unless you know the exact attribute set.

Common Review access log settings

Before chasing a missing log line, confirm logging is enabled and know the file path.

bash

dsconf ldap1 logging access get

Sample output (trimmed):

output

Access Log Configuration
--------------------------------------------------------------------------------
Buffering enabled = on
Log level = default
Log name and location = /var/log/dirsrv/slapd-ldap1/access

Error, audit, audit-failure, and security logs use the same logging SUBSYSTEM get|set pattern.

Common Read the global password policy

Password rules live in cn=config and optional localpwp entries. Start with the global policy before creating subtree overrides.

bash

dsconf ldap1 pwpolicy get

Sample output (trimmed):

output

Global Password Policy: cn=config
------------------------------------
passwordstoragescheme: PBKDF2-SHA512
passwordchange: on
passwordmustchange: off
passwordhistory: off

List available storage schemes when migrating from legacy hashes:

bash

dsconf ldap1 pwpolicy list-schemes

Sample output (trimmed):

output

AES
CLEAR
CRYPT
PBKDF2-SHA512

Advanced Check replication when no agreements exist yet

On a fresh instance, replication list reports no suffixes. replication status still requires --suffix even when replication is disabled.

bash

dsconf ldap1 replication list

Sample output:

output

There are no replicated suffixes

Query status for the suffix you plan to replicate:

bash

dsconf ldap1 replication status --suffix dc=example,dc=com

Sample output on an unreplicated suffix:

output

Error: No object exists given the filter criteria: dc=example,dc=com (...)

That error is expected until you run replication enable and create agreements — see supplier and consumer replication.

Advanced List SASL mechanisms the server accepts

SASL configuration matters for Kerberos and GSSAPI binds. get-mechs shows what the server advertises to clients.

bash

dsconf ldap1 sasl get-mechs

Sample output:

output

EXTERNAL
GSS-SPNEGO
GSSAPI
DIGEST-MD5
CRAM-MD5
PLAIN
LOGIN
ANONYMOUS

This list shows mechanisms advertised by the server, not a recommendation to use every mechanism. Choose mechanisms according to your security policy and protect password-based mechanisms with TLS.

Map mechanisms to directory identities with dsconf ldap1 sasl list and sasl create when you deploy SASL GSSAPI and Kerberos authentication.

Advanced Create an online backup

Online backup runs as a task while ns-slapd stays up — unlike dsctl db2ldif, which needs a stopped server.

bash

dsconf ldap1 backup create /var/lib/dirsrv/slapd-ldap1/bak/cs-online-test

Sample output:

output

The backup create task has finished successfully

Confirm the directory with dsctl backups or ls under the instance bak/ folder. Delete lab backups with dsctl ldap1 backups --delete cs-online-test.

Common Machine-readable suffix list

Scripts can consume -j output instead of parsing column text.

bash

dsconf -j ldap1 backend suffix list

Sample output:

output

{
    "type": "list",
    "items": [
        "dc=example,dc=com (userroot)"
    ]
}

dsconf — when to use / when not

Use dsconf when	Use something else when
The `ns-slapd` process is running and you need to change configuration You are managing backends, indexes, replication, plug-ins, logging, or security policy You want online backup or import/export tasks without stopping the server You are administering a remote Directory Server by LDAP URL You need monitor counters or password policy inspection	Start, stop, or remove the local instance → dsctl Create users, groups, or OUs in the DIT → dsidm Offline LDIF export or reindex with the server stopped → `dsctl db2ldif` / `db2index` Low-level LDIF edits to arbitrary entries → ldapmodify when dsidm has no helper Instance does not exist yet → `dscreate`

dsconf vs dsctl

	dsconf	dsctl
Requires running LDAP	Yes	No — many subcommands need the server stopped
Configuration scope	`cn=config`, backends, repl, plugins	Process, files on disk, NSS TLS DB
Remote administration	Yes (`ldap://` URL)	No — local host only
Typical first check	`backend suffix list`, `monitor server`	`status`, `healthcheck`

Command	One line
dsctl	Start/stop instance and offline database work
dsconf	Online configuration (this page)
dsidm	Directory data — users and groups
ldapsearch	Verify configuration and entries
ldapmodify	Raw LDIF changes when no dsconf helper exists

See the 389 Directory Server tutorial for the full learning path.

dsconf — interview corner

What does dsconf configure?

dsconf is the high-level CLI for online 389 Directory Server administration. It groups LDAP operations into subcommands: backend, config, replication, plugin, logging, security, schema, and others.

It translates your intent into changes under cn=config and related backend entries while ns-slapd is running.

A strong answer is:

"dsconf is the online config tool — backends, replication, plugins, logs, security, schema — over LDAP while the server runs."

What does userroot mean in backend suffix list?

userroot is the default backend identifier for the first user database created by dscreate. The suffix list prints dc=example,dc=com (userroot) — the DN clients search and the backend name for backend suffix get, index list, and import/export tasks.

Additional backends get their own identifiers when you backend create another suffix.

A strong answer is:

"userroot is the backend name for the primary user database; the suffix list pairs the naming context DN with that backend id."

Why does plugin show memberof fail?

plugin show expects the complete plug-in cn. Copy the full name from plugin list, for example MemberOf Plugin; the abbreviated selector memberof does not identify that entry.

A strong answer is:

"Use the exact cn from plugin list, like MemberOf Plugin — the short name memberof is not a valid selector."

Why does replication status require --suffix?

A Directory Server instance can host multiple backends and replicated suffixes. replication status scopes agreement state to one nsDS5ReplicaRoot at a time, so --suffix is mandatory.

On an unreplicated lab server the command errors until replication is enabled — that is normal.

A strong answer is:

"status is per suffix; you must pass --suffix because an instance can replicate multiple naming contexts."

How does dsconf authenticate locally?

A local instance name normally uses LDAPI autobind. Root can usually administer the instance without entering the Directory Manager password; otherwise, supply an authorized LDAP identity with -D and -W, a password file, SASL settings, or .dsrc.

For remote URLs, credentials and TLS settings can also come from .dsrc or SASL configuration — not only from command-line flags.

A strong answer is:

"A local instance name normally uses LDAPI autobind. Root can usually administer the instance without entering the Directory Manager password; otherwise, supply an authorized LDAP identity."

Should you use dsconf to create users?

No. dsconf changes server configuration. Directory entries (users, groups, OUs) belong to dsidm or standard LDAP tools.

Mixing the two leads to confusion — plug-in tuning is dsconf; adding uid=alice is dsidm user create.

A strong answer is:

"dsconf is for server config; dsidm is for directory data. Users and groups are not dsconf tasks."

Troubleshooting

Symptom	Likely cause	Fix
`Can't contact LDAP server`	Instance stopped or wrong URL	`dsctl INSTANCE status`; start with `dsctl INSTANCE start`
`unrecognized arguments: userroot` after `backend monitor`	`backend monitor` expects `--suffix`, not a positional backend	Use `backend monitor --suffix dc=example,dc=com`; alternatively use `monitor backend userroot` for the backend monitor entry
`No object exists` for `plugin show`	Wrong plug-in name	Copy exact name from `plugin list`
`replication status: required: --suffix`	Missing suffix flag	Add `--suffix dc=example,dc=com`
`No object exists` for replication on fresh server	Replication not enabled yet	Run `replication enable` first — replication guide
`Insufficient access`	Bind DN lacks config write access	Bind as Directory Manager or an account with config ACIs
Connection reset during heavy tests	Server restarted by parallel maintenance	Wait for `dirsrv@INSTANCE` to return to active
Changes not visible to clients	Config cached or wrong instance	Confirm instance name; some plugin changes need restart — check plug-in docs

References

dsctl, dsconf and dsidm (Port389) — purpose and scope of each administration tool
Red Hat Directory Server 13 management guide — backends, monitoring, imports, exports, schema, and configuration
Exporting and importing data — online dsconf backend import and export
dsconf(8) man page — command synopsis and options

Rohan Timalsina

is a technical writer and Linux enthusiast who writes practical guides on Linux commands and system administration. He focuses on simplifying complex topics through clear explanations.

dsconf — quick reference

Connection and global options

Backend and suffix (backend)

Server configuration (config)

Monitoring (monitor)

Logging (logging)

Plug-ins (plugin)

Password policy (pwpolicy, localpwp)

Replication (replication, repl-agmt, repl-tasks, repl-conflict)

Security, SASL, and schema

Online backup and chaining

Directory Manager

dsconf — command syntax

dsconf — command examples

dsconf — when to use / when not

dsconf vs dsctl

Related commands

dsconf — interview corner

Troubleshooting

References

Related Articles

Manage 389 Directory Server Data with dsidm

dsctl Commands for Managing 389 Directory Server Instances

Disable, Reactivate, and Automatically Inactivate User Accounts in 389 Directory Server

Search GoLinuxCloud

Backend and suffix (`backend`)

Server configuration (`config`)

Monitoring (`monitor`)

Logging (`logging`)

Plug-ins (`plugin`)

Password policy (`pwpolicy`, `localpwp`)

Replication (`replication`, `repl-agmt`, `repl-tasks`, `repl-conflict`)