Manage OpenLDAP with the CLI

Presentation

The script slapd-cli provide start, stop and other commands for OpenLDAP daemon. It requires:

  • Logger, to forward messages to syslog

  • Awk, for regular expression management

  • OpenLDAP, for save, index,… tools

Configuration of this script can be done in an external file, with the same name as the slapd-cli program

The main features are:

  • start / stop / status of OpenLDAP daemon

  • check configuration

  • debug: start OpenLDAP in debug mode (stay attached)

  • reindex

  • backup / restore data

  • backup / restore configuration

  • check synchronization status

  • import test data / test configuration

Tip

This script is included by default in debian and red-hat OpenLDAP LTB packages. You can also get it from the main repository.

Usage of slapd-cli

The script can be launched like this:

slapd-cli action [optional arguments]

Tip

In OpenLDAP LTB packages, the script is available in /usr/local/openldap/sbin/slapd-cli. Anyway, with the PATH updated by /etc/profile.d/openldap-profile.sh, you can just run slapd-cli.

Action is a keyword between:

start

start the slapd server

stop

stop the slapd server

forcestop

kill the slapd server if it can’t stop

restart

restart the slapd server

debug

start the slapd server in debug mode (stay attached)

force-restart

forcestop + start

status

get the status of currently running slapd server

configtest

test configuration syntax

reindex

index or reindex database

backup

backup the data

restore

restore the data

backupconfig

backup the configuration

restoreconfig

restore the configuration

checksync

check the synchronization state of the current instance to every provider found in configuration

importflatconfigtemplate

import the flat template configuration file, after setting the variables

importldifconfigtemplate

import the ldif template configuration file, after setting the variables

convertconfig [inputfile.conf] [outputfile.ldif]

convert the input slapd configuration file into the equivalent ldif configuration

buildconfigtemplate [inputfile.ldif] [outputfile.ldif]

Get the input ldif configuration file and transform it into a template configuration

importdatatemplate

import the template data file, after setting the variables

lloadstart

start the load-balancer

lloadstop

stop the load-balancer

lloadstatus

get the status of currently running load-balancer

removeoldbackups

remove old configuration and data backup files (also done when calling backup and backupconfig actions)

Tip

slapd-cli provides autocompletion with slapd-cli-prompt configuration file, which is deployed by default in OpenLDAP LTB packages. That way, you just have to use the tab key to find out the actions and autocomplete file names.

Note

This script uses the last modification time of files to know which one to restore or to remove. If you modify a file directly in the backup directory, it will impact these actions.

Installation of slapd-cli

Note

The OpenLDAP installation path is assumed to be /usr/local/openldap.

Copy script in /usr/local/openldap/sbin:

# mv slapd-cli /usr/local/openldap/sbin
# chmod +x /usr/local/openldap/sbin/slapd

Configuration file must be installed into configuration folder:

# mkdir -p /usr/local/openldap/etc/openldap
# mv slapd-cli.conf /usr/local/openldap/etc/openldap/
# chmod 600 /usr/local/openldap/etc/openldap/slapd-cli.conf

Deploy template files into configuration folder:

# mv *-template.{conf,ldif} /usr/local/openldap/etc/openldap/

Optionally, deploy load-balancer configuration file:

# mv lload.conf /usr/local/openldap/etc/openldap/
# chmod 600 /usr/local/openldap/etc/openldap/lload.conf

Optionally, enable autocomplete:

# mv slapd-cli-prompt /etc/bash_completion.d/

Finally, you can decide to use the systemd services for slapd or lload:

# mv slapd-ltb.service /lib/systemd/system/
# systemctl --system daemon-reload
# systemctl enable slapd-ltb.service

# mv lload-ltb.service /lib/systemd/system/
# systemctl --system daemon-reload
# systemctl enable lload-ltb.service

Configuration of slapd-cli

Use the external file in /usr/local/openldap/etc/openldap rather than editing directly the script.

Following parameters are about network:

Parameter

Description

IP

Listen address for LDAP requests. Meta character * can be used for all interfaces

PORT

Listen port for LDAP requests. Use SLAPD_SERVICES if you need several ports

SSLIP

Listen address for LDAPS requests. Meta character * can be used for all interfaces

SSLPORT

Listen port for LDAPS requests. Use SLAPD_SERVICES if you need several ports

LDAPI_SOCKETDIR

Directory where LDAPI socket is created (will be created if it does not exist)

