# Installing an OpenLDAP Server on a NetBSD VPS

Note: This tutorial assumes you’ve already followed the NetBSD on SDF VPS tutorial to set up networking, the time zone and pkgsrc using the SDF VPS pkgsrc.

An LDAP server can be used for an endless number of things. Essentially, LDAP is just an object-oriented hierarchical database. Common uses include authentication and authorisation, host management, a backend for Kerberos, a backend for a DHCP server, a shared address book and forming a part of some public key infrastructures.

In this tutorial, I will be setting up the LDAP server to provide authorisation and authentication for a nix client, but the first few stages are the same for almost any application of LDAP.

The OpenLDAP server is available in the SDF VPS pkgsrc and so the software is already installed, but does require some configuration.

## Jargon and Tools

OpenLDAP
  The LDAP server that will be used
Suffix
  The suffix appended to all LDAP objects, which normally related to a domain name
Root DN
  The administrative user of the server, with read and write access to all data objects. The password for this user should be kept secure
`slapd`
  The name of the executable of the OpenLDAP server
`slappasswd`
  The name of the executable tool used for creating password hashes
`pwd_mkdb`
  The name of the executable tool that generates the password databases

## Initial Setup

To begin with, we’ll create the chroot environment. Whilst the OpenLDAP server is running, this is the only part of the file system it will be able to see.

The first step is to create the directories and copy the initial configuration that comes from pkgsrc.

    # mkdir /var/chroot/openldap
    # mkdir /var/chroot/openldap/etc /var/chroot/openldap/var
    # cp -r /usr/pkg/etc_example/openldap /var/chroot/openldap/etc/
    # cp -r /usr/pkg/var/openldap /var/chroot/openldap/var/

The next step is to create the user and group that the server will run as, and allow for this information to be available in the chroot.

    # groupadd -g 17 slapd
    # useradd -u 17 -g 17 -d /var/chroot/openldap slapd
    # grep slapd /etc/master.passwd > /var/chroot/openldap/etc/master.passwd
    # pwd_mkdb -d /var/chroot/openldap /var/chroot/openldap/etc/master.passwd
    # grep slapd /etc/group > /var/chroot/openldap/etc/group

No password needs to be set for the slapd user as no one will ever log in using its username. This disallows logins from that user.

Finally, we’ll need to set the correct permissions necessary for OpenLDAP to access its data while keeping it secure.

    # chown -R slapd:slapd /var/chroot/openldap
    # chmod -R 700 /var/chroot/openldap/var/openldap/openldap-data

## Initial Configuration

The next stage involves editing some configuration files so that paths are correct within the chroot and the chroot is enabled with the correct user and group.

This step also includes setting the password for the root DN (Distinguished Name), the LDAP administrative user.

Begin by creating a hash of the password you wish to use for the root DN. This should be a secure password, as the root DN can read and write to the database, regardless of any access restrictions that we set up later on. The slappasswd tool is used to do this.

    # slappasswd -s 'reallysecurepassword'
    {SSHA}1LuiLGmSO+EoPA0uk80v4TC5xwacBOWg

Note: The `-s` flag passed here tells `slappasswd` that we want to pass the secret on the command line. If you execute `slappasswd` without any arguments, it will prompt for the password on the terminal allowing you to avoid having the password show up in any logs or in the running process list.

You should copy the whole line to your clipboard as we will need it shortly. Then open up `/var/chroot/openldap/etc/openldap/slapd.conf` in your favourite editor.

The first three lines that need changing are near the top of the file. They start with include, pidfile and argsfile and have a path to a file following them. These paths point to the read-only filesystem of the SDF VPS pkgsrc and not our chroot, so they should be changed like so:

    include         /etc/openldap/schema/core.schema
    [...SNIPPED...]
    pidfile         /var/openldap/run/slapd.pid
    argsfile        /var/openldap/run/slapd.args

