Free Online Course · Self-paced · Hands-on

389 Directory Server Tutorial: Complete Administration Guide

Free 389 Directory Server course: dscreate, dsconf and dsidm, TLS, ACIs, password policy, replication, and LMDB tuning, tested on 389-ds-base 3.2.

  • 11 chapters
  • 84 lessons
  • ~40h
  • Intermediate
  • Tested with 389 Directory Server 3.2.x
  • Updated Sep 2026
Start the course View syllabus
389 Directory Server Tutorial: Complete Administration Guide
By Last updated

About this course

This is a free, product-focused course on administering 389 Directory Server, the upstream LDAP server behind Red Hat Directory Server and the directory inside FreeIPA. It follows the upstream 3.x release line and the tools that ship with it: dscreate to create instances, dsctl for local and offline work, dsconf to change a running server, and dsidm for users, groups, and organizational units.

The course was tested on selected Linux distributions. Core administration procedures apply to equivalent 389 Directory Server versions, while installation, service management, firewall, and SELinux or AppArmor commands may differ by distribution. Every lesson uses LMDB, the default backend for new instances since 3.0, so if you still run Berkeley DB, read the LMDB migration lesson before any of the tuning chapters.

If LDAP is new to you, read LDAP and OpenLDAP basics first, then install the server and follow the chapters in order. If you already run 389 Directory Server, each lesson lists its own prerequisites, so you can go straight to replication, ACIs, or the troubleshooting library.

What you'll learn

  • Explain how instances, backends, suffixes, and plug-ins fit together, then install 389 Directory Server and create an instance with dscreate
  • Administer running servers with dsctl, dsconf, and dsidm instead of hand-editing configuration
  • Back up, restore, and upgrade instances, and migrate Berkeley DB backends to LMDB
  • Build single-supplier, cascading, and multi-supplier replication, then monitor and repair it
  • Manage users, groups, schema, and membership plug-ins such as memberOf, Auto Membership, and DNA
  • Secure the directory with TLS, client certificates, SASL GSSAPI, password policies, and ACIs
  • Connect Linux clients through SSSD and protect Apache with LDAP authentication
  • Diagnose common LDAP errors, and tune indexes, caches, threads, and search limits for production load

Who this course is for

  • Linux administrators who run, or are about to inherit, a 389 Directory Server or Red Hat Directory Server deployment
  • Identity engineers moving users off OpenLDAP or local /etc/passwd files into a replicated directory
  • Directory operators responsible for TLS, access control, password policy, and replication health
  • FreeIPA administrators who want to understand the LDAP server underneath it

Prerequisites

  • Comfortable Linux command line: systemctl, firewall tools, editing files, and root or sudo access
  • One Linux VM for the core chapters, plus two or three more for the replication and client labs. Any distribution with a 3.x 389-ds-base package works
  • LDAP basics such as DNs, suffixes, and object classes. The LDAP and OpenLDAP basics lesson covers them if they are new
  • No subscription needed, because the upstream 389-ds-base package from your distribution covers every lab

Versions and testing environment

Every command in this course was run on this stack

ComponentVersionNotes
389 Directory Server 3.2.x 389-ds-base 3.2.0 from the distribution repositories, with new instances on the LMDB backend
Rocky Linux 10.2 Lab host OS. The same 3.2.0 release ships as Red Hat Directory Server 13.2 on RHEL 10.2
Fedora, Debian, Ubuntu, SUSE, Arch Varies Install with dnf, apt, zypper, or pacman. Package versions differ, and 2.x packages still create Berkeley DB instances
OpenLDAP 2.6.x Source server in the OpenLDAP migration lesson
Apache HTTP Server 2.4.x Used in the Apache LDAP authentication lesson

Syllabus