LDAPI_SOCKETURL

LDAPI socket URL (URL encoded value)

LDAPI_SOCKETMODE

Mode for LDAPI socket (by default 777)

LDAPI_SOCKETUSER

Owner user of LDAPI socket

LDAPI_SOCKETGROUP

Owner group of LDAPI socket

SLAPD_SERVICES

List of listen LDAP URIs, space-separated. It is made of all previous variables. This parameter is corresponding to -h option in slapd launch command.

Following parameters are about OpenLDAP directories and files:

Parameter

Description

SLAPD_PATH

OpenLDAP main directory

DATA_PATH

Data folder. You can set auto to let slapd-cli find out data paths in configuration

SLAPD_PID_FILE

Path to the pid file. It must match the olcPidFile configuration parameter

SLAPD_CONF

Path to the flat slapd.conf configuration file

SLAPD_CONF_DIR

Path to the slapd.d folder. When defined, SLAPD_CONF won’t be used anymore

SLAPD_BIN

slapd binary path

SLAPD_PARAMS

Additional options for slapd. Options -h, -f, -u and -g are already managed

SLAPD_MODULEDIR

Path to the library module folder

SLAPADD_BIN

slapadd binary path

SLAPADD_PARAMS

slapadd extra options

SLAPCAT_BIN

slapcat binary path

SLAPCAT_PARAMS

slapcat extra options

SLAPINDEX_BIN

slapindex binary path

SLAPTEST_BIN

slaptest binary path

LDAPSEARCH_BIN

ldapsearch binary path

Following parameters are about other options for slapd launch:

Parameter

Description

SLAPD_USER

Owner user of slapd process

SLAPD_GROUP

Owner group of slapd process

SLAPD_SYSLOG_LOCAL_USER

Syslog local user (by default local4)

TIMEOUT

Maximum delay waiting for slapd to stop. After, you need to use the forcestop action

FD_LIMIT

Maximum opened file descriptors

DEBUG_LEVEL

OpenLDAP log level to use in debug mode. Default is 256 (stats)

SYSTEMD_SERVICE_NAME

Name of slapd service in systemd. Default is slapd-ltb.

SYSTEMD_LLOAD_SERVICE_NAME

Name of lload service in systemd. Default is lload-ltb.

Following parameters are about backup and restore:

Parameter

Description

BACKUP_AT_SHUTDOWN

Do a backup data when slapd is stopped

BACKUP_PATH

Backup folder

BACKUP_SUFFIX

Backup file suffix

BACKUP_COMPRESS_EXT

Extension of LDIF compressed file. No compression is done if this is empty

BACKUP_COMPRESS_BIN

Binary used to compress LDIF file

BACKUP_UNCOMPRESS_BIN

Binary used to uncompress LDIF file

BACKUP_CONFIG_DELETE_AFTER_DAYS

Maximum days to keep a configuration backup file

BACKUP_DATA_DELETE_AFTER_DAYS

Maximum days to keep a data backup file

UMASK

command used for running umask

MASK

mask used for computing unix permissions while backuping

Following parameters are about data provisioning:

Parameter

Description

DATA_TEMPLATE_FILE

Path to template file used for data provisioning

DATA_SUFFIX

Suffix used for data provisioning. suffix is going to be replaced in DATA_TEMPLATE_FILE

DATA_ORGANIZATION

Organization (o attribute) used for the suffix in DATA_TEMPLATE_FILE

DATA_SERVICEACCOUNT_DN

Distinguished name for a service account.

DATA_SERVICEACCOUNT_PW

Password for the latter service account. Password must be clear-text. It will be hashed

DATA_ADMIN_<USER>_DN
Distinguished name for an admin account. <USER> must be replaced by any unique string.
You can add any number of admin accounts by choosing as many <USER> as you want.
Admins are no different from user account except that they are member of an admin group

DATA_ADMIN_<USER>_PW

Password for the latter admin account. Password must be clear-text. It will be hashed

DATA_ADMIN_<USER>_UID

uid attribute value for the admin account

DATA_ADMIN_<USER>_SN

surname for the admin account

DATA_ADMIN_<USER>_GN

givenname for the admin account

DATA_ADMIN_<USER>_MAIL

mail for the admin account

DATA_USER_<USER>_DN
Distinguished name for a user account. <USER> must be replaced by any unique string.
You can add any number of user accounts by choosing as many <USER> as you want.

DATA_USER_<USER>_PW

