[[PageOutline(2-5,Contents,pullout)]]

= Testing LDAP extensions

This page gives some guidelines on testing the LdapPlugin extension, and provides some examples about deploying [http://www.openldap.org OpenLDAP] to perform the [browser:ldapplugin/0.11/ldapplugin/tests tests].

== Prerequistes

The examples in this page assume that you are working with a Linux server (Debian), with OpenLDAP 2.2 or greater.

The `slapd` server should be installed and you should also have access to the Ldap utils, which usually come with a separate package:
 * server tools: `slapadd`, `slapcat`
 * client tools: `ldapsearch`, `ldapadd`, `ldapmodify`, `ldapdelete`

All the commands are run using the superuser (root) account.

== Create the directory config file

The following config file is somewhat more complex than it could be, as it uses ACL, etc. However this is a good base to elaborate a more complex LDAP setup and which is the file I used to test the extension.

{{{
# BDB backend in this example
database        bdb

# Maximum entries returned in a search
sizelimit       100

# Log connections, operations, results
# Do not forget to reduce the debug level once everything is up and running !
loglevel        768

suffix          "dc=example,dc=org"
rootdn          "uid=root,dc=example,dc=org"

# Cleartext password: Trac
rootpw          {SSHA}yGq6aHM4w3Hf94hl4j+1rgO3HSGmmbVq
lastmod         on

# Path to the database files
directory       /var/local/db/tracldap

# 1.3.6.1.4.1.15527 is reserved. Do not hijack it
# Please see http://www.iana.org/cgi-bin/enterprise.pl

# Attribute type definitions
attributetype ( 1.3.6.1.4.1.15527.143
                NAME 'tracperm'
                DESC 'Trac Permission'
                EQUALITY caseIgnoreMatch
                SUBSTR caseIgnoreSubstringsMatch
                SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32} )

# Class definitions
objectclass ( 1.3.6.1.4.1.15527.8
              NAME 'tracuser'
              DESC 'Regular user with Trac permission'
              SUP top
              STRUCTURAL
              MUST ( uid $ cn $ userpassword )
              MAY  ( tracperm $ sn $ description ) )
objectclass ( 1.3.6.1.4.1.15527.9
              NAME 'tracgroup'
              DESC 'Trac permission for groupofnames'
              SUP top
              AUXILIARY
              MAY  ( tracperm ) )

# ACLs (warning: give read access to anonymous LDAP connection)
access to dn.base="" by * read
access to dn.base="cn=subschema" by * read
access to filter=(|(objectclass=groupOfNames)(objectclass=tracuser)) dn.one="dc=example,dc=org"
       by group="cn=managers,dc=example,dc=org" write
       by * read
access to attrs=tracperm
       by group="cn=managers,dc=example,dc=org" write
       by self read
       by users read
       by anonymous read
access to attrs=entry dn.subtree="dc=example,dc=org"
       by * read

# Search indexing
index  objectClass,uid eq
index  cn,sn           eq,sub,pres,approx
index  member          eq

}}}

You should include this file from the main OpenLDAP configuration file, usually located here: `/etc/ldap/slapd.conf`. You need to include these definitions at the bottom of the file.

== Configure your system logger

OpenLDAP errors can be cryptic. You can find useful information however in the log produced by the server.

It is useful to compare requests made by standard utilities such as `ldapsearch` and the requests made by the extension: if an ldapsearch request fails, blame your server configuration (or your directory content) not the Trac Ldap Extension.

 1. Add the following entry in `/etc/syslog.conf`:
{{{
# Log OpenLDAP
local4.*                       -/var/log/openldap.all
}}}
 1. Reload the syslog configuration:
{{{
/etc/init.d/sysklogd reload
}}}
 1. You probably want to open a console and keep dumping the log messages:
{{{
tail -f /var/log/openldap.all
}}}

== Start up the LDAP server

 1. Create the directory where the LDAP directory files will reside:
{{{
mkdir /var/local/db/tracldap
}}}
 1. Start up the server:
{{{
/etc/init.d/slapd start
}}}

