Set Reliable LDAP Client Defaults with ldap.conf

You will finish with a per-user OpenLDAP client configuration that supplies the LDAP server, base DN, search limits and TLS certificate checks without putting a password in a file. The examples match the ldap.conf(5) shipped by OpenLDAP 2.6.10 on Ubuntu package libldap-common 2.6.10+dfsg-0ubuntu0.24.04.1.

Allow about fifteen minutes. You need a shell, a working LDAP endpoint, its base DN and the CA certificate file or certificate directory used by your organisation. An LDAP client such as ldapsearch or ldapwhoami is useful for the final check, but it is separate from libldap-common. The commands below do not change a directory server.

1. Choose a user configuration file

Start with ~/.ldaprc. It changes defaults for your account and does not need elevated privileges. OpenLDAP also reads ~/ldaprc and ./ldaprc; a file called ldaprc in the current directory can therefore change the result when you run a command elsewhere.

Check whether an existing file is already present before editing it:

$ ls -l ~/.ldaprc ~/ldaprc ./ldaprc 2>/dev/null
$ printf 'LDAPNOINIT=%s\nLDAPCONF=%s\nLDAPRC=%s\n' \
    "${LDAPNOINIT-}" "${LDAPCONF-}" "${LDAPRC-}"

Checkpoint: if LDAPNOINIT is set, OpenLDAP disables all defaulting. That includes the normal system and user files, so unset it for this workflow:

$ unset LDAPNOINIT LDAPCONF LDAPRC

Do not put a bind password in ldap.conf or an environment variable. Those locations are commonly readable by processes, shell history tools or diagnostic output.

2. Write the connection and search defaults

Make a backup if the file exists, then create a new file with a restrictive mode. This is an ordinary user-level change:

$ if test -e "$HOME/.ldaprc"; then
    cp --preserve=mode,ownership,timestamps "$HOME/.ldaprc" "$HOME/.ldaprc.bak"
  fi
$ umask 077
$ editor "$HOME/.ldaprc"

Put a configuration like this in the editor, replacing the uppercase placeholders with values from your directory administrator:

# One or more space-separated server URIs
URI     ldaps://ldap.example.test
BASE    ou=People,dc=example,dc=test
VERSION 3
REFERRALS off
TIMEOUT 10
NETWORK_TIMEOUT 10
SIZELIMIT 100
TIMELIMIT 30

# Use the CA that issued the LDAP server certificate
TLS_CACERT /etc/ssl/certs/example-directory-ca.pem
TLS_REQCERT demand

URI is preferred over the deprecated HOST and PORT settings. The scheme selects the transport: ldap:// normally uses port 389, ldaps:// normally uses 636, and ldapi:// addresses a local Unix socket. A space-separated URI list lets the library try more than one server.

BASE supplies the default search base. It is a DN, not a URL, and commas inside a DN value must be escaped or represented using DN quoting. Do not quote the whole value just because it contains spaces: quotes become part of the value for this file format. Comments occupy their own lines; an inline # is not a safe way to annotate an option.

Checkpoint: inspect the result and permissions:

$ sed -n '1,120p' "$HOME/.ldaprc"
$ stat -c '%A %n' "$HOME/.ldaprc"
-rw------- /home/you/.ldaprc

3. Make TLS verification explicit

For a TLS connection, keep TLS_REQCERT demand, which is the installed default and requires the server certificate checks to succeed. allow and try permit weaker outcomes, while never disables certificate checking. Do not use TLS_REQCERT never to get around a certificate error: it removes the protection that prevents an attacker from impersonating the directory.

If your organisation supplies a directory of individual CA certificates instead of one bundle, use TLS_CACERTDIR. The manual specifies a semicolon-separated list of directories and says that TLS_CACERT is used first when both are set. A wrong CA path is meant to fail closed. Check the file without printing its private contents:

$ test -r /etc/ssl/certs/example-directory-ca.pem && \
    echo 'CA file is readable'
CA file is readable

On this Debian-based installation, TLS_PROTOCOL_MIN and TLS_RANDFILE are ignored because OpenLDAP is linked against GnuTLS. Do not add those settings as a supposed fix for a TLS negotiation problem. Check the server's supported protocol and the GnuTLS configuration instead.

4. Test the defaults with a read-only query

Use a read-only search against a known-safe base. The command needs no sudo. Replace the placeholders and use the authentication method required by your directory; -x selects simple authentication for command-line tools, and omitting -D performs an anonymous search where the server permits it:

$ ldapsearch -x -LLL \
    -b 'ou=People,dc=example,dc=test' \
    '(uid=KNOWN_TEST_USER)' dn uid

Expected output is an LDIF entry containing at least a dn: line and the requested uid:, or a deliberate 'no such object' or empty result if the test value does not exist. A successful connection with no matching entry still proves that the client reached the server and used a valid base.

If the client is not installed, check without changing anything:

$ command -v ldapsearch || echo 'install the LDAP client tools through the normal package process'

Do not paste a password into a command line. If a bind is required, use the client's supported prompt or credential mechanism, and confirm your local tool's manual before choosing an option.

5. Understand overrides when a command behaves differently

OpenLDAP reads settings in layers. Unless LDAPNOINIT is defined, the order is the system file /etc/ldap/ldap.conf, user files in the home and current directories, any file named by LDAPCONF or LDAPRC, and finally environment variables named from options, such as LDAPBASE. Later values override earlier ones. Some options, including BINDDN, are user-only and are ignored in the system file.

For a one-off test, use a temporary environment override and remove it when the command ends:

$ LDAPBASE='ou=People,dc=example,dc=test' \
  ldapsearch -x -LLL '(uid=KNOWN_TEST_USER)' dn uid

This is useful for proving that a surprising result comes from the base DN rather than the server. It is also a common distraction trap: an inherited LDAPBASE, LDAPURI or LDAPNOINIT can make a carefully edited file appear ineffective. Check the environment in the same shell that launches the client.

6. Roll back or install a system-wide default

If the new user configuration causes a problem, restore the backup and rerun the read-only test:

$ mv -- "$HOME/.ldaprc.bak" "$HOME/.ldaprc"
$ ldapsearch -x -LLL -b 'ou=People,dc=example,dc=test' '(uid=KNOWN_TEST_USER)' dn uid

If there is no backup, move the file aside rather than deleting it so you can inspect it later:

$ mv -- "$HOME/.ldaprc" "$HOME/.ldaprc.disabled"

Only install a system-wide default when you have reviewed its effect on every LDAP client on the host. Editing /etc/ldap/ldap.conf requires elevated privileges and can disrupt services or scripts that use the shared library. Preserve the existing file, make the smallest change, and keep a tested recovery copy. The user file is usually the safer place to prove the settings first.