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.

• 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

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

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 favorite 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 favorite 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 organized in some way.

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 authorization services for nix clients. If you’re looking to use LDAP for another application, hopefully you’ve got to a point where a more generalized tutorial is able to help you.

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 authorization files
• inetorgperson.schema
  • Includes objects and attributes for representing contact information and organizational 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:

/var/chroot/openldap/etc/openldap/slapd.conf

  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

The sample configuration in /var/chroot/openldap/etc/openldap/slapd.conf is sane for using LDAP for authentication and authorization so this step simply involves un-commenting the following:

/var/chroot/openldap/etc/openldap/slapd.conf

  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

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

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.

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 $ Installing an OpenLDAP Server on a NetBSD VPS - traditional link (using RCS)