Next, we’ll need to set the suffix, the root DN, and the password for the root DN. The suffix is normally formed from your domain name. In this example, the domain name is shiftout.org, and so the suffix should be `dc=shiftout,dc=org`. The suffix should then be copied onto the end of the root DN, so in this example, it becomes: `cn=manager,dc=shiftout,dc=org`. For the root DN’s password, replace `secret` with the string you copied to your clipboard earlier.

    suffix          "dc=shiftout,dc=org"
    rootdn          "cn=manager,dc=shiftout,dc=org"
    [...SNIPPED...]
    rootpw          {SSHA}1LuiLGmSO+EoPA0uk80v4TC5xwacBOWg

Then there is one final path to modify. This is the directory that OpenLDAP uses for storing its data. Currently, it is set to point at the read-only SDF VPS pkgsrc, so this needs to be changed.

    directory       /var/openldap/openldap-data

The final step before running the server for the first time is to configure the rc scripts. These allow for the server to be started on boot.

First, copy the example rc script for slapd into the `/etc/rc.d` directory.

    # cp /usr/pkg/share/examples/rc.d/slapd /etc/rc.d/

Then edit the new file `/etc/rc.d/slapd` with your favourite editor.

There are two lines you need to edit here. The line defining where to find `slapd` is fine as the read-only filesystem is fine for executing programs from, it’s only the configuration and data store we needed to move.

The first line that needs to be edited is the location of the configuration file, which should look like this:

    required_files="/var/chroot/openldap/etc/openldap/${name}.conf"

The second line is the command line arguments that are passed to `slapd` when it is started. This should look like:

    command_args="-u slapd -g slapd -r /var/chroot/openldap/ -f /etc/openldap/slapd.conf"

The `-u` and `-g` flags are used to specify the user and group that `slapd` should be running as. The `-r` flag tells slapd where to chroot, and the `-f` flag tells slapd where to find the configuration file. All configuration files are read after the chroot has happened, which is why the path does not include `/var/chroot/openldap` in it.

Finally, it is necessary to enable `slapd` in the `rc.conf` file.

    # echo "slapd=YES" >> /etc/rc.conf

You can edit the file manually and add this line if you would like to keep your `rc.conf` organised in some way.

## Testing

Before starting `slapd` as a daemon, it would be wise to first test that it is working fine using debug mode. The following command will start slapd in debug mode with the command line arguments we specified in `slapd`’s rc file. 255 represents the debug level.

    # /usr/pkg/libexec/slapd -u slapd -g slapd -r /var/chroot/openldap/ -f /etc/openldap/slapd.conf -d 255

If you see something similar to:

    502c06bd slapd starting
    502c06bd daemon: added 4r listener=0x0
    502c06bd daemon: added 6r listener=0x7f7ffc427180
    502c06bd daemon: added 7r listener=0x7f7ffc427240
    502c06bd daemon: select: listen=6 active_threads=0 tvp=NULL
    502c06bd daemon: select: listen=7 active_threads=0 tvp=NULL
    502c06bd daemon: activity on 1 descriptor
    502c06bd daemon: waked
    502c06bd daemon: select: listen=6 active_threads=0 tvp=NULL
    502c06bd daemon: select: listen=7 active_threads=0 tvp=NULL

Then you have succeeded in configuring an OpenLDAP to a point where it will start successfully. Press Ctrl+C to stop the server. You can start or stop the server as a daemon using `/etc/rc.d/slapd {start,stop}` just like you would with other daemons on NetBSD.

Note: From this point, configuration will become specific to providing authentication and authorisation services for nix clients. If you’re looking to use LDAP for another application, hopefully you’ve got to a point where a more generalised tutorial is able to help you.

## Including extra schemata

Three schemata will need to be used by `slapd` to enable you to store objects representing users and groups.

`cosine.schema`
  Includes “generally useful” objects and attributes (sic)
`nis.schema`
  Includes objects and attributes for use in representing fields from BSD-style flat file authentication and authorisation files
`inetorgperson.schema`
  Includes objects and attributes for representing contact information and organisational information

These files are included by adding the following three lines underneath the first include we changed earlier in the `/var/chroot/openldap/etc/openldap/slapd.conf` file:

    include         /etc/openldap/schema/cosine.schema
    include         /etc/openldap/schema/nis.schema
    include         /etc/openldap/schema/inetorgperson.schema