11 chapters · 84 lessons · ~40h of reading

  1. 1 Installation & instance basics 5 lessons · ~1h 15m
    1. Part 1 Architecture — instances, backends, plug-ins 14 min read
    2. Part 2 Install 389 Directory Server 21 min read
    3. Part 3 dscreate inf file reference 12 min read
    4. Part 4 Run multiple instances on one host 16 min read
    5. Part 5 Non-root instance (development) 12 min read
  2. 2 Administration CLI 3 lessons · ~39 min
    1. Part 6 dsctl — local and offline operations 14 min read
    2. Part 7 dsconf — online configuration 13 min read
    3. Part 8 dsidm — users, groups, directory data 12 min read
  3. 3 Backup, upgrade & maintenance 3 lessons · ~1h 3m
    1. Part 9 Back up and restore 16 min read
    2. Part 10 Update and upgrade safely 25 min read
    3. Part 11 Migrate Berkeley DB to LMDB 22 min read
  4. 4 Migration & replication 17 lessons · ~5h 39m
    1. Part 12 Replication architecture and topology 15 min read
    2. Part 13 Single-supplier replication setup 15 min read
    3. Part 14 Cascading replication setup 20 min read
    4. Part 15 Multi-supplier replication setup 19 min read
    5. Part 16 Manage replication agreements 21 min read
    6. Part 17 Configure fractional replication 15 min read
    7. Part 18 Manage replication changelog 15 min read
    8. Part 19 Monitor replication and lag 20 min read
    9. Part 20 Troubleshoot replication failures 17 min read
    10. Part 21 Initialize and reinitialize replicas 14 min read
    11. Part 22 Promote or demote a replica 19 min read
    12. Part 23 Remove a replica from the topology 17 min read
    13. Part 24 CleanAllRUV stale replica IDs 12 min read
    14. Part 25 Certificate-based replication authentication 29 min read
    15. Part 26 Migrate to a new server 37 min read
    16. Part 27 Migrate from OpenLDAP 32 min read
    17. Part 28 Restore a replicated server 22 min read
  5. 5 Directory data & schema 15 lessons · ~4h 7m
    1. Part 29 Suffixes and backends 19 min read
    2. Part 30 Export and import LDIF 18 min read
    3. Part 31 Manage users and groups 14 min read
    4. Part 32 Configure the memberOf plug-in 19 min read
    5. Part 33 Configure Referential Integrity 19 min read
    6. Part 34 Configure Auto Membership 16 min read
    7. Part 35 Configure Managed Entries and Linked Attributes 20 min read
    8. Part 36 Enforce unique LDAP attributes 16 min read
    9. Part 37 Assign UID and GID with DNA 20 min read
    10. Part 38 Roles vs groups 14 min read
    11. Part 39 Class of Service (CoS) 17 min read
    12. Part 40 Rename and move LDAP entries 16 min read
    13. Part 41 Generate test data with ldifgen 16 min read
    14. Part 42 Create custom schema 15 min read
    15. Part 43 Read-only databases and instances 8 min read
  6. 6 Advanced directory features 3 lessons · ~42 min
    1. Part 44 LDAP referrals 15 min read
    2. Part 45 Database chaining 15 min read
    3. Part 46 Directory views 12 min read
  7. 7 TLS, certificates & authentication 9 lessons · ~2h 43m
    1. Part 47 TLS, STARTTLS, and LDAPS 17 min read
    2. Part 48 TLS versions and cipher suites 18 min read
    3. Part 49 Require secure LDAP connections 17 min read
    4. Part 50 Client certificate authentication 17 min read
    5. Part 51 SASL GSSAPI and Kerberos 19 min read
    6. Part 52 Certificate management 27 min read
    7. Part 53 FIPS mode 21 min read
    8. Part 54 Attribute encryption 12 min read
    9. Part 55 Restrict anonymous access 15 min read
  8. 8 Password policy & access control 10 lessons · ~3h 3m
    1. Part 56 Password storage schemes 17 min read
    2. Part 57 Global, subtree, and user password policy 22 min read
    3. Part 58 Account lockout 16 min read
    4. Part 59 Disable and inactivate user accounts 18 min read
    5. Part 60 ACI examples 19 min read
    6. Part 61 Advanced ACI targets and bind rules 15 min read
    7. Part 62 Self-service password and profile ACIs 13 min read
    8. Part 63 Delegated administration 25 min read
    9. Part 64 Macro ACIs 18 min read
    10. Part 65 Get Effective Rights — test ACI permissions 20 min read
  9. 9 Client and application integrations 3 lessons · ~45 min
    1. Part 66 SSSD LDAP authentication 15 min read
    2. Part 67 SSH public keys with SSSD 13 min read
    3. Part 68 Apache LDAP authentication 17 min read
  10. 10 Troubleshooting library 8 lessons · ~1h 44m
    1. Part 69 Fix LDAP error 49 — invalid credentials 12 min read
    2. Part 70 Fix LDAP error 50 — insufficient access 12 min read
    3. Part 71 Fix LDAP error 53 — unwilling to perform 15 min read
    4. Part 72 Fix LDAP error 65 — object class violation 13 min read
    5. Part 73 Fix LDAP works but LDAPS fails 15 min read
    6. Part 74 Fix missing or stale memberOf 14 min read
    7. Part 75 Fix slow LDAP searches 14 min read
    8. Part 76 Reset Directory Manager password 9 min read
  11. 11 Performance and production operations 8 lessons · ~2h 19m
    1. Part 77 Configure LDAP indexes 14 min read
    2. Part 78 Configure LDAP search limits 13 min read
    3. Part 79 Configure threads and connections 10 min read
    4. Part 80 Virtual List View indexes 16 min read
    5. Part 81 Tune LMDB and caches 17 min read
    6. Part 82 Configure low disk space protection 20 min read
    7. Part 83 Benchmark performance with ldclt 30 min read
    8. Part 84 Tune large groups and memberOf 19 min read