Password for the corresponding user account. Password must be clear-text. It will be hashed

DATA_USER_<USER>_UID

uid attribute value for the user account

DATA_USER_<USER>_SN

surname for the user account

DATA_USER_<USER>_GN

givenname for the user account

DATA_USER_<USER>_MAIL

mail for the user account

Following parameters are about configuration provisioning:

Parameter

Description

CONFIG_FLAT_TEMPLATE_FILE

Path to the flat slapd.conf template file used for configuration provisioning

CONFIG_LDIF_TEMPLATE_FILE

Path to the ldif template file used for configuration provisioning

CONFIG_SUFFIX

Main data base suffix

CONFIG_FQDN

Full-qualified domain name of the machine hosting slapd (used for olcSaslHost)

CONFIG_LOGLEVEL

Log level, see OpenLDAP olcLogLevel directive

CONFIG_LOGFILE

path of the log file, see OpenLDAP olcLogFile directive

CONFIG_MANAGERROOTDN

Distinguished name for the main data base superadmin

CONFIG_MANAGERROOTPW

Password for the main data base superadmin. Password must be clear-text. It will be hashed

CONFIG_CONFIGROOTDN

Distinguished name for cn=config superadmin

CONFIG_CONFIGROOTPW

Password for the cn=config superadmin. Password must be clear-text. It will be hashed

CONFIG_MONITORROOTDN

Distinguished name for cn=monitor superadmin

CONFIG_MONITORROOTPW

Password for the cn=monitor superadmin. Password must be clear-text. It will be hashed

CONFIG_DATADIR

Path to the main data base folder

Following parameters are about load balancer:

Parameter

Description

LLOAD_IP

Listen address for LDAP requests. Meta character * can be used for all interfaces

LLOAD_PORT

Listen port for LDAP requests. Use LLOAD_SERVICES if you need several ports

LLOAD_SSLIP

Listen address for LDAPS requests. Meta character * can be used for all interfaces

LLOAD_SSLPORT

Listen port for LDAPS requests. Use LLOAD_SERVICES if you need several ports

LLOAD_SOCKETURL

socket URL for load balancer (URL encoded value)

LLOAD_SERVICES
list of listen LDAP URIs, space-separated. It is made of all previous variables.
This parameter is corresponding to -h option in slapd launch command.

LLOAD_PID_FILE

Path to the pid file. It must match the olcPidFile configuration parameter

LLOAD_CONF

Path to the flat lload.conf configuration file

LLOAD_CONF_DIR

Path to the slapd.d lload conf folder. When defined, LLOAD_CONF won’t be used anymore

Run several OpenLDAP instances

You can run several OpenLDAP daemons on the same server.

Choose an instance name.

Link slapd-cli command: (replace <instance> by your instance name)

# ln -s /usr/local/openldap/sbin/slapd-cli /usr/local/openldap/sbin/slapd-<instance>-cli

Copy slapd-cli configuration file: (replace <instance> by your instance name)

# cp /usr/local/openldap/etc/openldap/slapd-cli.conf /usr/local/openldap/etc/openldap/slapd-<instance>-cli.conf

Edit new slapd-<instance>-cli.conf and change at least the following parameters:

  • PORT and SSLPORT

  • SLAPD_PID_FILE must be changed to: /usr/local/openldap/var/run/slapd-<instance>.pid. Take care to also change the PID file into OpenLDAP configuration (parameter olcPidFile)

  • SLAPD_CONF_DIR or SLAPD_CONF to a specific configuration directory or file. Typically, for a directory: SLAPD_CONF_DIR="/usr/local/openldap/etc/openldap/slapd.d-<instance>"

  • SYSTEMD_SERVICE_NAME to slapd-<instance>-ltb (and optionnally SYSTEMD_LLOAD_SERVICE_NAME to lload-<instance>-ltb)

  • BACKUP_PATH to a dedicated backup directory: /var/backups/openldap-<instance>

Run the openldap instance with: (replace <instance> by your instance name)

# systemctl start slapd-ltb@<instance>.service

You can also use the cli for running any command on the new instance:

# slapd-instance-cli backupconfig
slapd-instance-cli: [INFO] Using /usr/local/openldap/etc/openldap/slapd-instance-cli.conf for configuration
slapd-instance-cli: [INFO] Launching OpenLDAP configuration backup...
slapd-instance-cli: [OK] Configuration saved in /var/backups/openldap-instance/config-20240523174022.ldif