At the end of this file, we’ll also add another index. Searching on non-indexed fields can result in no results being returned, so this is important.

    index           uid         eq

## Configuring ACLs

The sample configuration in `/var/chroot/openldap/etc/openldap/slapd.conf` is sane for using LDAP for authentication and authorisation so this step simply involves uncommenting the following:

    access to dn.base="" by * read
    access to dn.base="cn=Subschema" by * read
    access to *
            by self write
            by users read
            by anonymous auth

## A second test

To ensure that no errors have been made while configuring, it would be a good idea now to run `slapd` again with the debug option. Any errors will be apparent in the output if they have occurred.

    # /usr/pkg/libexec/slapd -u slapd -g slapd -r /var/chroot/openldap/ -f /etc/openldap/slapd.conf -d 255

## Importing data

Assuming you’ve got this far with no problems, it’s time to import some data. The data used for interactions with an OpenLDAP server is stored in a text file in LDIF (LDAP Data Interchange Format). Once we have performed this initial import, further interactions can be performed through graphical clients.

Copy the following example into a text file:

    # Create top-level object in domain
    dn: dc=shiftout,dc=org
    objectClass: top
    objectClass: dcObject
    objectclass: organization
    o: shiftOut
    dc: shiftOut
    description: shiftOut

    dn: ou=people,dc=shiftout,dc=org
    objectClass: organizationalUnit
    ou: people

    dn: ou=groups,dc=shiftout,dc=org
    objectClass: organizationalUnit
    ou: groups

    dn: uid=irl,ou=people,dc=shiftout,dc=org
    objectClass: inetOrgPerson
    objectClass: posixAccount
    objectClass: shadowAccount
    uid: irl
    sn: Learmonth
    givenName: Iain
    cn: Iain Learmonth
    displayName: Iain R. Learmonth
    uidNumber: 2000
    gidNumber: 2000
    userPassword: password
    gecos: Iain R. Learmonth
    loginShell: /bin/bash
    homeDirectory: /home/irl
    shadowExpire: -1
    shadowFlag: 0
    shadowWarning: 7
    shadowMin: 8
    shadowMax: 999999
    shadowLastChange: 10877
    mail: irl@sdf.org
    homePhone: +1 (206) 299 2120 x1388
    title: System Administrator
    initials: IRL

    dn: cn=irl,ou=groups,dc=shiftout,dc=org
    objectClass: posixGroup
    cn: irl
    gidNumber: 2000

The following is used in this example:

- Suffix: dc=shiftout,dc=org
- Initial user: irl
- Organisation name: shiftOut

These three values will need to be changed. Hopefully you can also use common sense to identify names and contact information that will need to be changed.

Assuming you have saved your LDIF file as `/tmp/ldif`, run the following command to import it:

    ldapadd -D "cn=manager,dc=shiftout,dc=org" -Wx -f /tmp/ldif

You will need to replace the bind DN here with the correct root DN and suffix you specified earlier.

Note for experienced users: Tools such as `slapadd`, `slapcat`, etc. work directly on the OpenLDAP database files. As the path for this is set in a configuration file that assumes it’s being used in the chroot, they will not work. Experienced users may decide to setup another `slapd.conf` file for use outside the chroot, but the `ldapadd`, `ldapsearch`, etc. tools work just as well while the server is running.

You can check the import was successful by running:

    ldapwhoami -D "uid=irl,ou=people,dc=shiftout,dc=org" -Wx

Replace the uid and suffix with the ones that you have created. You should see an output similar to:

    dn:uid=irl,ou=people,dc=shiftout,dc=org

If you see this, you have correctly configured a working LDAP server, to which you can add, query, modify, and remove data representing users and groups.

## Graphical Client

Apache Directory Studio provides a graphical browser that you can use to add, query, modify and remove data from your LDAP database. It can be downloaded from http://directory.apache.org/studio/.

$Id: VPS_NetBSD_OpenLDAP.html,v 1.5 2012/08/16 00:47:07 irl Exp $