Hands-on labs

6 guided builds you run yourself

  1. Install the server and create your first instance

    Install the packages, create an instance with dscreate, add a suffix, and confirm the server answers ldapsearch.

  2. Enable LDAPS and STARTTLS

    Import a server certificate and CA, turn on encrypted LDAP, and verify the handshake from a client with ldapsearch and openssl.

  3. Build two-way multi-supplier replication

    Join two writable suppliers with agreements in both directions, initialize the second one, and test writes and failover.

  4. Back up an instance and prove the restore

    Take online and offline backups, check them with checksums, copy them off the host, and restore onto an isolated instance.

  5. Migrate a directory from OpenLDAP

    Convert OpenLDAP schema, data, and access rules with openldap_to_ds, validate the result, and plan the cutover.

  6. Log in to Linux with directory accounts

    Point SSSD at the directory over TLS, look up POSIX users, log in, and check that cached credentials work offline.

Where to go after this course

  • 389 Directory Server documentationUpstream release notes and design pages. Read the notes for your target release before you upgrade.
  • Keycloak coursePut single sign-on in front of the directory. The LDAP federation chapters connect Keycloak to 389 Directory Server.
  • OpenLDAP courseThe other widely used open-source LDAP server, useful if you support both or are planning a migration.

Frequently Asked Questions

What is the difference between 389 Directory Server and Red Hat Directory Server?

Red Hat Directory Server is Red Hat's supported build of the same code. Red Hat Directory Server 13.2 runs on RHEL 10.2 and is rebased to 389-ds-base 3.2.0, the release this course was tested on. You need a subscription and the Directory Server repository to install it, and in return you get vendor support and Red Hat's product documentation. The commands, configuration, and file layout match what you learn here.

Should I choose 389 Directory Server or OpenLDAP?

Both are solid LDAP servers. 389 Directory Server gives you multi-supplier replication, a plug-in model, and the dsconf and dsidm tools out of the box, and it has a supported commercial build. OpenLDAP is smaller and built around overlays and cn=config. On RHEL-family systems, Red Hat stopped shipping the OpenLDAP server in its supported repositories after RHEL 7, which pushes many teams toward 389 Directory Server. OpenLDAP vs 389 Directory Server compares them in detail.

Does it matter if my distribution ships 389 Directory Server 2.x?

Yes. Version 3.0 changed the default backend for new instances from Berkeley DB to LMDB, and from 3.1.3 onward Berkeley DB is no longer supported at all. An instance still on Berkeley DB will refuse to start after an upgrade to 3.1.3 or later until you convert it with dsctl INSTANCE dblib bdb2mdb. Check the backend of any existing instance before you upgrade the package.

Is there a web console, or is everything done on the command line?

The cockpit-389-ds package adds a 389 Directory Server plug-in to the Cockpit web console, where you can browse entries and change common settings. This course sticks to the command line because dsconf and dsidm commands can be scripted, reviewed, and repeated on the next server, and the console runs the same operations underneath.

Can I run 389 Directory Server in a container?

Yes. The project publishes an official image at quay.io/389ds/dirsrv. The lessons here install packages on a VM because replication, TLS, and SSSD labs are easier to follow when the server, its certificates, and its logs sit on a normal host. Treat the container as a separate deployment choice and plan persistent storage for the database and configuration before you use it.

Which replication terms does the course use?

Current 389 Directory Server terms: supplier, consumer, hub, and multi-supplier. The older master and slave names appear once where people still search for them, but every configuration example uses the current terms, matching the dsconf commands.

Deepak Prasad

R&D Engineer

Founder of GoLinuxCloud with 15+ years of expertise in Linux, Python, Go, Laravel, DevOps, Kubernetes, Git, Shell scripting, OpenShift, AWS, Networking, and Security. With extensive experience, he excels across development, DevOps, networking, and security, delivering robust and efficient solutions for diverse projects.

Expertise
  • Go (programming language)
  • Python (programming language)
  • DevOps
  • Computer Security
  • Cloud Computing
  • Kubernetes
  • Linux
  • Ansible (software)