Learn LDAP - Troubleshooting

#Introduction

Sooner or later the directory misbehaves: a bind fails, a search is slow, replication stalls. Episode 27 teaches troubleshooting as a method, not a bag of tricks. You'll learn to read the logs at the right debug level, recognize the most common failure patterns, and follow a systematic path from symptom to cause.

#The Troubleshooting Mindset

Before touching commands, follow a discipline:

Reproduce — can you trigger the symptom reliably? If not, the "symptom" may be intermittent noise.
Isolate — is it the client, the network, or the server? Test each layer separately.
Read the logs first — logs contain the cause far more often than guessing does.
Change one thing at a time — re-test after every change; two simultaneous changes make the cause unidentifiable.
Document — what you tried, what you changed, what fixed it; the next incident is faster.

#Reading slapd Logs

Logs are the primary source of truth. Levels were covered in episode 18; here's how to use them for diagnosis:

Level	Diagnostic value
`stats`	operations, connections, bind results — the daily view
`conns`	connection lifecycle — connectivity problems
`filter`	the exact search filters arriving — query problems
`acl`	why an access was denied — authorization problems
`sync`	replication events — replication problems

Enable a level temporarily, reproduce the failure, then read the log:

Raising the log level temporarily

dn: cn=config
changetype: modify
replace: olcLogLevel
olcLogLevel: conns,filter,acl,stats

When the incident is over, return to stats. Debug levels are for diagnosis, not for production running — high levels crush throughput.

Important

stats2, packets, trace, and the highest debug levels are extremely noisy and slow the server. Never leave a high debug level running in production "just in case" — you'll diagnose the slowdown you caused before the original problem.

#Common Bind Failures

Symptom	Likely cause	Fix
result 49 (invalid credentials)	wrong password, or locked account (episode 12)	check credentials; check `pwdAccountLockedTime`
result 49 + "no such user"	account doesn't exist, or wrong search base	verify the DN; check the base
result 50 (insufficient access)	ACL denies the bind	review the ACLs in `cn=config`
result 13 (confidentiality required)	`olcSecurity: ssf` blocks a plain connection	connect with StartTLS/LDAPS
"connection refused"	firewall, or slapd down	`systemctl status slapd`; `nc -vz host 389`
result 91 (connect error)	network unreachable, DNS wrong	`ping`; `dig`; check `URI` config

Test binds layer by layer:

Isolating a bind failure

systemctl status slapd
nc -vz ldap.example.com 389
ldapwhoami -x -D uid=budi,ou=people,dc=example,dc=com -w wrongpass
ldapwhoami -x -Y EXTERNAL -H ldapi:///

#Common Search Failures

Symptom	Likely cause	Fix
empty result	wrong base, wrong filter	test the filter in `ldapsearch` step by step
result 4 (size limit exceeded)	`olcSizeLimit` too small for the query	raise the limit or narrow the filter
slow search	missing index (episode 14)	add `eq`/`sub` index, `slapindex`
partial result	scope wrong (base vs one vs sub)	check `-s base/one/sub`
result 32 (no such object)	base DN doesn't exist on this server	`ldapsearch -b dc=example,dc=com (objectClass=*)`
result 11 (admin limit)	server-imposed limits hit	check `olcLimits` and `olcTimeLimit`

The systematic search test:

Breadth-first search debugging

ldapsearch -x -b dc=example,dc=com "(objectClass=*)" dn
ldapsearch -x -b ou=people,dc=example,dc=com "(objectClass=inetOrgPerson)" dn
ldapsearch -x -b ou=people,dc=example,dc=com "(uid=budi)" dn

Each step narrows where the filter or base is wrong.

#Replication Troubleshooting

Symptom	Likely cause	Fix
lagging `contextCSN`	network, credentials, or provider overload	compare `contextCSN` on both sides; check the bind account
result 49 in replication bind	`cn=replicator` password changed	update `olcSyncrepl` credentials
no sync events in logs	`olcSyncrepl` not applied, or rid conflict	verify the config with `slaptest -u`
inconsistent data	conflict resolution by `contextCSN`	identify which node won; decide policy
"connection lost" loops	firewall, or provider restarted	check connectivity; the `retry` value handles reconnects

Checking replication health

ldapsearch -x -H ldap://ldap01.example.com -b dc=example,dc=com contextCSN
ldapsearch -x -H ldap://ldap02.example.com -b dc=example,dc=com contextCSN
grep -i syncrepl /var/log/slapd/slapd.log | tail -20

#Performance Troubleshooting

Slow search — is there an index for the filter's attribute? Compare time ldapsearch against the same query with -b a tiny base.
High CPU — what does cn=Monitor show? monitorOpCompleted per operation type tells you if searches dominate.
MDB_READERS_FULL — too many concurrent readers; raise olcDbMaxReaders (episode 25).
Write failures — olcDbMaxSize reached; the data file is full. This is the emergency case from episode 25.
Slow binds — is the password hash scheme fast to compute? {SSHA512} costs more than {SSHA}; measure if it matters.

CPU and connections at a glance

top -b -n1 | head -20
ldapsearch -x -D cn=admin,dc=example,dc=com -W \
  -b cn=Connections,cn=Monitor monitorConnectionTotal

#The Systematic Diagnostic Flow

When something is wrong, run this order:

systemctl status slapd — is the server alive?
slaptest -u — is the configuration valid?
ldapsearch -b dc=example,dc=com "(objectClass=*)" dn — can you read at all?
Raise olcLogLevel — reproduce the failure and read the log.
Isolate client vs network vs server — ldapsearch from the server itself, then from a client.
Fix one thing, re-test, and only then move on.

Note

The debug level -d flag on slapd -d 256 (which equals stats) is the offline twin of olcLogLevel — useful for a fresh manual start, never for a running production server.

#Closing

In this episode 27 you learned systematic troubleshooting: the reproduce-isolate-log discipline; reading slapd logs at the right level; the common bind, search, replication, and performance failures with their causes and fixes; and a six-step diagnostic flow from service status to log reading to isolated testing.

Key takeaways:

Logs first, guesses later — the level conns,filter,acl,stats covers most incidents.
Layer by layer — client, network, server; each test isolates one layer.
slaptest -u catches config errors early — before they become runtime mysteries.
Change one thing, re-test — the discipline is what makes troubleshooting reliable.

In the next episode, episode 28, we design for the long run: schema design best practices — DIT design, custom schema with OID allocation, normalization, and safe migration patterns.