====== Installing an OpenLDAP Server on a NetBSD VPS ======

**Note: This tutorial assumes you’ve already followed the [[:vps_-_netbsd|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 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.

===== 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 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.**

===== 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 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:

<file config /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
</file>

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 authorization so this step simply involves un-commenting the following:

<file config /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
</file>
===== 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:

<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
</file>

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 $ [[http://sdf.org/?tutorials/VPS_NetBSD_OpenLDAP|Installing an OpenLDAP Server on a NetBSD VPS]] - traditional link (using [[wp>Revision_Control_System|RCS]])