Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
ContentsContents
Security and Hardening Guide
Navigation
Applies to SUSE Linux Enterprise Desktop 15 SP3

6 LDAP with 389 Directory Server Edit source

The Lightweight Directory Access Protocol (LDAP) is a protocol designed to access and maintain information directories. LDAP can be used for tasks such as user and group management, system configuration management, and address management. In SUSE Linux Enterprise Desktop 15.3 the LDAP service is provided by the 389 Directory Server, replacing OpenLDAP.

Ideally, a central server stores the data in a directory and distributes it to all clients using a well-defined protocol. The structured data allow a wide range of applications to access them. A central repository reduces the necessary administrative effort. The use of an open and standardized protocol such as LDAP ensures that as many client applications as possible can access such information.

A directory in this context is a type of database optimized for quick and effective reading and searching. The type of data stored in a directory tends to be long lived and changes infrequently. This allows the LDAP service to be optimized for high performance concurrent reads, whereas conventional databases are optimized for accepting many writes to data in a short time.

6.1 Structure of an LDAP directory tree Edit source

This section introduces the layout of an LDAP directory tree, and provides the basic terminology used with regard to LDAP.

An LDAP directory has a tree structure. All entries (called objects) of the directory have a defined position within this hierarchy. This hierarchy is called the directory information tree (DIT). The complete path to the desired entry, which unambiguously identifies it, is called the distinguished name or DN. An object in the tree is identified by its relative distinguished name (RDN). The distinguished name is built from the RDNs of all entries on the path to the entry.

The relations within an LDAP directory tree become more evident in the following example, shown in Figure 6.1, “Structure of an LDAP directory”.

Structure of an LDAP directory
Figure 6.1: Structure of an LDAP directory

The complete diagram is a fictional directory information tree. The entries on three levels are depicted. Each entry corresponds to one box in the image. The complete, valid distinguished name for the fictional employee Geeko Linux, in this case, is cn=Geeko Linux,ou=doc,dc=example,dc=com. It is composed by adding the RDN cn=Geeko Linux to the DN of the preceding entry ou=doc,dc=example,dc=com.

The types of objects that can be stored in the DIT are globally determined following a Schema. The type of an object is determined by the object class. The object class determines what attributes the relevant object must or may be assigned. The Schema contains all object classes and attributes which can be used by the LDAP server. Attributes are a structured data type. Their syntax, ordering and other behavior is defined by the Schema. LDAP servers supply a core set of Schemas which can work in a broad variety of environments. If a custom Schema is required, you can upload it to an LDAP server.

Table 6.1, “Commonly used object classes and attributes” offers a small overview of the object classes from 00core.ldif and 06inetorgperson.ldif used in the example, including required attributes (Req. Attr.) and valid attribute values. After installing 389 Directory Server, these can be found in usr/share/dirsrv/schema.

Table 6.1: Commonly used object classes and attributes

Object Class

Meaning

Example Entry

Req. Attr.

domain

name components of the domain

example

displayName

organizationalUnit

organizational unit

documentationdept

ou

nsPerson

person-related data for the intranet or Internet

Tux Linux

cn

Example 6.1, “Excerpt from CN=schema” shows an excerpt from a Schema directive with explanations.

Example 6.1: Excerpt from CN=schema
attributetype (1.2.840.113556.1.2.102 NAME 'memberOf' 1
       DESC 'Group that the entry belongs to' 2
       SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 3
       X-ORIGIN 'Netscape Delegated Administrator') 4

