Yolinux.com Tutorial

YoLinux LDAP Tutorial: Deploying OpenLDAP 2.x/1.2

LDAP Directory Server Installation and configuration


Description: Lightweight Directory Access Protocol (LDAP) is a means of serving data on individuals, system users, network devices and systems over the network for e-mail clients, applications requiring authentication or information. The LDAP server is a means of providing a single directory source (with a redundant backup optional) for system information look-up and authentication. Using the LDAP server configuration example on this page will enable you to create an LDAP server to support email clients, web authentication, etc. We have many useful links for other LDAP deployments. LDAP can also be distributed in a hierarchical fashion but my examples refer to a single LDAP server. This tutorial will cover the setup and configuration of an LDAP server on Linux, the loading of data and use. Once configured, I recommend "Apache Directory Studio" or "gq" as an admin tool.

Simply put, this tutorial will enable you to create an LDAP server to which your e-mail clients (Outlook, Mozilla, Netscape, etc) can connect with their address books. It will allow one to search the LDAP database for people's e-mail addresses which are then pulled into the address list. Try it out with Thunderbird, Mozilla, Netscape or Outlook on our LDAP site ldap.yolinux.com for a demo. Cool eh! You will also be able to authenticate applications of OS system logins. You can also try out authentication by pointing your application to authenticate on our demo server at ldap.yolinux.com.

LDAP Server Tutorial Table of Contents:

Linux LDAP rolodex

Related YoLinux LDAP Tutorials:

°slapd configuration

°Client Linux system login authentication

°Apache Web Site Authentication

°LDAP bind Authentication

°Extending schemas

°Schema for MS/Outlook

°LDAP for email clients

°LDAP web client

°YoLinux Tutorials Index




Free Information Technology Magazines and Document Downloads
TradePub link image


   

    Bookmark and Share


Advertisements




Why LDAP?:

LDAP can provide a central directory of information for:
OpenLDAP Tutorial: LDAP Server Installation, Configuration, Loading data, Usage Overview.

The following steps will lead to an operational OpenLDAP 2.x server:

  1. Install packages:
    • Red Hat / Fedora RPM packages openldap, openldap-clints, openldap-servers and openldap12: openldap, openldap-clients, openldap-servers, openldap12
      (rpm -ivh openldap-2.x...rpm openldap-clients-2.x...rpm openldap-servers-2.x...rpm openldap12-1.2...rpm)
    • Ubuntu (dapper 6.06)/Debian: slapd, ldap-utils, libldap2, libldap2-dev, libdb4.2
    • Ubuntu (hardy 8.04)/Debian: slapd, ldap-utils, libdb4.3
    • S.u.S.e.: openldap2, openldap2-client
  2. Edit configuration files:
    • slapd.conf - Holds configuration info, domain info, admin info and references "include files".
      • Red Hat / Fedora: /etc/openldap/slapd.conf
      • Ubuntu / Debian: /etc/ldap/slapd.conf
        (Ubuntu 6.06) See example: /usr/share/slapd.slapd.conf)
    • /etc/default/slapd - (Ubuntu) Defaults should be ok.
    • Create the include file for the Object definition. This defines the data to be held by the LDAP server. (Use include file or add it to end of slapd.conf) It is easiest to use an existing LDAP object class that comes pre-defined with OpenLDAP. If this does not meet your requirements define a new object which inherits basic attributes from an existing and defined object class.
  3. Generate Dynamic Configuration Files: This is exclusively for RHEL6 which does not use the configuration files directly but requires that you use the slapd.conf file to generate a tree of directories and files which can be dynamically updated. Changes are then made using the command ldapmodify
  4. Create an LDIF data file: This is the actual data you wish to store in the LDAP database. It follows an object model (data schema) defined in either a pre-existing object definition or in an object model definition you have defined in a slapd.conf include file.
  5. Start the LDAP database:
    • Red Hat RHEL6/ CentOS 6: service slapd start (or: /etc/init.d/slapd start)
      Start configuration in /etc/sysconfig/ldap
      # Options of slapd (see man slapd)
      #SLAPD_OPTIONS=
      
      # At least one of SLAPD_LDAP, SLAPD_LDAPI and SLAPD_LDAPS must be set to 'yes'!
      # Run slapd with -h "... ldap:/// ..."   yes/no, default: yes
      SLAPD_LDAP=yes
      # Run slapd with -h "... ldapi:/// ..."   yes/no, default: yes
      SLAPD_LDAPI=yes
      # Run slapd with -h "... ldaps:/// ..."    yes/no, default: no
      SLAPD_LDAPS=no
              
    • Red Hat RHEL4,5/ CentOS 4,5 / Fedora: service ldap start (or: /etc/init.d/ldap start)
    • Ubuntu (dapper 6.06 - hardy 8.04)/ Debian: /etc/init.d/slapd start
    (Option: Starting LDAP manually (as root): /usr/sbin/slapd -u ldap -h '"ldap:/// ldaps:///"')
  6. Load the LDIF data file into the database:
    • ldapadd -f file-name.ldif -xv -D "CN-with-privileges" -h host-name-of-server -W
      you will be prompted for a password. or
    • ldapadd -f file-name.ldif -xv -D "CN-with-privileges" -h host-name-of-server -w password
  7. Test LDAP: Use an e-mail client such as Mozilla Seamonkey, Netscape or Outlook to access the data on the server.
  8. Manage:View, query and make changes to the data using the web front-end aWebDap or admin tools like "Apache Directory Studio" or "gq". (or use LDAP command line interface) Try the online aWebDap demo.

LDAP Server - Quick Start Example and Test:

(This will result in an operational LDAP server with data.)

Download and use the following two sample files:

  1. slapd.conf
  2. stooges.ldif - LDAP data file
    (Simple noauth ldif example: stooges.ldif)

Note for Fedora Core 3 and later: (OpenLDAP 2.2.13 and later) Add the statement "allow bind_v2" after the schema "include" directives in the file /etc/openldap/slapd.conf if you wish to allow the use of older clients.

