====== LDAP Server Configuration ======

AstLinux includes the [[http://www.openldap.org|OpenLDAP]] [[wp>Slapd|slapd]] server for distributing directory information, automatically configured to provide a public address book, when enabled.

In addition to providing [[wp>LDAP|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!!

===== General Configuration =====

The AstLinux Web Interface is used for configuration, click on **Configure LDAP Server**\\

Network tab -> Network Services:\\
{{:userdoc:ldap-network-tab.png?nolink|Configure LDAP Server}}

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:

{{:userdoc:ldap-missing-cert.png?nolink|Missing SIP-TLS Server Certificate}}

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...

{{:userdoc:ldap-basic-config.jpg?nolink|LDAP Server Basic Configuration}}

!!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.

{{:userdoc:ldap-set-passwords.jpg?nolink|LDAP Set Passwords}}

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 [[wp>LDAP_Data_Interchange_Format|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 [[http://www.zytrax.com/books/ldap|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.

  * [[http://sourceforge.net/projects/ldapaddrbook|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.
  * [[http://jxplorer.org|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/jxplorer'' to correct the wrong permissions.


===== LDAP Address Book =====

Default address book schema:

{{:userdoc:ldap-addressbook-schema.png?nolink|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 [[http://roundcube.net|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.  {{:userdoc:ldap-ldapab-tab.png?nolink|LDAP-AB Tab}}\\

{{:userdoc:ldap-addressbook-manage.jpg?nolink|LDAP Address Book Management}}

!!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 ''dn:'' for ''ou=addressbook'' to be included at the beginning (example ''dc=ldap'' base):

  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 [[https://nic-nac-project.org/~kaosmos/morecols-en.html|MoreFunctionsForAddressBook]].
  * For **MS Outlook** there are commercial 3rd-party tools available to export to vCard.\\ [[http://www.msoutlook.info/question/803|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 =====

**Yealink SIP-T28P:**\\
Firmware: 2.61.0.80

{{:userdoc:ldap-example-yealink.jpg?nolink|Yealink}}

**Cisco (Linksys) SPA-942:**\\
Firmware: 6.1.5(a)

{{:userdoc:ldap-example-spa942.jpg?nolink|SPA942}}

**snom 360:**\\
Firmware: 8.7.3.19

{{:userdoc:ldap-example-snom.jpg?nolink|snom 360}}

===== 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"