objectclass (2.16.840.1.113730.3.2.333 NAME 'nsPerson' 5
       DESC 'A representation of a person in a directory server' 6
       SUP top STRUCTURAL 7
       MUST ( displayName $ cn ) 8
       MAY ( userPassword $ seeAlso $ description $ legalName $ mail \
             $ preferredLanguage ) 9
       X-ORIGIN '389 Directory Server Project'
  ...

1

The name of the attribute, its unique object identifier (OID, numerical), and the abbreviation of the attribute.

2

A brief description of the attribute with DESC. The corresponding RFC, on which the definition is based, may also mentioned here.

3

The type of data that can be held in the attribute. In this case, it is a case-insensitive directory string.

4

The source of the schema element (for example, the name of the project).

5

The definition of the object class nsPerson begins with an OID and the name of the object class (like the definition of the attribute).

6

A brief description of the object class.

7

The SUP top entry indicates that this object class is not subordinate to another object class.

8

With MUST, list all attribute types that must be used with an object of the type nsPerson.

9

With MAY, list all attribute types that are optionally permitted with this object class.

6.2 Installing 389 Directory Server Edit source

Install 389 Directory Server with the following command:

tux > sudo zypper install 389-ds

This installs the 389-ds and lib389 packages. After installation, set up the server

6.2.1 Setting up a new 389 Directory Server instance Edit source

You will use the dscreate command to create new 389 Directory Server instances, and the dsctl command to cleanly remove them.

There are two ways to configure and create a new instance: from a custom configuration file, and from an auto-generated template file. You can use the auto-generated template without changes for a test instance, though for a production system you must carefully review it and make any necessary changes.

Then you will set up administration credentials, manage users and groups, and configure identity services.

Follow these steps to set up a simple instance for testing and development, populated with a small set of sample entries.

The 389 Directory Server is controlled by three primary commands:

dsctl

Manages a local instance and requires root permissions. Requires you to be connected to a terminal which is running the directory server instance. Used for starting, stopping, backing up the database, and more.

dsconf

The primary tool used for administration and configuration of the server. Manages an instance's configuration via its external interfaces. This allows you to make configuration changes remotely on the instance.

dsidm

Used for identity management (managing users, groups, passwords, etc.). The permissions are granted by access controls, so, for example, users can reset their own password or change details of their own account.

6.2.2 Creating a 389 Directory Server instance with a custom configuration file Edit source

You can create a new 389 Directory Server instance from a simple custom configuration file. This file must be in the INF format, and you can name it anything you like.

The default instance name is localhost. The instance name cannot be changed after it has been created. It is better to create your own instance name, rather than using the default, to avoid confusion and to enable a better understanding of how it all works.

Example 6.2 shows an example configuration file that you can use to create a new 389 Directory Server instance. You can copy and use this file, though be sure to create your own password.

  1. Copy the following example file, ldap1.inf, to your home directory:

    Example 6.2: Minimal 389 Directory Server instance configuration file
    # ldap1.inf
    
    [general]
    config_version = 2 1
    
    [slapd]
    root_password = password2
    self_sign_cert = True 3
    instance_name = ldap1
    
    [backend-userroot]
    sample_entries = yes 4
    suffix = dc=ldap1,dc=com

    1

    This line is required, indicating that this is a version 2 setup INF file.

    2

    Create a root_password for the ldap user cn=Directory Manager. This user is for connecting (binding) to the directory.

    3

    Create self-signed server certificates in /etc/dirsrv/slapd-INSTANCE-NAME.

    4

    Populate the new instance with sample user and group entries.

  2. To create the 389 Directory Server instance from Example 6.2, run the following command:

    tux > sudo dscreate -v from-file ldap1.inf | tee ldap1-output.txt

    This shows all activity during the instance creation, stores all the messages in ldap1-output.txt, and creates a working LDAP server in about a minute. The verbose output contains a lot of useful information. If you do not want to save it, then delete the | tee ldap1-output.txt portion of the command.

  3. If the dscreate command should fail, the messages will tell you why. After correcting any issues, remove the instance (see Step 5) and create a new instance.

  4. A successful installation reports "Completed installation for INSTANCE-NAME". Check the status of your new server:

    tux > sudo dsctl ldap1 status
    Instance "ldap1" is running
  5. The following commands are for cleanly removing the instance. The first command performs a dry run and does not remove the instance. When you are sure you want to remove it, use the second command with the --do-it option:

    tux > sudo dsctl ldap1 remove
    Not removing: if you are sure, add --do-it
    
    tux > sudo dsctl ldap1 remove --do-it

    This command also removes partially installed or corrupted instances. You can reliably create and remove instances as often as you want.

If you forget the name of your instance, use dsctl to list all instances:

tux > /usr/sbin/dsctl -l
slapd-ldap1

6.2.3 Creating a 389 Directory Server instance from a template Edit source

You can auto-create a template for a new 389 Directory Server instance with the dscreate command. This creates a template that you can use without making any changes, and you can change it to suit your own requirements. All of the defaults are documented in the template file, and commented out. To make changes, uncomment the default and enter your own value. All options are well documented.

The following example prints the template to stdout:

tux > dscreate create-template

This is good for a quick review of the template, but you must create a file to use in creating your new 389 Directory Server instance. You can name this file anything you want:

tux > dscreate create-template ldap1-template.txt

This is a snippet from the new file:

# full_machine_name (str)
# Description: Sets the fully qualified hostname (FQDN) of this system. When
# installing this instance with GSSAPI authentication behind a load balancer, set
# this parameter to the FQDN of the load balancer and, additionally, set
# "strict_host_checking" to "false".
# Default value: ldapserver1.test.net
;full_machine_name = ldapserver1.test.net

# selinux (bool)
# Description: Enables SELinux detection and integration during the installation
# of this instance. If set to "True", dscreate auto-detects whether SELinux is
# enabled. Set this parameter only to "False" in a development environment.
# Default value: True
;selinux = True

You see how it automatically configures the defaults from your existing environment. Use this file with no changes to create a new instance:

tux > sudo dscreate from-file ldap1-template.txt

This creates a new instance named localhost, and automatically starts it after creation:

tux > sudo dsctl localhost status
Instance "localhost" is running

The default values create a fully operational instance, but there are some values you might want to change.

The instance name cannot be changed after it has been created. It is better to create your own instance name, rather than using the default, to avoid confusion and to enable a better understanding of how it all works. To do this, uncomment the ;instance_name = localhost line and change localhost to your chosen name. In the following examples, the instance name is ldap1.

Another useful change is to populate your new instance with sample users and groups. Uncomment ;sample_entries = no and change no to yes.

Set your own password by uncommenting ;root_password, and replacing the default password with your own.

The template does not create a default suffix, so you should configure your own on the suffix line, like the following example:

suffix = dc=ldap1,dc=com

You can cleanly remove any instance and start over with dsctl:

tux > sudo dsctl ldap1 remove --do-it

6.2.4 Stopping and starting 389 Directory Server Edit source

Use systemd to manage your 389 Directory Server instance. Get the status of your server:

tux > systemctl status --no-pager --full dirsrv@ldap1.service
   ● dirsrv@ldap1.service - 389 Directory Server ldap1.
     Loaded: loaded (/usr/lib/systemd/system/dirsrv@.service; enabled; vendor preset: disabled)
     Active: active (running) since Thu 2021-03-11 08:55:28 PST; 2h 7min ago
    Process: 4451 ExecStartPre=/usr/lib/dirsrv/ds_systemd_ask_password_acl /etc/dirsrv/slapd-ldap1/dse.ldif (code=exited, status=0/SUCCESS)
   Main PID: 4456 (ns-slapd)
     Status: "slapd started: Ready to process requests"
      Tasks: 26
     CGroup: /system.slice/system-dirsrv.slice/dirsrv@ldap1.service
             └─4456 /usr/sbin/ns-slapd -D /etc/dirsrv/slapd-ldap1 -i /run/dirsrv/slapd-ldap1.pid

Start, stop, and restart your LDAP server:

tux > sudo systemctl start dirsrv@ldap1.service
tux > sudo systemctl stop dirsrv@ldap1.service
tux > sudo systemctl restart dirsrv@ldap1.service

See Chapter 15, The systemd daemon for more information on using systemctl.

The dsctl command also starts and stops your server:

tux > sudo dsctl ldap1 status
tux > sudo dsctl ldap1 stop
tux > sudo dsctl ldap1 restart
tux > sudo dsctl ldap1 start

6.2.5 Configuring admin credentials for local administration Edit source

For local administration of the 389 Directory Server, you can create a .dsrc configuration file in the /root directory, allowing root and sudo users to administer the server without typing connection details with every command. Example 6.3 shows an example for local administration on the server, using ldap1 and com for the base DN.

After creating your /root/.dsrc file, try a few administration commands, such as creating new users (see Section 6.5, “Managing LDAP users and groups”).

Example 6.3: A .dsrc file for local administration
# /root/.dsrc file for administering the ldap1 instance

[ldap1] 1

uri = ldapi://%%2fvar%%2frun%%2fslapd-ldap1.socket 2
basedn = dc=ldap1,dc=com
binddn = cn=Directory Manager

1

This must specify your exact instance name.

2

ldapi detects the UID and GID of the user attempting to log in to the server. If the UID/GID are 0/0 or dirsrv:dirsrv, ldapi binds the user as the directory server root dn, which is cn=Directory Manager.

In the URI, the slashes are replaced with %%2f, so in this example the path is /var/run/slapd-ldap1.socket.

6.3 Firewall configuration Edit source

The default TCP ports for 389 Directory Server are 389 and 636. TCP 389 is for unencrypted connections, and STARTTLS. 636 is for encrypted connections over TLS.

firewalld is the default firewall manager for SUSE Linux Enterprise. The following rules activate the ldap and ldaps firewall services:

tux > sudo firewall-cmd --add-service=ldap --zone=internal
tux > sudo firewall-cmd --add-service=ldaps --zone=internal
tux > sudo firewall-cmd --runtime-to-permanent

Replace the zone with the appropriate zone for your server. See Section 6.9, “Using CA certificates for TLS” for information on securing your connections with TLS, and Section 25.3, “Firewalling basics” to learn about firewalld.

6.4 Backing up and restoring 389 Directory Server Edit source

389 Directory Server supports making offline and online backups. The dsctl command makes offline database backups, and the dsconf command makes online database backups. Back up the LDAP server configuration directory, to enable complete restoration in case of a major failure.

The following commands use the example LDAP1 instance name.

6.4.1 Backing up the LDAP server configuration Edit source

Your LDAP server configuration is in the directory /etc/dirsrv/slapd-LDAP1. This directory contains certificates, keys, and the dse.ldif file. Make a compressed backup of this directory with the tar command:

tux > sudo tar caf config_slapd-LDAP1_$(date +%Y-%m-%d_%H-%M-%S).tar.gz /etc/dirsrv/slapd-LDAP1/
Note

When running tar, you may see the harmless informational message tar: Removing leading `/' from member names.

To restore a previous configuration, unpack it to the same directory:

  1. (Optional) To avoid overwriting an existing configuration, move it:

    tux > sudo old /etc/dirsrv/slapd-LDAP1/
  2. Unpack the backup archive:

    tux > sudo tar -xvzf config_slapd-LDAP1_DATE.tar.gz
  3. Copy it to /etc/dirsrv/slapd-LDAP1:

    tux > sudo cp -r etc/dirsrv/slapd-LDAP1 /etc/dirsrv/slapd-LDAP1

6.4.2 Creating an offline backup of the LDAP database and restoring from it Edit source

The dsctl command makes offline backups. Stop the server:

tux > sudo dsctl LDAP1 stop
Instance "LDAP1" has been stopped

Then make the backup using your instance name. This example creates a backup archive at /var/lib/dirsrv/slapd-LDAP1/bak/LDAP1/-2021_07_26_13_03_17:

tux > sudo dsctl LDAP1 db2bak
db2bak successful

Restore from this backup, naming the directory containing the backup archive:

tux > sudo dsctl LDAP1 bak2db /var/lib/dirsrv/slapd-LDAP1/bak/LDAP1-2021_07_26_13_03_17/
bak2db successful

Then start the server:

tux > sudo dsctl LDAP1 start
Instance "LDAP1" has been started

You can also create LDIF backups:

tux > sudo dsctl LDAP1 db2ldif --replication userRoot
ldiffile: /var/lib/dirsrv/slapd-LDAP1/ldif/LDAP1-userRoot-2021_07_28_08_47_30.ldif
db2ldif successful

Restore an LDIF backup with the name of the archive, then start the server:

tux > sudo dsctl ldif2db userRoot /var/lib/dirsrv/slapd-LDAP1/ldif/LDAP1-userRoot-2021_07_28_08_47_30.ldif
tux > sudo dsctl LDAP1 start

6.4.3 Creating an online backup of the LDAP database and restoring from it Edit source

Use the dsconf to make an online backup of your LDAP database:

tux > sudo dsconf LDAP1 backup create
The backup create task has finished successfully

This creates /var/lib/dirsrv/slapd-LDAP1/bak/LDAP1-2021_07_28_09_46_08.

Restore it:

tux > sudo dsconf LDAP1 backup restore /var/lib/dirsrv/slapd-LDAP1/bak/LDAP1-2021_07_28_09_46_08

6.5 Managing LDAP users and groups Edit source

Users and groups are created and managed with the dsidm command. It runs interactively, or you can run it on the command line, and enter all options in a single command.

The following examples use the instance name ldap1. Replace this with your instance name.

List your existing users and groups:

tux > sudo dsidm ldap1 user list
tux > sudo dsidm ldap1 group list

List all information on a single user:

tux > sudo dsidm ldap1 user get username

List all information on a single group:

tux > sudo dsidm ldap1 group get groupname

List members of a group:

tux > sudo dsidm ldap1 group members demo_group

In the following example we add two users, wilber and geeko, by specifying their data via command-line arguments. The example server instance is named ldap1, and the instance's suffix is dc=ldap1,dc=com.

Procedure 6.1: Creating LDAP users

LDAP users are your users that already exist. They should have Linux system accounts, with Linux logins and home directories. Adding them to your LDAP server provides central user management for your network. You need to enter accurate user data, which you can obtain by accessing the computers that hold their accounts, and running the id command, like this example for Wilber Fox:

tux > id wilber
uid=1001(wilber) gid=101(users) groups=101(users)
  1. Create the LDAP user wilber:

    tux > sudo dsidm ldap1 user create --uid wilber \
      --cn wilber --displayName 'Wilber Fox' --uidNumber 1001 --gidNumber 101 \
      --homeDirectory /home/wilber
  2. Verify by looking up your new user's distinguished name (fully qualified name to the directory object, which is guaranteed unique):

    tux > sudo dsidm ldap1 user get wilber
    dn: uid=wilber,ou=people,dc=ldap1,dc=com
    [...]

    You need the distinguished name for actions such as changing the password for a user.

  3. Create a password for new user wilber:

    1. tux > sudo dsidm ldap1 account reset_password \
        uid=wilber,ou=people,dc=ldap1,dc=com
    2. Enter the new password for wilber twice.

      If the action was successful, you get the following message:

      reset password for uid=wilber,ou=people,dc=ldap1,dc=com

      Use the same command to change an existing password.

  4. Verify that the user's password works:

    tux > ldapwhoami -D uid=wilber,ou=people,dc=ldap1,dc=com -W
    Enter LDAP Password: PASSWORD
    dn: uid=wilber,ou=people,dc=ldap1,dc=com

The following example deletes the user wilber:

tux > sudo dsidm ldap1 user delete
   Enter dn to delete : uid=wilber,ou=people,dc=ldap1,dc=com
   Deleting nsUserAccount uid=wilber,ou=people,dc=ldap1,dc=com :
   Type 'Yes I am sure' to continue: Yes I am sure
   Successfully deleted uid=wilber,ou=people,dc=ldap1,dc=com
Procedure 6.2: Creating LDAP groups and assigning users to them

In the following examples, we create a group, server_admins, and assign the user wilber to this group. The example server instance is named ldap1, and the instance's suffix is dc=ldap1,dc=com.

  1. Create the group:

    tux > sudo dsidm ldap1 group create

    You will be prompted for a group name. Enter your chosen group name, which in the following example is server_admins:

    Enter value for cn : server_admins
  2. Add the user wilber to the group:

    tux > sudo dsidm ldap1 group add_member server_admins uid=wilber,ou=people,dc=ldap1,dc=com
    added member: uid=wilber,ou=people,dc=ldap1,dc=com

6.6 Setting up SSSD Edit source

SSSD (System Security Services Daemon) is a daemon that communicates with remote identity providers and allows pam and nsswitch to consume that data. SSSD can have multiple back-ends, cache users and groups, and provides features such as SSH key distributions.

  1. On a separate server, install the sssd and sssd-ldap packages:

    tux > sudo zypper in sssd sssd-ldap
  2. Disable and stop the nscd daemon because it conflicts with sssd:

    tux > sudo systemctl disable nscd && systemctl stop nscd
  3. Create the SSSD configuration and restrict the login to the members of a group created for server admins, such as the server_admins groups that was set up in Procedure 6.2, “Creating LDAP groups and assigning users to them”:

    Tip
    Tip

    The memberOf plug-in needs to be enabled, so that clients can log in and authorize (see Section 6.7, “Managing modules”).

    tux > sudo dsidm ldap1 client_config sssd.conf server_admins
  4. Review the output and paste (or redirect) it to /etc/sssd/sssd.conf. If required, edit the configuration file according to your needs.

  5. To configure the certificates on your client, copy ca.crt from the LDAP server to your client, then rehash it:

    tux > sudo c_rehash /etc/openldap/certs
  6. Enable and start SSSD:

    tux > sudo systemctl enable --now sssd
  7. To make sure SSSD is part of PAM and NSS, follow the instructions in the sections Configure PAM (SUSE) and Configure NSS (SUSE) at https://www.port389.org/docs/389ds/howto/howto-sssd.html.

  8. Your users must have their own SSH key pairs, and SSH access to your SSSD server. If everything is set up correctly, wilber can access the 389 Directory Server instance via SSH to the machine where you have installed and configured SSSD. However, geeko will fail to do so, because geeko does not belong to the group server_admins, as configured in Procedure 6.2, “Creating LDAP groups and assigning users to them”.

6.7 Managing modules Edit source

Use the following command to list all available modules, enabled and disabled. Use your server's hostname rather than the instance name of your 389 Directory Server server, like the following example hostname of ldapserver1:

tux > sudo dsconf -D "cn=Directory Manager" ldap://ldapserver1 plugin list
[sudo] password for root: PASSWORD
Enter password for cn=Directory Manager on ldap://ldapserver1: PASSWORD

7-bit check
Account Policy Plugin
Account Usability Plugin
ACL Plugin
ACL preoperation
[...]

This is how to enable the MemberOf plugin referenced in Section 6.6, “Setting up SSSD”:

tux > sudo dsconf -D "cn=Directory Manager" ldap://ldapserver1 plugin memberof enable

Note that the plugin names used in commands are lowercase, so they are different from how they appear when you list them. If you make a mistake with a plugin name, you will see a helpful error message:

dsconf instance plugin: error: invalid choice: 'MemberOf' (choose from
'memberof', 'automember', 'referential-integrity', 'root-dn', 'usn',
'account-policy', 'attr-uniq', 'dna', 'linked-attr', 'managed-entries',
'pass-through-auth', 'retro-changelog', 'posix-winsync', 'contentsync', 'list',
'show', 'set')

After enabling a plugin, it is necessary to restart the server:

tux > sudo systemctl restart dirsrv@ldap1.service

To avoid having to restart the server, set the nsslapd-dynamic-plugins parameter to on:

tux > sudo dsconf -D "cn=Directory Manager" ldap://ldapserver1 config replace \
  nsslapd-dynamic-plugins=on
Enter password for cn=Directory Manager on ldap://ldapserver1: PASSWORD

Successfully replaced "nsslapd-dynamic-plugins"

6.8 Migrating to 389 Directory Server from OpenLDAP Edit source

OpenLDAP is deprecated and no longer supported as of SUSE Linux Enterprise 15 SP3. It has been replaced by 389 Directory Server. SUSE provides the openldap_to_ds utility to assist with migration, included in the 389-ds package.

The openldap_to_ds utility is designed to automate as much of the migration as possible. However, every LDAP deployment is different, and it is not possible to write a tool that satisfies all situations. It is likely there will be some manual steps to perform, and you should test your migration procedure thoroughly before attempting a production migration.

6.8.1 Testing migration from OpenLDAP Edit source

There are enough differences between OpenLDAP and 389 Directory Server that migration will probably involve repeated testing and adjustments. It can be helpful to do a quick migration test to get an idea of what steps will be necessary for a successful migration.

Prerequisites:

  • A running 389 Directory Server instance.

  • An OpenLDAP slapd configuration file or directory in dynamic ldif format.

  • An ldif file backup of your OpenLDAP database.

If your slapd configuration is not in dynamic ldif format, create a dynamic copy with slaptest. Create a slapd.d directory, for example /root/slapd.d/, then run the following command:

tux > sudo slaptest -f /etc/openldap/slapd.conf -F /root/slapd.d

This results in something similar to the following example:

tux > sudo ls /root/slapd.d/*

/root/slapd.d/cn=config.ldif

/root/slapd.d/cn=config:
cn=module{0}.ldif  cn=schema.ldif                 olcDatabase={0}config.ldif
cn=schema          olcDatabase={-1}frontend.ldif  olcDatabase={1}mdb.ldif

Create one ldif file per suffix. In the following examples, the suffix is dc=ldap1,dc=com. If you are using the /etc/openldap/slapd.conf format, use the following command to create the ldif backup file:

tux > sudo slapcat -f /etc/openldap/slapd.conf -b dc=ldap1,dc=com -l /root/ldap1-com.ldif

Use openldap_to_ds to analyze the configuration and files, and show a migration plan without changing anything:

tux > sudo openldap_to_ds ldap1 /root/slapd.d ldap1-com.ldif

This performs a dry run and does not change anything. The output looks like this:

Examining OpenLDAP Configuration ...
Completed OpenLDAP Configuration Parsing.
Examining Ldifs ...
Completed Ldif Metadata Parsing.
The following migration steps will be performed:
 * Schema Skip Unsupported Attribute -> otherMailbox (0.9.2342.19200300.100.1.22)
 * Schema Skip Unsupported Attribute -> dSAQuality (0.9.2342.19200300.100.1.49)
 * Schema Skip Unsupported Attribute -> singleLevelQuality (0.9.2342.19200300.100.1.50)
 * Schema Skip Unsupported Attribute -> subtreeMinimumQuality (0.9.2342.19200300.100.1.51)
 * Schema Skip Unsupported Attribute -> subtreeMaximumQuality (0.9.2342.19200300.100.1.52)
 * Schema Create Attribute -> suseDefaultBase (SUSE.YaST.ModuleConfig.Attr:2)
 * Schema Create Attribute -> suseNextUniqueId (SUSE.YaST.ModuleConfig.Attr:3)
[...]
 * Schema Create ObjectClass -> suseDhcpConfiguration (SUSE.YaST.ModuleConfig.OC:10)
 * Schema Create ObjectClass -> suseMailConfiguration (SUSE.YaST.ModuleConfig.OC:11)
 * Database Reindex -> dc=example,dc=com
 * Database Import Ldif -> dc=example,dc=com from example.ldif - excluding entry attributes = [{'structuralobjectclass', 'entrycsn'}]
No actions taken. To apply migration plan, use '--confirm'

The following example performs the migration, and the output looks different from the dry run:

tux > sudo openldap_to_ds ldap1 /root/slapd.d ldap1-com.ldif --confirm
Starting Migration ... This may take some time ...
migration: 1 / 40 complete ...
migration: 2 / 40 complete ...
migration: 3 / 40 complete ...
[...]
Index task index_all_05252021_120216 completed successfully
post: 39 / 40 complete ...
post: 40 / 40 complete ...
🎉 Migration complete!
----------------------
You should now review your instance configuration and data:
 * [ ] - Create/Migrate Database Access Controls (ACI)
 * [ ] - Enable and Verify TLS (LDAPS) Operation
 * [ ] - Schedule Automatic Backups
 * [ ] - Verify Accounts Can Bind Correctly
 * [ ] - Review Schema Inconistent ObjectClass -> pilotOrganization (0.9.2342.19200300.100.4.20)
 * [ ] - Review Database Imported Content is Correct -> dc=ldap1,dc=com

When the migration is complete, openldap_to_ds creates a checklist of post-migration tasks that must be completed. It is a best practice to document all of your post-migration steps, so that you can reproduce them in your post-production procedures. Then test clients and application integrations to the migrated 389 Directory Server instance.

Important
Important: Develop a rollback plan

It is essential to develop a rollback plan in case of any failures. This plan should define a successful migration, the tests to determine what worked and what needs to be fixed, which steps are critical, what can be deferred until later, how to decide when to undo any changes, how to undo them with minimal disruption, and which other teams need to be involved.

Due to the variability of deployments, it is difficult to provide a recipe for a successful production migration. Once you have thoroughly tested the migration process and verified that you will get good results, there are some general steps that will help:

  • Lower all hostname/DNS TTLs to 5 minutes 48 hours before the change, to allow a fast rollback to your existing OpenLDAP deployment.

  • Pause all data synchronization and incoming data processes, so that data in the OpenLDAP environment does not change during the migration process.

  • Have all 389 Directory Server hosts ready for deployment before the migration.

  • Have your test migration documentation readily available.

6.8.2 Planning your migration Edit source

As OpenLDAP is a box of parts and highly customizable, it is not possible to prescribe a one size fits all migration. It is necessary to assess your current environment and configuration with OpenLDAP and other integrations. This includes, and is not limited to:

  • Replication topology

  • High availability and load balancer configurations

  • External data flows (IGA, HR, AD, etc.)

  • Configured overlays (plug-ins in 389 Directory Server)

  • Client configuration and expected server features

  • Customized schema

  • TLS configuration

Plan what your 389 Directory Server deployment will look like in the end. This includes the same list, except replace overlays with plugins. Once you have assessed your current environment, and planned what your 389 Directory Server environment will look like, you can then form a migration plan. We recommended to build the 389 Directory Server environment in parallel to your OpenLDAP environment to allow switching between them.

Migrating from OpenLDAP to 389 Directory Server is a one-way migration. There are enough differences between the two that they cannot interoperate, and there is not a migration path from 389 Directory Server to OpenLDAP. The following table highlights the major similarities and differences.

FeatureOpenLDAP389 Directory ServerCompatible
Two-way replicationSyncREPL389 DS-specific systemNo
MemberOfOverlayPlug-inYes, simple configurations only
External AuthProxy-No
Active Directory Synchronization-Winsync Plug-inNo
Inbuilt SchemaOLDAP Schemas389 SchemasYes, supported by migration tool
Custom SchemaOLDAP Schemas389 SchemasYes, supported by migration tool
Database ImportLDIFLDIFYes, supported by migration tool
Password hashesVariesVariesYes, all formats supported excluding Argon2
OpenLDAP to 389 DS replication--No mechanism to replicate to 389 DS is possible
Time-based one-time password (TOTP)TOTP overlay-No, currently not supported
entryUUIDPart of OpenLDAPPlug-inYes

6.9 Using CA certificates for TLS Edit source

You can manage the CA certificates for 389 Directory Server with the following command line tools: certutil, openssl, and pk12util.

For testing purposes, you can create a self-signed certificate with dscreate. Find the certificate at /etc/dirsrv/slapd-localhost/ca.crt. For remote administration, copy the certificate to a readable location. For production environments, contact a CA authority of your organization's choice and request a server certificate, a client certificate, and a root certificate.

Make sure to meet the following requirements before executing the procedure below:

  • You have a server certificate and a private key to use for the TLS connection.

  • You have set up an NSS (Network Security Services) database (for example, with the certutil command).

Before you can import an existing private key and certificate into the NSS (Network Security Services) database, you need to create a bundle of the private key and the server certificate. This results in a *.p12 file.

Important
Important: *.p12 file and friendly name

When creating the PKCS12 bundle, you must encode a friendly name in the *.p12 file.

Make sure to use Server-Cert as the friendly name. Otherwise the TLS connection will fail, because the 389 Directory Server searches for this exact string.

Keep in mind that the friendly name cannot be changed after you import the *.p12 file into the NSS database.

  1. Use the following command to create the PKCS12 bundle with the required friendly name:

    root # openssl pkcs12 -export -in SERVER.crt \
      -inkey SERVER.key -out SERVER.p12 \
      -name Server-Cert

    Replace SERVER.crt with the server certificate and SERVER.key with the private key to be bundled. With -out, specify the name of the *.p12 file. Use -name to set the friendly name to use: Server-Cert.

  2. Before you can import the file into the NSS database, you need to obtain its password. To do this, use the following command:

    pk12util -i PATH_TO_SERVER.p12 -d sql:PATH_TO_NSS_DB -n Server-cert -W SERVER.p12_PASSWORD

    You can then find the password in the pwdfile.txt file in the PATH_TO_NSS_DB directory.

  3. Now import the SERVER.p12 file into your NSS database:

    pk12util -i SERVER.p12 -d PATH_TO_NSS_DB

6.10 More information Edit source

For more information about 389 Directory Server, see the upstream documentation, available at https://www.port389.org/docs/389ds/documentation.html.

Print this page