Then execute the following commands as root:

  1. mkdir /var/lib/ldap/stooges /var/lib/ldap/fraternity
  2. Update or replace /etc/openldap/slapd.conf with file supplied for this demo.
  3. Build slapd.d dynamic configuration directory tree (this step is specific to RHEL 6/CentOS 6):
    • Clean up old configuration and data files:
      rm -Rf /etc/openldap/slapd.d/*
      rm -f /var/lib/ldap/alock
      rm -f /var/lib/ldap/__db.00?
              
    • See configuration with a default database configuration file:
      [root]# cp /usr/share/openldap-servers/DB_CONFIG.example /var/lib/ldap/stooges/DB_CONFIG
      [Potential Pitall]: If this step is not taken slaptest will give this error:
      bdb_db_open: warning - no DB_CONFIG file found in directory /var/lib/ldap/stooges: (2).
    • Generate initial database:
      [root]# echo “” | slapadd -f slapd.conf
      The first database does not allow slapadd; using the first available one (2)
      str2entry: entry -1 has no dn
      slapadd: could not parse entry (line=1)
              
    • Generates initial configuration tree in /etc/openldap/slapd.d/:
      [root]# slaptest -f /etc/openldap/slapd.conf -F /etc/openldap/slapd.d
      config file testing succeeded
      [root]# chown -R ldap.ldap /etc/openldap/slapd.d
      [root]# chmod -R u+rwX /etc/openldap/slapd.d
      [root]# chcon -u system_u -t slapd_db_t /var/lib/ldap/stooges
              
      [Potential Pitall]: If you did not generate a database first with slapadd you get this error:
      bdb_db_open: database "o=stooges": db_open(/var/lib/ldap/stooges/id2entry.bdb) failed: No such file or directory (2).
  4. Set file ownership:
    • Red Hat/CentOS/Fedora:
      • chown -R ldap.ldap /var/lib/ldap/stooges /var/lib/ldap/fraternity /etc/openldap/slapd.conf
      • SELinux: chcon -u system_u -t slapd_db_t /var/lib/ldap/stooges /var/lib/ldap/fraternity
        chcon -u system_u -t etc_t /etc/openldap/slapd.conf
        (This step should not be necessary. Verify security context settings with ls -lZ)
    • Ubuntu:
      • chown openldap.openldap /var/lib/ldap/stooges /var/lib/ldap/fraternity /etc/ldap/slapd.conf
      • Ubuntu hardy 8.04: Change the security policy to allow subdirectories under /var/lib/ldap/:
        Edit file: /etc/apparmor.d/usr.sbin.slapd
        change from: /var/lib/ldap/* rw,
        to: /var/lib/ldap/** rwk,
        Restart Apparmor: /etc/init.d/apparmor restart
  5. Start LDAP service:
    • Red Hat Enterprise 6: /etc/init.d/slapd start
    • Red Hat Enterprise 4,5/Fedora: /etc/init.d/ldap start
    • Ubuntu/Debian/RHEL6: /etc/init.d/slapd start
    Note: You may have to stop an already running service.
  6. ldapadd -f stooges.ldif -xv -D "cn=StoogeAdmin,o=stooges" -h 127.0.0.1 -w secret1
    (or use the flag "-W" and get prompted for the password)

Test with the OpenLDAP command line client:
ldapsearch -vLx -h 127.0.0.1 -b "o=stooges" "(sn=Fine)"

Test with an email client:

  • Mozilla:
    • Configure: Open the Address Book: "Window" + "Address Book" + "File" + "New" + "LDAP Directory ..."
      "General" Tab
      • Name: Stooges
      • Hostname: localhost
      • Base DN: o=stooges
      • Port Number: 389
    • Restart Mozilla, select "Window" + "Mail and News Groups" + "Compose".
    • Select icon "Address" + "Stooge" + Search for "&" to get all email addresses.
  • Netscape Messenger:
    • Configure: "Communicator" + "Address Book" + "File" + "New Directory..." +
      • Description: Stooges
      • LDAP Server: localhost
      • Server Root: o=stooges
      • Port Number: 389
    • Use: "Communicator" + "Messenger" + "New Msg" icon + "Address" icon + change pull-down menu from "Personal Address Book" to "Stooges". For all enter "*". To search for Moe, enter "moe". (you don't even need to press enter, just wait.) Try the "Search for.." with Name "*" and Department "MemberGroupA". Excellent!

Install the aWebDap CGI executable to provide a user web front-end for search and updates. [Demo]

If you wish to add a second domain try this file: fraternity.ldif
Use the command: ldapadd -f fraternity.ldif -xv -D "cn=DeanWormer,o=delta" -w secret2

Read the rest of this tutorial to see what it all means!
If this doesn't work check out the LDAP pitfall section below.
To secure the LDAP database see the YoLinux LDAP Password Protection and Authentication Tutorial. (Note: This is authentication for the user to access the LDAP database and not using LDAP to authenticate applications)

To run a more complex example with an extended schema to optimally support MS/Outlook and Netscape Communicator see the YoLinux GILSE tutorial and example. If you are going to configure LDAP for your office, you will eventually want to follow this guide.


LDAP V3 improvements:

Note: OpenLDAP version numbers are independent of LDAP version standards.
  • Authentication and data security services via Simple Authentication and Security Layer (Cyrus SASL and MD5) and certificate based authentication using Transport Layer Security (GnuTLS) or Secure Socket Layer (OpenSSL)
  • Unicode to support internationalization
  • Referrals and Continuations
  • Schema Discovery
  • Extensibility (controls, extended operations, and more)


OpenLDAP Versions:

Linux versionOpenLDAP version
Ubuntu 12.042.4.28
Red Hat Enterprise Linux 6
CentOS 6
2.4.23
Red Hat Enterprise Linux 5
CentOS 5
2.3.27
Red Hat Enterprise Linux 4
CentOS 4
2.2.13
Fedora 32.2.29
Ubuntu 8.042.4.9


LDAP Data Schema:

LDAP uses an object oriented approach to data and data modeling which includes object definitions (collection of data attributes and rules) and object inheritance.

The data schema for LDAP is defined by the:
  • domain: (i.e. company name)
  • object classes
    • required attributes: Attributes which must be included to define the object. (i.e. person's last name)
    • allowed attributes: Additional attributes which may be included but are not requires. (i.e. fax number)
    • optional: "Superior" object (Defines a hierarchy by linking object to a parent object class)
  • attribute types
  • allowable comparison operation / filter

The statements which describe the object classes and attributes are different in Open LDAP versions 1.2 and 2.x. Unless you require a unique custom configuration it is easiest to use the pre-defined object inetOrgPerson (RFC 2798) included with OpenLDAP 2.x or to define an new object which inherits the inetOrgPerson object schema.

Each LDAP data entry has a "Distinguished Name" (DN) by which it is identified. Each component of the DN is called a "Relative Distinguished Name" (RDN). Operations against the LDAP data include adding, deleting, modifying and querying based on a query filter.


LDAP Configuration/Operation:
  1. Configuration Files for slapd: This LDAP daemon (slapd) configuration files define the data schema for the data it contains as well as system configurations (i.e. files and database type to use, etc...).

    slapd.conf:
    The main configuration file for the LDAP daemon is: /etc/openldap/slapd.conf (Ubuntu/Debian: /usr/share/slapd/slapd.conf)
    Two versions of OpenLDAP have been released and each has its' own method of configuration, schema definition and configuration statements. The file slapd.conf will reference other "include" files which will contain LDAP data schema definitions.

    The main difference between OpenLDAP 1.2 and 2.x is in the object and attribute definitions. OpenLDAP 2.x objects and attributes use OID's while version 1.2 does not. The slapd and database directives are close to being the same with minor enhancements in version 2.x.

    Password Encryption and Security: See the OpenLDAP password FAQ
    To secure the LDAP database see the YoLinux LDAP Password Protection and Authentication Tutorial
    To create a custom data object by extending the inetOrgPerson object see the new LDAP Object/Attribute definition tutorial

  2. LDIF: Defining Data for the LDAP database
    The input ascii data file format required by LDAP is the ldif format.
    For a more complete example see: OpenLDAP 2.x slapd.conf configuration and LDIF example
    To create a new custom object by extending the inetOrgPerson schema see the new LDAP object/attribute definition tutorial

    The following LDIF example uses the inetOrgPerson object model:

    dn: o=domain-name                      - Define the LDAP root
    objectClass: top
    objectClass: organization
    o: domain-name
    description: Full Company Name

    dn: cn=AdminManager,o=domain-name      - Data entries for the system administrator for the domain as defined in the file: slapd.conf
    objectClass: organizationalRole
    cn: AdminManager
    description: LDAP Directory Administrator

    Note: The following "DN" is great for address book support. For LDAP login authentication server support only, you may want to use the following attributes: uid, mail or employeeNumber.

    dn: cn=Larry Fine,o=domain-name
    cn: Larry Fine                           - Yes it is mentioned in the dn statement but it is repeated here
    objectClass: top                         - These objectclass statements MUST go here for Open LDAP
    objectClass: person
    objectClass: organizationalPerson
    objectClass: inetOrgPerson
    mail: LFine@isp.com
    givenname: Larry
    sn: Fine
    postalAddress: 14 Cherry St.
    l: Dallas
    st: TX
    postalCode: 76888
    telephoneNumber: (800)555-1212
    seeAlso: dc=www,dc=domain-name,dc=org       - Correct method: DN must be previously defined in order to reference it. i.e. dn: dc=www,dc=domain-name,dc=org
    XX Wrong Way! XX seeAlso: http://www.domain-name.org/~larry/ - OpenLDAP object inetOrgPerson expects a DN and this entry cannot be added directly so DO NOT ADD THIS LINE!!!
    jpegPhoto: < file:///path/to/file.jpeg       - JPEG photo from file.
    OR
    jpegPhoto: < http://domain/path/to/file.jpeg - It's in the documentation but I never got it to work.

    ...
    ..

    For a full list of allowable attributes see:

    • objectClass definition: person - File: /etc/openldap/schema/core.schema
    • objectClass definition: organizationalPerson - File: /etc/openldap/schema/core.schema
    • objectClass definition: inetOrgPerson - File: /etc/openldap/schema/inetorgperson.schema

    The LDIF example above corresponds to the following slapd.conf entries for OpenLDAP 2.x:

    database ldbm                - Define the database to be used by LDAP. Each database definition begins with a database statement.
                                   [Tutorial Update]: This tutorial defines ldbm to be the database. (RH 6-9 default)
                                                      Many are now recomending
    bdb or hdb. FC-3 defaults to bdb.
                                                      Ubuntu 8.04 defaults to hdb.

    suffix "o=domain-name"         [Tutorial Update]: As of OpenLDAP 2.1.13, only one suffix is supported per database.
                                                      Previously this example showed two suffixes defined.

    rootdn "cn=AdminManager,o=domain-name"
    rootpw super-secret-password                      For extra security, encrypt password with slappasswd
    directory /var/lib/ldap/domain-directory
    defaultaccess read
    schemacheck on
    lastmod on
    index cn,sn,st pres,eq,sub

    An alternate style for a base "dn":

    • Entry in file: /etc/openldap/slapd.conf
      Examples:
      • suffix "dc=ldap,dc=domain-name,dc=org"
      • suffix "dc=domain-name,dc=org"
      • suffix "st=Texas,c=US"
      • suffix "o=CompanyXXX,st=Texas,c=US"
      • suffix "o=stooges,dc=domain-name,dc=org"
      • suffix "ou=accounting,dc=domain-name,dc=org"
      The suffix defines the base of the directory tree. In a distributed system, various nodes may represent the root of a branch of a larger tree. The root shall be globally unique and static (does not change). Example tree:
                              dc=domain-name,dc=org
                                         |
                      ----------------------------------------
                      |                                      |
                     c=us                 c=jp (Use suffix: c=jp,dc=domain-name,dc=org if on a separate server)
                      |                                      |
               -------------------                       ------------------
               |        |        |                       |       |        |
      ou=accounting  ou=sales  ou=research     ou=accounting  ou=sales  ou=research
      
    • LDIF data file: (Match base "dn" as defined in the suffix statement.)
          dn: dc=ldap,dc=domain-name,dc=org    - First define the LDAP domain
          objectClass: top
          objectClass: dcObject
          objectClass: organization
          dc: domain-name
          o: domain-name
          description: Full Company Name Domain
      
      

    Note: As of OpenLDAP 2.1.2.13, the default configuration will allow only one suffix to be defined for each bdb database. The C preprocessor directive #define BDB_MULTIPLE_SUFFIXES (file: servers/slapd/back-bdb/init.c) may be used if you want to compile in multiple suffix support. If you use it, subtree indexing will slow down by factor of 2. The use of suffixAlias is no longer supported by default in version 2.1.13.

    For more inetOrgPerson data schema info see:

    • Object definition file: /etc/openldap/schema/inetorgperson.schema
    • RFC 2798 - Definition of the inetOrgPerson LDAP Object Class

     

    inetOrgPerson object attributes:
    • Requires:
      • objectClass: organizationalPerson
      • objectClass: person (Inherited from object organizationalPerson)
      • objectClass: top (Inherited from object person)
      • sn (Surename/Last Name - Inherited from object person)
      • cn (Common Name - Inherited from object person)
    • May have:
      • o (Organization Name)
      • displayName (RFC2798: Preferred name of a person to be used when displaying entries)
      • audio
      • businessCategory
      • carLicense
      • departmentNumber
      • employeeNumber
      • employeeType (i.e. "Contractor", "Employee", "Intern", "Temp", "External", "Unknown", etc...)
      • givenName
      • homePhone
      • homePostalAddress (After street number and name use line separator "$" in LDIF file: street$ st postalCode)
      • initials (MS/Outlook considers this to be the middle name)
      • jpegPhoto (See the OpenLDAP FAQ: Turn a jpeg into ldif format)
      • labeledURI
      • mail (e-Mail address)
      • manager (Specify dn entry of manager)
      • mobile
      • pager
      • photo
      • roomNumber
      • secretary (Specify dn entry of secretary)
      • uid
      • userCertificate
      • x500uniqueIdentifier
      • preferredLanguage
      • userSMIMECertificate (RFC2633: A PKCS#7 [RFC2315] SignedData)
      • userPKCS12 (PKCS #12 [PKCS12] provides a format for exchange of personal identity information.)
      • Attributes inherited from object organizationalPerson:
        • ou (Organization unit)
        • title
        • x121Address
        • registeredAddress
        • destinationIndicator
        • preferredDeliveryMethod
        • telexNumber
        • teletexTerminalIdentifier
        • telephoneNumber (MS/Outlook considers this to be the "Business Phone")
        • internationaliSDNNumber
        • facsimileTelephoneNumber
        • postOfficeBox
        • postalAddress (MS/Outlook and Netscape both use this for the business address.)
        • physicalDeliveryOfficeName (MS/Outlook considers this to be the field "Office")
        • street (Don't use "street" because Netscape can't use it. Use "postalAddress".)
        • l (Locality/City/Town)
        • st (State/Province)
        • postalCode (Zip code)
      • Attributes inherited from object person:
        • userPassword
        • telephoneNumber (work phone)
        • seeAlso (URL for more info)
        • description

    Helpful LDIF links:

    Notes:

    • Note that the objectclass statement immediately follows the dn and cn definitions. By specification this should not be necessary but it is for Open LDAP. Do not put it at the end as does the Netscape Communicator ldif file.
    • Each distinguished name (dn) definition in the ldif file must have one or more object classes. Resolve name collisions and duplicate entries by appending an emplyee number or special character. You can also reference an LDAP attribute guarenteed to be unique such as an emplyee number or email address in the "dn". Consider the "dn" to be a permanent value which is not updated as the other LDAP enties may be.
    • U of Michigan literature suggests that the dn statement should be normalized with no extra blank spaces (bad: a comma, then blank space, then data). It also recommended against the use of alternate delimiters, use comma only. Database normalization to me means no duplicate data, but this is what I read. It is true that an extra blank between parameters may break ldap URL's generated from it.
    • Trailing spaces are not trimmed from the values in an LDIF file, nor are internal spaces compressed. (from Open LDAP admin manual-7)
    • A line may be continued by starting the next line with a single space or tab. (from Open LDAP admin manual-7)
    • If a line begins with a space, colon, '< or the line contains a non-printable character, the attribute is followed by a double colon and the base64 encoded equivalent.
    • All parts of the dn except the organizational name, are each represented as an attribute entry. This is a requirement of LDAP.
    • Note that the administrator is listed in the database and the name matches that defined by the "rootdn" statement in the slapd.conf file.
    • It might be tempting to create a bunch of organizational units (ou) and place people under these in the dn statement. DON'T! It's a pain to restructure later if people are moved. Best to assign as an attribute and leave it out of the dn statement.
    • Loading the ldif address book from Netscape Communicator:
      (As described in ldap_db.cc of ldapconf)
      • Add the domain definition to the beginning of the file.
      • Add this definition to all dn statements.
      • Move/add objectclass statements to lines following dn line.
      • Add the the above attributes and class.

      Note that some of the attribute names have changed:

      Communicator ldif attributeMapping for Open LDAP
      modifytimestampDrop this piece of data from ldif file.
      Generated upon creation
      xmozillanicknameAdded attribute nickname
      xmozillausehtmlmailAdded attribute usehtmlmail
      givennameAdded attribute givenname
      streetaddressUsed existing attribute "postalAddress" instead
      countrynameDrop or use existing attribute "c" instead.
      (Note: "c" not part of inetOrgPerson object. Schema must be extended to use it.)
      xmozillauseconferenceserverDropped this piece of data.
      pagerphoneUsed existing attribute "pager" instead
      cellphoneUsed existing attribute "mobile" instead
      homeurlUsed existing attribute "seeAlso" instead.
      Must first define as a DN and then refer to DN.
      xmozillaanyphoneDropped this piece of redundant data.

      For more LDIF info see:

  3. Starting and stopping LDAP:
    LDAP interaction is with the slapd daemon. This can be invoked (on Redhat) by /etc/init.d/ldap start or Ubuntu /etc/init.d/slapd start. Upon startup the slapd daemon will read the /etc/openldap/slapd.conf file.

    To stop the slapd LDAP daemon: /etc/init.d/ldap stop (or Ubuntu: /etc/init.d/slapd stop)

    Note: Edit configuration files first and then start the system.

  4. Load LDAP with the following command:
    • OpenLDAP 2.x (RH 7.x/8.0/9.0):
      • Adding LDIF data to a running LDAP server:
                    ldapadd -f input-def.ldif -xv -D "cn=AdminManager,o=domain-name" -W 
                
        • x - Use simple authentication instead of SASL.
        • v - Verbose mode. Highly recommended for debugging purposes.
        • c - Continuous mode. Don't stop if one fails, skip it and keep going.
        • h - Host name of server (or IP address)
        • D - Use the given "dn" to bind to the database.
        • W - Prompts for simple authentication.
        The program will prompt for the password specified by the "rootpw" statement in the slapd.conf file. (As defined by the option -W)
      • Generating an LDAP database from an LDIF file:

                    slapadd -l input-def.ldif -cv
                
        I like to use this method for debugging an LDIF file as it generated good error messages. The LDAP server (slapd) MUST NOT be running when using this command.
    • OpenLDAP 1.2 (RH 6.x):
                  ldapadd -cv -D "cn=AdminManager, o=domain-name.org" -W < input-def.ldif
              
      • c - Continuous mode. Don't stop if one fails, skip it and keep going.
      • v - Verbose mode. Highly recommended for debugging purposes.
      • D - Use the given "dn" to bind to the database.
      • W - Prompts for simple authentication.

      The program will prompt for the password specified by the "rootpw" statement in the slapd.conf file. (As defined by the option -W)

  5. Test LDAP with the following command: OpenLDAP 2.x
        ldapsearch -vLx -b "o=domain-name" "(objectclass=*)"
        or
        ldapsearch -vLx -h 127.0.0.1 -b "o=domain-name" "(objectclass=*)"
    
        Stooges example: ldapsearch -vLx -h 127.0.0.1 -b "o=stooges" "(sn=Fine)"
    
    The addition of the "-x" argument enables simple authentication (you are asked for the password specified as rootpw defined in the file /etc/openldap/slapd.conf) instead of SASL.
    The expression "-h 127.0.0.1" will specify localhost explicitly. (It's the only way I can get it to work.)

    OpenLDAP 1.2

        ldapsearch -L -b "cn=AdminManager, o=domain-name" "(objectclass=*)"
        or
        ldapsearch -h "ldap.domain-name" -L -b "o=domain-name" "(sn=Fine)"
    

     

    Test LDAP with Your Netscape Browser: Use an LDAP enabled browser with an appropriate URL:
      ldap://ldap.yolinux.com/cn=Larry Fine,ou=MemberGroupA,o=stooges
    
    This method will display directory information in the Netscape browser. MS/Windows Explorer will defer the information to the MS/Outlook address book for display and data transfer.

    For more on LDAP URL's see RFC 2255: The LDAP URL Format.

     

    Test LDAP with an E-mail client: The true test is of course is with an e-mail client. See the list of clients and links to configuration notes at the top of this page.

    Netscape Messenger 4.5+:

    Adding custom search boxes: File: $HOME/.netscape/preferences.js
    (MS/Windows clients: C:\ProgramFiles\Netscape\Users\user-name\prefs.js)
    (This step is not required, it just makes for a more intuitive presentation within the client)
    user_pref("ldap_2.servers.domain-name.attributes.ou", "Attribute-Display-Name:LDAP-Database-Attribute");
    user_pref("ldap_2.servers.domain-name.filter1", "(&(objectclass=LDAP-Object-Schema-Name)(LDAP-Database-Attribute=%s))");
    pref("ldap_2.servers.domain-name.maxHits", 400);
    
    If your organization has an attribute you wish employees to use as a searchable item, you can configure Netscape Messenger to display an advanced search box with the appropriate label by using the Javascript configuration statements above. The display changes will only apply to the domain specified. Substitute the bold italic entries with the appropriate data for your application. (i.e. LDAP-Object-Schema-Name could be inetOrgPerson and the LDAP-Database-Attribute could be any of that objects' attributes you wish to search such as "carLicense") By default Netscape 4.7x only displays the search items "Name", "Email", "Organization" and "Department".

    Example - Allow a search by State:

    user_pref("ldap_2.servers.Stooges.attributes.ou", "State:st");
    user_pref("ldap_2.servers.Stooges.filter1", "(&(objectclass=inetOrgPerson)(st=%s))");
    
    Note:
    • Terminate the Netscape program before editing the file, then edit the file and then re-start Netscape.
    • The domain is specified without the "." and is the same as the "Description" name.

Security Considerations:
  • The "rootdn" password in our examples is "secret1" and held as plain text in the file /etc/openldap/slapd.conf. This can be encrypted using the slappasswd command:
    # slappasswd
    New password: password1
    Re-enter new password: password1
    {SSHA}vLTyN8Y35FqQzJcBgDum9r93zSN/uPTu
        
    This can then be placed in /etc/openldap/slapd.conf replacing the previous pasword reference:
    database	bdb
    suffix		"o=stooges"
    checkpoint      1024 15
    rootdn		"cn=StoogeAdmin,o=stooges"
    rootpw          {SSHA}vLtYn8y35gQqZjCbGdfm9r93zSN/upbu
    directory	/var/lib/ldap/stooges
    lastmod         on
    index   cn,sn,st		eq,pres,sub
        
  • RHEL6 supports two forms of authentication for LDAP clients:
    • SSSD ( System Security Services Daemon):
      requires TLS/SSL or LDAPS. Note that TLS requires a certificate server or you get the following error: Could not start TLS encryption. TLS error -8157:Certificate extension not found.
      Requires install packages: sssd sssd-client
      Command: authconfig –enableldap –enableldapauth –ldapserver=”localhost″ –ldapbasedn=”o=stooges” –enableldaptls –update
      GUI: authconfig-gtk
    • NSLCD based Authentication
      Requires install packages: nss-pam-ldapd pam_ldap
      Commands:
      authconfig –enableforcelegacy –update
      authconfig –enableldap –enableldapauth –ldapserver=localhost –ldapbasedn=”o=stooges” –update
      service nslcd start

Performance Considerations:
  • Index:

    For large LDAP databases one should index the searchable item. This will create an additional index file but will greatly enhance the speed of a search. For example the slapd.conf directive index cn eq will support an equality test (eq) on the LDAP "common name" (cn) attribute. This will only work if the name is an exact match. If using a wildcard in the search, then the substring match needs to be added: index cn eq,sub
    Note that certain LDAP attributes do not support substring searches.

    The index must be created with the initial configuration and database load or regenerated using the command slapindex.

    Add an index to an LDAP data field by defining it in the file: /etc/openldap/slapd.conf

    OpenLDAP 2.x

       index       sn,postalcode   pres,eq,sub
    
    Note that OpenLDAP 2.x requires that you mention the type of comparison filter used for the index.

    LDAP QualifierDescription
    presIs the search attribute present as any value in the LDAP directory. Return all that have an entry. i.e. (st=*) returns all entries with a state entry regardless of the entry
    eqDoes the search string exactly match the attribute in the LDAP directory.
    subDoes the search string match a substring of the attribute in the LDAP directory. i.e. (sn=*nderso*) or (sn=*anderson*)
    noneNo index generated. Items like JPEG photo are not searchable items anyway.
    approxIs the search string approximately equal to attribute based on a "metaphonic" algorithm. Not permitted in OpenLDAP.

    OpenLDAP 1.2

       index       sn,postalcode
    
    This will increase the speed of searches for entries based on surname and postalcode.

    To apply an index after a database has been created, dump the data and reload the data with LDAP restarted with the index defined.

    Also see the command slapindex which can re-generate an LDAP database index. (Must stop the slapd server first as it acts directly against the database.)

  • LDBM Cache:

    Add a cache definition in the file: /etc/openldap/slapd.conf
    The following cache directives apply only to LDBM (default database) and must follow the "database ldbm" statement.

    cachesize       5000      - Size of in-memory cache used by LDBM
    dbcachesize     1000000   - Cache size in bytes associated with index file opened by the system
    

    It is recommended that the dbcachesize be set to the size of the largest index files.

  • Logging Level:

    Run at a lower debug level to produce less logging output to log files: I have found that this can produce significant performance boost if you have been "over logging". Try setting logging to "none" with the option -d 32768. One can view the complete list of logging options with the comand slapd -d ?

    Installed log subsystems:
    
            Any                            (4294967295)
            Trace                          (1)
            Packets                        (2)
            Args                           (4)
            Conns                          (8)
            BER                            (16)
            Filter                         (32)
            Config                         (64)
            ACL                            (128)
            Stats                          (256)
            Stats2                         (512)
            Shell                          (1024)
            Parse                          (2048)
            Sync                           (16384)
            None                           (32768)
      
    Results for OpenLDAP 2.4.9

    slapd and ldapsearch both include a "debugging" option:
    /usr/sbin/slapd -d 3 -f /etc/openldap/slapd.conf
    or
    add options to init script (Red Hat/Fedora/CentOS): /etc/init.d/ldap (or Ubuntu/Debian: /etc/init.d/slapd).

    Note:
    • RH 6.x default configuration runs straight with defaults. (no command line options)
    • RH 7.1 default configuration:
      • Runs under the user id "ldap". Slapd command line option: -u ldap
      • Specifies a URL: -h '"ldap:/// ldaps:///"'

    To add options, create the file: (as referenced by the init script)
    • Red Hat/Fedora/CentOS: /etc/sysconfig/ldap
    • Ubuntu/Debian: /etc/default/slapd

    i.e.:
            SLAPD_OPTIONS="-d 3"       (RH 6.x OpenLDAP 1.2)
    
            SLAPD_OPTIONS="-d 32 -d 64 -d 256"       Extreme level of debugging. Leave blank for defaults. 
                                                     Default is 256. (RH 7.1 OpenLDAP 2.0)
            
    LDAP Options Config File: (Options used by init script /etc/init.d/ldap to start LDAP)
    • Red Hat: /etc/sysconfig/ldap
    • Ubuntu: /etc/default/slapd
    Default optionDescription
    SLAPD_CONFRed Hat default: SLAPD_CONF="/etc/openldap/slapd.conf"
    Ubuntu default: SLAPD_CONF="/etc/ldap/slapd.conf"
    SLAPD_USERRed Hat default: SLAPD_USER="ldap"
    Ubuntu default: SLAPD_USER="openldap"
    SLAPD_PIDFILEPath to the pid file of the slapd server. Typically set by the init.d script.
    SLAPD_SERVICESUbuntu: SLAPD_SERVICES="ldap://127.0.0.1:389/ ldaps:/// ldapi:///"
    SLAPD_OPTIONSRed Hat default: SLAPD_OPTIONS=""

  • Also see the OpenLDAP.org Performance Tuning FAQ


Backup LDAP database:

Backup LDAP database with the following command:

OpenLDAP 2.x
  • Newer (Fedora, RHEL4/5 or Ubuntu 6.06/8) using "bdb":
        /usr/sbin/slapcat -v -n 1 -l  /opt/BACKUP/ldap.ldif
    
  • Older (Red Hat 9) using "ldbm":
        /usr/sbin/ldbmcat -n /var/lib/ldap/id2entry.gdbm > /opt/BACKUP/ldap.ldif
    
OpenLDAP 1.2
    /usr/sbin/ldbmcat -n /var/lib/ldap/id2entry.dbb > /opt/BACKUP/ldap.ldif

Note that this backup may not be suitable for re-loading. The order is random if it has been modified. The object definition for the domain itself must be the first definition. If it is not then move it there manually so that it can reload successfully.

Using LDAP slapd slapcat method: slapcat -v -n 2 -l delta.ldif

  • -v: Verbose mode.
  • -n 2: The second database definition listed in the /etc/openldap/slapd.conf file.
  • -l: Name of LDIF output file.
This method is no better or worse than using ldbmcat. The LDIF files generated by ldbmcat and slapcat are identical.

Also see: Scripts and software tools to convert LDIF files to the useful ".csv" backup form. - (Some helpful tools I wrote)


Adding an entry to an existing LDAP directory:

File: schemp.ldif

dn: cn=Schemp Anderson,ou=MemberGroupB,o=stooges
ou: MemberGroupB
o: stooges
cn: Schemp Anderson
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
givenName: Schemp
sn: Anderson
uid: schemp
homePostalAddress: 20 Cherry Ln.$Plano TX 78888
pager: 800-555-1320
title: Development Engineer
facsimileTelephoneNumber: 800-555-3320
mail: SAnderson@isp.com
homePhone: 800-555-1320
telephoneNumber: (800)555-1220
mobile: 800-555-1320
postalAddress: 20 Fitzhugh Ave.
l: Dallas
st: TX
postalCode: 76888

Command: ldapadd -f schemp.ldif -h 127.0.0.1 -xv -D "cn=StoogeAdmin,o=stooges" -W


Notes: LDAP on Ubuntu distribution:

  • [Potential Pitfall]: The Ubuntu/Debian security policy architecture is known as "apparmor". (by contrast, Red Hat uses "SELinux".) If creating a subdirectory for your LDAP database (i.e. slapd.conf configuration: directory /var/lib/ldap/stooges), you may get the following error in the system log file /var/log/syslog:
    /etc/ldap/slapd.conf: line XX: invalid path: Permission denied
        
    where "XX" is the line number of the error in the file /etc/ldap/slapd.conf.
    Change the Apparmor configuration to support subdirectories by editing the file: /etc/apparmor.d/usr.sbin.slapd
    Change from:
    ..
    ...
    
    # the databases and logs
    /var/lib/ldap/ r,
    /var/lib/ldap/* rw,
    
    ...
    ..
        

    To:
    ..
    ...
    
    # the databases and logs
    /var/lib/ldap/ r,
    /var/lib/ldap/** rwk,
    
    ...
    ..
        
    Restart Apparmor: /etc/init.d/apparmor restart


Notes: LDAP on Red Hat/Fedora distribution:

  • [Potential Pitfall]: Red Hat Enterprise 5/CentOS 5 upgrade to 2.3.43 a start or restart of an existing LDAP installation gives the following error:
    Checking configuration files for slapd: bdb_db_open: Warning - No DB_CONFIG file found in directory /var/lib/ldap/stooges: (2)
    Expect poor performance for suffix o=stooges.org
    config file testing succeeded
    Fix:
    cp /etc/openldap/DB_CONFIG.example /var/lib/ldap/stooges/DB_CONFIG
    chown ldap.ldap /var/lib/ldap/stooges/DB_CONFIG
    /etc/init.d/ldap restart
    /etc/init.d/ldap restart
        
    Yes restart twice. The first time will perform a database recovery. The second will start smoothly without protest.

    Manual DB recovery: /usr/sbin/slapd_db_recover -v -h /var/lib/ldap/stooges/

  • [Potential Pitfall]: Fedora Core 3 and later: (OpenLDAP 2.2.13 and later) Add the statement "allow bind_v2" after the schema "include" directives in the file /etc/openldap/slapd.conf if you wish to allow the use of older clients.

  • [Potential Pitfall]: Red Hat 9.0 introduced a database change from 7.3. I had to dump the database and reload.

  • [Potential Pitfall]: The OpenLDAP version shipped with Red Hat 9.0 introduced a change! When using the command "ldapadd" you MUST use the argument "-h 127.0.0.1" as it is no longer implied.

  • During investigation and development I would:
    • Shut down LDAP: /etc/init.d/ldap stop
    • Remove the old database: rm /var/lib/ldap/*
      DO NOT DO THIS WITH slapd RUNNING!!!!
      If you do, the system will hang so bad, you will not be able to kill the process or shutdown the system cleanly! (RH6.2 kernel 2.2.14-12)
    • Edit the /etc/openldap/slapd.conf and my ldif file
    • Restart LDAP: /etc/init.d/ldap start
    • Create and load new LDAP database: ldapadd -cv -D "cn=AdminManager, o=...
    • If you are supporting only one group or organization, you can specify a default base for client programs in /etc/openldap/ldap.conf: BASE dc=place-dc-here. This is stated in the literature but I did not check if this affected the slapd process.
    • Then I would test with Netscape Communicator or gq in browse mode.

OpenLDAP 1.2:


[Potential Pitfall]: PAM misconfiguration:

File (default): /etc/hosts.deny
   ALL:ALL
This set-up will deny everyone including localhost!!!
Remove this line which is often default.

Be sure to at least add the following to: /etc/hosts.allow

   ALL:127.0.0.1

[Potential Pitfall]: Ipchains/Iptables misconfiguration:

The Red Hat 7.1-9.0 and Fedora installations will have you configure firewall rules which may conflict with access to the LDAP server. To flush all firewall rules:
  iptables -F
OR
  ipchains -F

[Potential Pitfall]: LDAP won't start

Check log file /var/log/messages
slaptest: sql_select option missing
slaptest: auxpropfunc error no mechanism available
ldap:  succeeded
slapd[4200]: sql_select option missing
slapd[4200]: auxpropfunc error no mechanism available
If the config files /etc/openldap/ldap.conf or /etc/openldap/slapd.conf are owned by root it will cause this error.
Fix: chown ldap.ldap /etc/openldap/ldap.conf /etc/openldap/slapd.conf

[Potential Pitfall]: Directory access

The Red Hat 7.1-9.0 and Fedora versions of Open LDAP runs the LDAP server "slapd" under the user id "ldap". Thus all directories and files that the LDAP server must access must be accessible by the user "ldap". (preferably owned by user "ldap"). This is a configuration change between Red Hat 6.x, which used root, and Red Hat 7.1.

[Potential Pitfall]: Can't access LDAP server with client
Note for Fedora Core 3: (OpenLDAP 2.2.13) Add the statement "allow bind_v2" after the schema "include" directives in the file /etc/openldap/slapd.conf if you wish to allow the use of older clients.

Debugging tips: To take a peak inside the database:

   strings /var/lib/ldap/id2entry.gdbm | more


OpenLDAP Man Pages:

Open LDAP UNIX commands:

  • ldapmodify - connects to an LDAP server, binds, and modifies entries
  • ldapadd - connects to an LDAP server, binds, and adds entries
  • ldapdelete - Deletes an LDAP entry
  • ldapmodrdn - modifies the Relative Distinguished Name (RDN) of an entry (i.e. change cn of an entry)
  • ldappasswd - change the password of an LDAP entry
  • slappasswd - OpenLDAP password utility
  • ldapsearch - ldap search tool
  • ud - interactive LDAP Directory Server query program

Configuration files:

  • ldap.conf - slapd configuration file which set system wide defaults to be applied when running ldap clients
  • ldapfilter.conf - configuration file for LDAP get filter routines
  • ldapfriendly - data file for LDAP friendly routines
  • ldapsearchprefs.conf - configuration file for LDAP search preference routines
  • ldaptemplates.conf - configuration file for LDAP display template routines
  • ldif (5) - LDAP Data Interchange Format
  • slapd.conf - configuration file for slapd, the stand-alone LDAP daemon
  • slapd.replog - slapd replication log format
  • ud.conf - ud configuration file
  • centipede - an LDAP centroid generation and maintenance program

Support programs/conversions:

  • chlog2replog - convert an X.500 DSA-style changelog to an LDAP-style replication log
  • edb2ldif - QUIPU EDB file to LDIF conversion tool
  • fax500 - X.500 capable fax delivery agent
  • mail500 - X.500 capable mailer
  • rcpt500 - mail to X.500 gateway program and program replies with result of query.
  • go500 - Local Gopher index search to X.500 search gateway
  • go500gw - General Gopher to X.500 gateway for browsing and searching
  • in.xfingerd - Finger to LDAP/X.500 gateway daemon
  • ldbmcat - LDBM to LDIF database format conversion utility
  • ldif (8) - convert arbitrary data to LDIF format
  • ldif2id2children / ldif2id2entry / ldif2index / ldif2ldbm - LDIF to LDBM database format conversion utilities
  • slapindex - Regenerate SLAPD index to LDIF utility

LDAP processes/daemons:

LDAP Software development SDK man pages and RFC's


The Berkeley BDB database:

The back-bdb is now the new preferred database format and the old back-ldbm code has been removed from OpenLDAP.

The Berkeley database software tools have names which are Linux distribution dependant:

  • Red Hat Enterprise Linux 4: db41_archive, db41_checkpoint, db41_deadlock, db41_dump, db41_load, db41_printlog, db41_recover, db41_stat, db41_upgrade, db41_verify
    Part of compat-db-4.1.25-9 RPM package. (No man pages)
  • Ubuntu: db4.3_archive, db4.3_checkpoint, db4.3_deadlock, db4.3_dump, db4.3_load, db4.3_printlog, db4.3_recover, db4.3_stat, db4.3_upgrade, db4.3_verify
    Library installation: sudo apt-get install libdb4.4
    (Has man pages!)
    Also: db4.2_archive, db4.2_checkpoint, db4.2_deadlock, ...

Example database recovery:
  • Test database: /usr/sbin/slaptest -d 255
    bdb(o=megacorp.com): PANIC: fatal region error detected; run recovery
    bdb_db_open: dbenv_open failed: DB_RUNRECOVERY: Fatal error, run database recovery (-30978)
    backend_startup: bi_db_open failed! (-30978)
       
  • Recover database:
    • Go to the directory in which the database files are located: cd /var/lib/ldap
    • Run db recovery: db4.2_recover
      [Potential Pitfall]: If the db4.2_recover returns the following errors:
      db_recover: PANIC: fatal region error detected; run recovery
      db_recover: PANIC: fatal region error detected; run recovery
      db_recover: DB_ENV->open: DB_RUNRECOVERY: Fatal error, run database recovery
              
      try removing the log file(s) rm log.0000000001 and then try to perform the recovery again.

Links:


YoLinux.com LDAP Tutorials:


LDAP Links:

Public LDAP Servers on the Internet: Check out and try out other LDAP installations.

LDAP Desktop Admin tools and Clients:

LDAP Web Clients:

LDAP Clients: (authentication)

OpenLDAP.org web site:

LDAP - Information links:

Netscape Roaming:

LDAP - Schema links:

Also see RFC 2256 (User Schema for use with LDAPv3).

LDAP - Developer resources:

LDAP - Commercial Products:


LDAP Book ListBooks:

Understanding And Deploying LDAP Directory Services "Understanding And Deploying LDAP Directory Services",
by Timothy A. Howes,Phd, Mark C. Smith and Gordon S. Good,
ISBN 0672323168, Addison-Wesley Pub Co

Second edition. It is general in nature but complete in that it covers all concepts in depth. It is a good book for those wanting to understand everything about LDAP, schema development and its' capabilities.

Amazon.com
Understanding And Deploying LDAP Directory Services "Understanding And Deploying LDAP Directory Services",
by Timothy A. Howes,Phd, Mark C. Smith and Gordon S. Good,
ISBN 1-57870-070-1, MacMillan Technical Publishing

First edition out of print. (Used only) See second edition above. This is the largest LDAP book I own. It is general in nature but complete in that it covers all concepts in depth. It is NOT a good programmers reference but it is good for those wanting to understand everything about LDAP, schema development and its' capabilities. Netscape centric.

Amazon.com
Programming Directory-Enabled Applications with Lightweight Directory Access Protocol "Programming Directory-Enabled Applications with Lightweight Directory Access Protocol"
by Timothy A. Howes,Phd and Mark C. Smith
ISBN 1-57870-000-0, MacMillan Technical Publishing

Excellent programmers reference for those using the LDAP C language API. Also covers search filters and LDAP URL's. The OpenLDAP source code is so poorly commented that I found this book often was the only source for an explanation of what was happening in the code.

Amazon.com
Implementing LDAP "Implementing LDAP",
Mark Wilcok
ISBN 1-861002-21-1, WROK Press

This book covers all aspects of LDAP from LDIF to the LDAP SDK in C, PERL and JAVA. It has a strong Netscape Directory server bias.

Amazon.com
LDAP System Administration "LDAP System Administration",
Gerald Carter
ISBN 1565924916, O'Reilly & Associates

This book covers the use of OpenLDAP and the integration of services.

Amazon.com
LDAP Programming, Management and Integration "LDAP Programming, Management and Integration",
Clayton Donley
ISBN 1930110405, Manning Publications; 1st edition

This book covers LDAP administration as well as introductory information. It covers the directory services markup language (DSML), PERL LDAP module as well as JAVA JNDI.

Amazon.com
book image "Understanding LDAP - Design and Implementation" - IBM-Redbooks
Heinz Johner, Larry Brown, Franz-Stefan Hinner, Wolfgang Reis, Johan Westman
IBM Redbook #SG24-4986-00

A reference to ldap, available as PDF as well. This book has a bias towards IBM's E-network LDAP Directory server. Tight, terse, but covers everything.

IBM Redbook #SG24-6193-00 "LDAP Implementation and Practical Use"
IBM Redbook #SG24-6193-00

Copyright © 2000 - 2014 by Greg Ippolito