LDAP Server Configuration
In addition to providing LDAP services for local devices, (IP Phones, desktop SIP clients, etc.), the default LDAP Address Book may be shared by various email and contacts applications supporting LDAP on a vast variety of devices.
Note: AstLinux 1.1.4 or later is required
The AstLinux Web Interface is used for configuration, click on Configure LDAP Server
Network tab → Network Services:
The LDAP server supports secure SSL/TLS connections, as such it requires a certificate. For convenience by default, the LDAP server shares the Asterisk SIP-TLS Server Certificate. If you already created one, you are good and can skip the next step, if not you will see the following entry:
Click SIP-TLS Certificate, use a Key Size of 2048 Bits and set the “Server Cert DNS Name” to the host.domain of your AstLinux box. When completed, navigate back to the LDAP Server Configuration screen and the previous “Missing SIP-TLS…” section should no longer be displayed.
Continuing, the basic default settings are as follows…
Tip → Leaving the Admin Password blank uses the hashed (not cleartext) password used by the web interface. Though if the LDAP-AB tab is used it may be convenient to define the Admin Password.
The Base DN entry may be left at it's default “dc=ldap” (recommended) unless you have a federated system of LDAP servers, in such a case you may want to define a more global Base DN such as “dc=ldap,dc=example,dc=com” to create a unique domain-component.
Note → The LDAP data naming is based on the Base DN entry, so any change in the Base DN after the server is populated will require LDAP skills to migrate the previous Base DN data or simply populate the new Base DN with new directory data.
Note → The AstLinux default schema requires the Base DN entry to begin with dc= as in the examples above.
By default two users are automatically created in the LDIF schema:
- cn=directory,ou=users - A read-only user with a default, well known, password that must be changed.
- cn=staff,ou=users - A read/write user whose default password is the same as the “staff” web interface password, if defined, or else a well known password that must be changed.
Before we can change the default “ou=users” passwords the LDAP Server must be “enabled”, Save Settings, then Restart LDAP. You will now see a 'Set “ou=users” Passwords' section.
The “cn=admin” password is required to make the “ou=users” password changes, copied from the “Admin Password” setting previously in the dialog, if empty you must use the web interface “admin” password.
Note → Successful password changes will be noted in the syslog.
Introduction to LDAP
LDAP is a complex subject. Technically, LDAP is just a protocol that defines the method by which directory data is accessed. Necessarily, it also defines and describes how data is represented in the directory service. Finally, it defines how data is loaded (imported) into and saved (exported) from a directory service using LDIF. LDAP does not define how data is stored or manipulated. Data storage and access methods are 'automagical' processes as far as the standard is concerned and are generally handled by back-end modules within any specific LDAP implementation.
The good news is for the scope of AstLinux, a basic address book, created in a standard way can provide directory services to many different clients without being complex. Typically this implies a single LDAP (slapd) server for the local network.
Tip → This Open Source Guide LDAP for Rocket Scientists is about LDAP, OpenLDAP 2.x and ApacheDS on Linux and the BSD's. It is meant for newbies, Rocket Scientist wannabees and anyone in between.
LDAP Client Tools
A brief, and far from complete list of LDAP client tools and applications an AstLinux administrator may find useful is listed below.
- LDAP Address Book An LDAP Client, written in Java by John Dawson, designed to act as the front end for a global address book implemented as an LDAP directory. Supports full read/update/delete access to directory entries. Fully configurable for all schemas.
- JXplorer JXplorer is a cross platform LDAP browser and editor.
Note → For Mac OS X execute:
chmod 755 jxplorer-3.3.02.app/Contents/MacOS/jxplorerto correct the wrong permissions.
LDAP Address Book
Default address book schema:
By default two users are automatically created in the LDIF schema:
- cn=directory,ou=users - A read-only user to the address book.
- cn=staff,ou=users - A read/write user to the address book.
The “ou=groups” is empty by default, but some LDAP clients such as Roundcube address book can be configured to use “ou=groups” when organizing groups of addresses without cluttering-up the “ou=addressbook” entry.
The Web Interface can be used to manage the LDAP address book.
Tip → When using the LDAP-AB tab it may be convenient to define the Admin Password in the LDAP Server Configuration sub-tab and Restart LDAP, as such the “cn=admin” password will not have to be repeatedly entered.
The file size limit for imported files is 5 MB via the web interface. The CLI command
vcard-export may be used for larger vCard files.
Typically one of the Import vCard “Sanitize…” options is required since the LDIF schema specifications for a telephone number is quite specific, any one or more invalid numbers will case the import to fail.
The Import LDIF file requires the parent
ou=addressbook to be included at the beginning (example
dn: ou=addressbook,dc=ldap objectClass: organizationalUnit ou: addressbook
This is automatic for any Export LDIF
.ldif.txt file to be imported later.
vCard Export from Applications
To import your contacts into the LDAP Addressbook you need to export your contacts as a single multi-contact vCard file (*.vcf):
- In the OS X Apple Contacts/Addressbook application you can easily export a group of contacts
by right-clicking on a groupname and selecting “Export Group vCard…”
- For Thunderbird you'll need an external Add-on like MoreFunctionsForAddressBook.
- For MS Outlook there are commercial 3rd-party tools available to export to vCard.
Here is also a trick without 3rd-party tools (not tested!).
Note → In Germany we use sometimes strange number-formatting like “+49 (0) 89-12345678”, that means from within Germany you would call “089 12345678” from abroad e.g. “0049 89 12345678”. You need to fix those formats before you import the *.vcf file into OpenLDAP, because the vCard-Import-Filter would change this number to “+49-0-89-12345678” which would be wrong. - MK
Example LDAP Phone Configurations
Cisco (Linksys) SPA-942:
CLI LDAP Command Examples
Below is a quick reference for common LDAP operations via the CLI. The examples assume the Base DN is “dc=ldap”, adjust accordingly.
Export Address Book LDIF:
ldapsearch -xW -D "cn=admin,dc=ldap" -b "ou=addressbook,dc=ldap" -H ldap://127.0.0.1 -LLL > addressbook.ldif
Import LDIF, while saving the current ou=addressbook as ou=addressbook-old:
ldapdelete -xW -D "cn=admin,dc=ldap" -H ldap://127.0.0.1 -r "ou=addressbook-old,dc=ldap" # error OK ldapmodrdn -xW -D "cn=admin,dc=ldap" -H ldap://127.0.0.1 -r "ou=addressbook,dc=ldap" "ou=addressbook-old" ldapadd -xW -D "cn=admin,dc=ldap" -H ldap://127.0.0.1 -f addressbook.ldif
Revert the saved ou=addressbook-old back to ou=addressbook on Import Error:
ldapdelete -xW -D "cn=admin,dc=ldap" -H ldap://127.0.0.1 -r "ou=addressbook,dc=ldap" # error OK ldapmodrdn -xW -D "cn=admin,dc=ldap" -H ldap://127.0.0.1 -r "ou=addressbook-old,dc=ldap" "ou=addressbook"
Change “ou=users” Passwords:
ldappasswd -xW -D "cn=admin,dc=ldap" -H ldap://127.0.0.1 -S "cn=directory,ou=users,dc=ldap" ldappasswd -xW -D "cn=admin,dc=ldap" -H ldap://127.0.0.1 -S "cn=staff,ou=users,dc=ldap"