When transitioning from traditional CA certificates to Let's Encrypt in OpenLDAP environments, many administrators encounter mysterious SSL handshake failures despite proper certificate placement. The error SSL_connect SYSCALL returned=5 typically indicates a mismatch between the server's TLS configuration and client expectations.
OpenLDAP requires three essential certificate components:
olcTLSCACertificateFile: /path/to/fullchain.pem
olcTLSCertificateFile: /path/to/cert.pem
olcTLSCertificateKeyFile: /path/to/privkey.pem
The common pitfalls include:
- Using symlinked Let's Encrypt paths without proper permissions
- Missing intermediate certificates in the chain
- Incorrect ownership of private key files
First, verify certificate chain integrity:
openssl verify -CAfile /etc/letsencrypt/live/domain.com/fullchain.pem \
/etc/letsencrypt/live/domain.com/cert.pem
Then create a new TLS configuration file (tls.ldif):
dn: cn=config
changetype: modify
add: olcTLSCACertificateFile
olcTLSCACertificateFile: /etc/letsencrypt/live/domain.com/fullchain.pem
-
add: olcTLSCertificateFile
olcTLSCertificateFile: /etc/letsencrypt/live/domain.com/cert.pem
-
add: olcTLSCertificateKeyFile
olcTLSCertificateKeyFile: /etc/letsencrypt/live/domain.com/privkey.pem
Let's Encrypt certificates typically have restrictive permissions. For OpenLDAP:
chown openldap:openldap /etc/letsencrypt/live/domain.com/{privkey.pem,fullchain.pem,cert.pem}
chmod 640 /etc/letsencrypt/live/domain.com/privkey.pem
After applying changes, verify with:
ldapsearch -ZZ -H ldap://localhost -D "cn=admin,dc=example,dc=com" -W -b "dc=example,dc=com"
For more detailed debugging, enable TLS logging in slapd.conf:
olcLogLevel: 16384
When direct modifications fail, try recreating the entire TLS configuration:
ldapmodify -Y EXTERNAL -H ldapi:/// <When switching to Let's Encrypt certificates for OpenLDAP, many administrators encounter the frustrating "SSL_connect SYSCALL returned=5" error. Here's how I solved this issue in our production environment:
ldapsearch -x -H ldaps://localhost:636 -b "" -s base -ZZ
# Returns: ldap_start_tls: Connect error (-11)
OpenLDAP has specific requirements for TLS certificates that differ from typical web server configurations:
# Certificate files must have these exact permissions:
sudo chmod 644 /etc/letsencrypt/live/ldap.example.com/cert.pem
sudo chmod 600 /etc/letsencrypt/live/ldap.example.com/privkey.pem
sudo chown openldap:openldap /etc/letsencrypt/live/ldap.example.com/privkey.pem
The most reliable method I've found is using ldapmodify with this LDIF:
dn: cn=config
changetype: modify
add: olcTLSCACertificateFile
olcTLSCACertificateFile: /etc/letsencrypt/live/ldap.example.com/fullchain.pem
-
add: olcTLSCertificateFile
olcTLSCertificateFile: /etc/letsencrypt/live/ldap.example.com/cert.pem
-
add: olcTLSCertificateKeyFile
olcTLSCertificateKeyFile: /etc/letsencrypt/live/ldap.example.com/privkey.pem
-
add: olcTLSVerifyClient
olcTLSVerifyClient: never
Execute with:
sudo ldapmodify -Y EXTERNAL -H ldapi:/// -f tls-config.ldif
When troubleshooting, always check these components:
# 1. Verify certificate chain
openssl verify -CAfile /etc/letsencrypt/live/ldap.example.com/fullchain.pem \
/etc/letsencrypt/live/ldap.example.com/cert.pem
# 2. Test TLS connection
openssl s_client -connect localhost:636 -showcerts \
-CAfile /etc/letsencrypt/live/ldap.example.com/fullchain.pem
Special considerations for Let's Encrypt certificates:
- Symbolic links in /etc/letsencrypt/live/ must be preserved
- Certificate renewal must trigger OpenLDAP reload
- Subject Alternative Names (SANs) must include all used hostnames
# Example renewal hook for OpenLDAP:
sudo systemctl restart slapd
- Verify file permissions and ownership
- Confirm all three certificate files are properly specified
- Check for syntax errors in slapd configuration
- Test both ldapsearch and application connections
- Set up proper logging with olcLogLevel 256 (TLS)