== OpenLDAP Practical, Week 5 ==

This practical is about installing and configuring an OpenLDAP LDAP server on
our virtual machine. We want to setup it from source and link it with Berkeley
DB backend.

At the end of the practical, we should have a working LDAP
directory reflecting more or less what we could have in the LDAP server of the
university.

=== Problem 1: Unsupported version of Java VM ===

When running the './configure' command for the first time, it fails with

    > checking if java works... configure: error: The Java VM java failed (see config.log, check the CLASSPATH?)

After having a look inside 'config.log', we find this error:

    > java.lang.UnsupportedClassVersionError unsupported major.minor version 51.0

==== Resolution ====

This exception ('unsupported major.minor version xx.y') arises when there is a
version mismatch between the Java compiler and Virtual Machine. We verifiy this
assertion by issuing the following commands and checking their output:

    $ javac -version; java -version
    > javac 1.7.0_65
    > java version "1.6.0_33"

The output confirms that something is messed up so we fix this error by
removing the package 'openjdk-6-jre-headless' which was installed for some
reason.

=== Problem 2: schema files are read-only ===

When willing to modify 'etc/openldap/schema/core.schema', it turns out that the
file is actually read-only.

==== Resolution ====

It is actually not advisable to directly modify the default schema files
present in 'etc/openldap/schema/'. Installing them read-only is a way to tell
the user not to modify them because they are likely to be overriden by an
automatic process (especially by running 'make install' again).

In our case, instead of modifying 'schema/core.schema', we will extend our
schema by creating a 'schema/local.schema' file and write our additional schema
inside.

Last but not least, we have to instruct 'slapd' to include this file by adding
this line in 'slapd.conf' (after replacing '<PREFIX>' with slapd's
configuration directory).

    include <PREFIX>/schema/local.schema

=== Problem 3: writing the proper command line to add the DIT ===

Since we prefer using command line interfaces, we will use 'ldapadd' instead of
'Jxplorer' to create our DIT. Thus we have to understand how to use 'ldapadd'
properly.

==== Resolution ====

After having a glance at the manual page 'ldapadd (1)', we find out that:

- the option '-W' tells 'ldapadd' to prompt for our password but we can also
  supply it directly using '-w'.
- the option '-D' allows us to pass the Distinguished Name
- the option '-f' allows us to pass a LDIF file

Thus, our command line can look something like:

    $ ldapadd -w secret -D 'cn=Manager,c=gb' -f file.ldif

=== Problem 4: writing the LDIF file ===

To construct our DIT, we need to write its description in the LDIF file that we
will pass to 'ldapadd'. The reason why the practical advise us to create the
DIT using a LDAP browser is certainly because writing a LDIF file is rather
tricky the first time.

==== Resolution ====

Though the manpage of 'ldapadd' gives us a basic example of LDIF file for
adding an entry, it is rather insufficient.

The documentation of OpenLDAP, especially the section _LDIF text entry format_
available at the link below gives us more information, including an example
with children and parent nodes.

http://www.openldap.org/doc/admin24/dbtools.html#The%20LDIF%20text%20entry%20format

After a few tries with different syntaxes, we finally get this error:

    ldap_add: Invalid syntax (21)
    additional info: objectClass: value #0 invalid per syntax

Here, the 'objectClass' refered to is 'organisation'. The problem is that it is
misspelled in the practical. The real class is actually 'organization' as
stated here:

http://www.zytrax.com/books/ldap/ape/

At this point, our LDIF file looks something like:

    dn: o=University of Kent,c=gb
    objectClass: organization

    dn: ou=MSc ISB,o=University of Kent,c=gb
    objectClass: organizationalUnit

    dn: cn=Olivier Gayot,ou=MSc ISB,o=University of Kent,c=gb
    objectClass: organizationalPerson
    objectClass: pkiUser
    objectClass: pmiUser

After trying to add it using 'ldapadd', the LDAP server sends us this error:

    adding new entry "cn=Olivier Gayot,ou=MSc ISB,o=KENT,c=gb"
    ldap_add: Object class violation (65)
        additional info: object class 'organizationalPerson' requires attribute 'sn'

What we understand here is that we need to add an extra attribute 'sn'. To
figure out what it actually means, we can have a look in the file
'schema/core.schema', especially this section:

    attributetype ( 2.5.4.4 NAME ( 'sn' 'surname' )
        DESC 'RFC2256: last (family) name(s) for which the entity is known by'
        SUP name )

With that information, we can edit our LDIF file and supply our new attribute:

    dn: o=University of Kent,c=gb
    objectClass: organization

    dn: ou=MSc ISB,o=University of Kent,c=gb
    objectClass: organizationalUnit

    dn: cn=Olivier Gayot,ou=MSc ISB,o=University of Kent,c=gb
    objectClass: organizationalPerson
    objectClass: pkiUser
    objectClass: pmiUser
    sn: Gayot

By using the command line below, our DIT is successfully created (the option
'-c' is used here because, without it, 'ldapadd' stops because our parent nodes
have already been created)

    $ ldapadd -w secret -D 'cn=Manager,c=gb' -f file.ldif -c