- 1 LDAP Overview
- 2 LDAP troubleshooting
- 3 Integration with external LDAP servers
- 4 Connecting to an External LDAP Server with SSL
- 5 Provisioning users in LDAP
- 6 LDAP replication
- 7 Moving an LDAP Master
LDAP uses in ZCS
LDAP is used in ZCS to store data for
Additionally, information relating to:
LDAP in the system architecture
In every ZCS installation, there will be one and only one Master LDAP server. This server is authoritative for user information, server configuration, etc.
Additionally, one or more Replicas may be defined, to improve performance and reduce the load on the Master.
During installation in a multi-server environment, the LDAP server must be the first installed and configured, and must be running during any subsequent installations. The LDAP server must also be the first started in a multi-server environment.
If you're seeing ERROR: service.FAILURE (system failure: getDirectContext) (cause: javax.naming.CommunicationException localhost.localdomain:389) on installation, you're in the right place.
LDAP initialization generally fails due to the following
- Failure to start the LDAP server
- Failure to resolve the LDAP server
- Failure to connect to the LDAP server
The startup of the LDAP server during installation happens when the initialization script calls the ldap start script.
If this startup fails, all further initialization fails.
If you see something like the following when upgrading, verify that the sudoers file contains the proper allowances for the zimbra user.
[zimbra@mailhost ~]$ zmcontrol start Host mailhost.domain.com Starting ldap...Password:
Detecting startup failure
ps auxww | grep zimbra | grep slapd Should return a line containing: /opt/zimbra/openldap/libexec/slapd -l LOCAL0 -4 -u zimbra -h ldaps:// ldap://:389/ -f /opt/zimbra/conf/slapd.conf
If there is no output, LDAP is not starting. See the next section
If this line is present, verify that the zimbra system is detecting it (run as the zimbra user):
A return of:
slapd running pid: 7568 (your PID will vary)
If you get no such response from the ldap status command, it's likely that the running slapd process is hanging around from a previous installation. To kill it manually:
killall -TERM slapd ps auxww | grep zimbra | grep slapd
If the process is still there, determine it's PID (second column in the ps output) and
kill -9 PID
After cleaning up old LDAP processes, you should re-attempt the initialization by re-running zmsetup.pl
Ubuntu 6.10 LDAP Startup Solution
This applies to running the Debian build on Ubuntu, not the Ubuntu build
If you are getting the dreaded:
LDAP startup ... FAILED (256) on UBUNTU, I solved my problems with 2 changes:
1 UBUNTU by default symlinks /bin/sh to /bin/dash which does not support the 'source' command.
To fix rm /bin/sh ln -s bash /bin/sh
2 UBUNTU Server distro does not have a Java runtime, the certification startup
The zimbra installer requires the java runtime in the /jre directory. Zimbra has a JRE available so simply a second symlink will solve the problem To fix: ln -s /opt/zimbra/jdk1.5.0_08/jre /jre
Correcting startup failure
sh -x bin/ldap start
output from this should indicate the source of the problem
The problem may not be indicated in the command above. Instead, you should check your syslog, for logs originating from local0.
An alternative method is to execute the command executed by "ldap start", in my case, this was:
sudo /opt/zimbra/openldap-2.3.21/libexec/slapd -d7 -l LOCAL0 -4 -u zimbra -h ldap://localhost:389/ -f /opt/zimbra/conf/slapd.conf
Note the -d7 in the middle is used to troubleshoot and read debug logs on the screen.
LDAP and DNS
LDAP uses DNS to resolve the ldap host, even if it's localhost
To verify that you're able to resolve the ldap host:
- host ldap-hostname
Make sure you understand DNS.
Failure to Connect
To detect connection failure (using the hostname configured for the ldap server):
telnet ldaphostname 389
If this times out, or the connection is refused, there could be several causes.
If resolution succeeds, the initialization may fail because the LDAP server failed to start
If the server is running a local firewall, make sure it's allowing port 389 connections.
If the ldap hostname resolves to a public IP on an external firewall, make sure that firewall is allowing connections through on port 389.
Integration with external LDAP servers
Connecting to an External LDAP Server with SSL
If the external LDAP server has a self-signed certificate, you will need to add the cert to the Zimbra keystore(s). Use the following command (substitute your chosen alias and the path to your cert file; all on one line):
sudo /opt/zimbra/java/bin/keytool -import \ -alias EXTERNAL-LDAP \ -keystore /opt/zimbra/java/jre/lib/security/cacerts \ -storepass changeit \ -file EXTERNAL-LDAP-CERT-FILE
After adding the cert to the keystore, you'll need to restart Tomcat. As the zimbra user, do this:
tomcat stop && tomcat start
Make sure that you have selected SSL when configuring use of the external ldap server in the admin console. You can verify on the command line that this returns an "ldaps" url:
- zmprov gd DOMAIN.COM | grep zimbraAuthLdapURL
PS : in order to download the certificate, you can use openssl from the zimbra server :
openssl s_client -connect EXTERNAL-LDAP:636 > EXTERNAL-LDAP-CERT-FILE
You just have to clean the resulting file a bit...
Provisioning users in LDAP
The basic form for this is:
zmprov ca username@domain password
Additional attributes can be specified on the same command:
zmprov ca username@domain password attribute value attribute value
For creation of a single user, the admin console is the preferred method. If you need to bulk provision users, during initial installation, it can be easier to create a script.
EXAMPLE - creating several users at once:
Create a file containing all of the zmprov commands that you wish to run:
ca user1 user1pass ca user2 user2pass ca user3 user3pass ca adminuser adminuserpass zimbraIsAdminAccount TRUE ca user4 user4pass zimbraMailAlias user_4 zimbraMailAlias user_four zimbraMailAlias user.four ca nopassuser
Save this file (eg, usercreate.txt ). Then, run zmprov, redirecting standard input from this file:
zmprov < usercreate.txt
With this method, it's relatively straightforward to dump an existing ldap directory into a text file, format it for zmprov, and bulk-provision the users in the ZCS LDAP instance.
If you are using external LDAP authentication you can create the users with no local password by supplying the empty string "" after the username
Your LDAP Master server (machine 1) should be installed using normal ZCS installation options. The replica will be installed on a separate server (machine 2).
To install the replica server:
- Make sure the master is up and running before you apply the configuration to machine 2 and complete the installation.
- Use standard install.sh options, including the zimbra-ldap server.
- Set the zimbra-ldap server to DISABLED. This is very important, as if you leave it set to Enabled, it will just create a new directory server and you'll have two separate mail systems.
- Set the master LDAP server for machine 2 to be machine 1.
- Set the master LDAP password to the correct value (run zmlocalconfig -s ldap_root_password on the master to determine this value)
- Installation will complete as normal, and both servers will have their ZCS servers up, except for slapd on machine 2.
If you want to install an LDAP replica on a previously existing Zimbra server, you will need to use install.sh to install zimbra-ldap on the server. When install.sh asks if you wish to perform an upgrade, select Yes, then select Yes when it asks to install zimbra-ldap. The rest of the install will be similar to installing a disabled LDAP server on a new box.
After the servers are up, you need to set up a few things before the replica can be brought up.
- Enable replication on the master with the command /opt/zimbra/libexec/zmldapenablereplica
- Run /opt/zimbra/libexec/zmldapenablereplica on the replica. This will set up the replication account in the directory and will make a copy of the master on the replica. This should run cleanly.
- You may have to run zmcreatecert on machine 2 to create the conf/slapd.crt file. Just run it with no command line options. If this file is not present, slapd will not start.
When this is complete, you're done. You can test the replica by creating a few accounts through the administrative interface on the master server. You should be able to see them immediately with an LDAP search run against machine 2.
Increasing the LDAP logging level from 0 to 1 on the replica will allow you to see replication activity as well. To enable, run:
zmlocalconfig -e ldap_log_level=1 ldap stop; ldap start
LDAP logging will appear in /var/log/zimbra.log. It is recommended this setting be enabled only for testing and troubleshooting.
Using the Replica
To use the replica LDAP server after you've tested it, you now need to update the ldap_url value on the Zimbra servers you wish to have query the replica instead of the master. (Any services running on the replica server itself will automatically query the replica first.)
Use the ldap_url value set on the replica server as a template value (zmlocalconfig ldap_url). For each server you want to change:
- Stop the zimbra services on that server
- Update the ldap_url value (zmlocalconfig -e ldap_url="url url url") (quotes needed because of the space)
- Then start the services again
The order for the ldap_url key on the hosts using the replica should be replicas first, with the master listed last. The master must always be included!
Moving an LDAP Master
This procedure shows how to move the LDAP Master from one host to another. This is not recommended for use by those without at least some LDAP expertise, and could result in trouble for your system. It should be performed only if it is necessary to move the Master LDAP server from its current server to another.
To move the master LDAP directory:
- Create a replica on the machine that will become the new master using the instructions from LDAP Replication.
- Start services on all servers and ensure that the replica is picking up LDAP updates from the master.
- If everything is running correctly, shut down all servers again.
- On the new LDAP master, make a backup copy of $ZIMBRA_HOME/conf/slapd.conf.in. Remove the replication-related lines at the end of the file. This will be everything below TLSCACertificateFile /opt/zimbra/conf/ca/ca.pem.
- Edit zmlocalconfig on all hosts so that ldap_master_url and ldap_url now point to the new directory master.
- Edit zmlocalconfig on the new directory master so that ldap_is_master is set to true.
- Edit zmlocalconfig on the old directory master so that ldap_is_master is set to false.
- Start up services on all servers, starting with the new directory master.
At this point, services should be up and running on all hosts, and they should all be working off the new LDAP master. The old LDAP master can be disabled, or it can be converted into a replica by shutting it down, removing the contents of its openldap-data directory, and running zmldapenablereplica.