You should not get any error. If you get an error message (carefully check the log file), please fix up your LDAP configuration before resuming installation.

If everything is ok, shut down the server, because we need to initialize the LDAP directory before continuing.

== Initializing the directory

We need to create the top-most entry (the local root) of the LDAP hierarchical directory.

 1. Copy the following LDIF data in a file, `init.ldif` for example:
{{{
dn: dc=example,dc=org
dc: example
o: Trac
description: Test directory for Trac
objectClass: dcObject
objectClass: organization
}}}
 1. Then inject this LDIF data into the LDAP directory using the server tool, and the server should be down at this moment:
{{{
/usr/sbin/slapadd -b "dc=example,dc=org" -l init.ldif
}}}
 1. Restart the LDAP server:
{{{
/etc/init.d/slapd start
}}}

Now that the server is up and running, we can inject the initial directory entries that are expected by the extension unit tests.

 1. Copy the following LDIF data in another file, `dirtest.ldif`:
{{{
# Group definition
# Managers is a group that has permission to add and revoke Trac permissions
dn: cn=managers,dc=example,dc=org
cn: managers
objectClass: groupOfNames
objectClass: tracgroup
member: uid=trac,dc=example,dc=org

# Group definition
# Users is a group of regular users
dn: cn=users,dc=example,dc=org
cn: users
objectClass: groupOfNames
objectClass: tracgroup
member: uid=joeuser,dc=example,dc=org

# User definition
# Trac is the 'software user' that manages the Trac permissions
dn: uid=trac,dc=example,dc=org
uid: trac
cn: Trac Manager
userPassword: Trac
objectClass: tracuser

# Special 'user': anonymous
# joker entry for non authenticated access
dn: uid=anonymous,dc=example,dc=org
uid: anonymous
cn: Trac Anonymous
sn: Anonymous
userPassword: no_use
objectClass: tracuser

# Special 'user': authenticated
# joker entry for any authenticated access
dn: uid=authenticated,dc=example,dc=org
uid: authenticated
cn: Trac Authenticated
sn: Authenticated
userPassword: no_use
objectClass: tracuser

# User definition
# Joe User is just a regular user
dn: uid=joeuser,dc=example,dc=org
uid: joeuser
cn: Joe User
sn: User
userPassword: anypasswd
objectClass: tracuser
}}}
 1. Add those entries to the directory using the client tool. This won't work if the LDAP server is down:
{{{
ldapadd -D "uid=root,dc=example,dc=org" -x -W -f direst.ldif
}}}
You'll be prompted for the user password, ie the password for user `uid=root`. This password is defined in the LDAP directory config file, here `Trac`.

Now you should be able to fully use the directory:
 1. Search entries using an anonymous bind:
{{{
ldapsearch -b "dc=example,dc=org" -x objectclass=*
}}}

 1. Search entries using an authenticated bind (password for Trac is `Trac` too):
{{{
ldapsearch -b "dc=example,dc=org" -D "uid=trac,dc=example,dc=org" -x -W objectclass=*
}}}

 1. You can also add new entries and remove them if you like. However, the Ldap Extension unit tests expect the directory to be set up as described above.

== Clean up

If the test fails or some part of the installation procedure fails, you want to clean up the LDAP directory to restart from a clean environment.

 1. Shut down the OpenLDAP server:
{{{
/etc/init.d/slapd stop
}}}
 1. Remove the LDAP database files:
{{{
rm /var/local/db/tracldap/*
}}}
 1. Reinitialize the directory, see above.

== Troubleshooting

OpenLDAP server is sensitive to its configuration settings, so double check your configuration files and your LDIF files if you encounter errors in the early setup stage.

=== Common errors

 * `slapadd: could not parse entry (line=n)`, which usually means that your initial LDIF file is malformed: 
   * DOS vs. UNIX line ending mismatch.
   * Trailing space.

 * `ldapsearch` returns no result:
   1. Ensure that your base tree match the one defined in the LDIF file.
   1. Try disabling the ACL, comment the rules and restart the `slapd` server.