dc724d5
LDAP Support in DHCP
dc724d5
Brian Masney <masneyb@ntelos.net>
dc724d5
Last updated 3/23/2003
dc724d5
dc724d5
This document describes setting up the DHCP server to read it's configuration
dc724d5
from LDAP.  This work is based on the IETF document
dc724d5
draft-ietf-dhc-ldap-schema-01.txt included in the doc directory.  For the
dc724d5
latest version of this document, please see http://home.ntelos.net/~masneyb.
dc724d5
dc724d5
First question on most people's mind is "Why do I want to store my
dc724d5
configuration in LDAP?"  If you run a small DHCP server, and the configuration
dc724d5
on it rarely changes, then you won't need to store your configuration in LDAP.
dc724d5
But, if you have several DHCP servers, and you want an easy way to manage your
dc724d5
configuration, this can be a solution.
dc724d5
dc724d5
The first step will be to setup your LDAP server.  I am using OpenLDAP from
dc724d5
www.openldap.org.  Building and installing OpenLDAP is beyond the scope of
dc724d5
this document.  There is plenty of documentation out there about this.  Once
dc724d5
you have OpenLDAP installed, you will have to edit your slapd.conf file.  I
dc724d5
added the following 2 lines to my configuration file:
dc724d5
dc724d5
include         /etc/ldap/schema/dhcp.schema
dc724d5
index           dhcpHWAddress eq
dc724d5
index           dhcpClassData eq
dc724d5
dc724d5
The first line tells it to include the dhcp schema file.  You will find this
dc724d5
file under the contrib directory in this distribution.  You will need to copy
dc724d5
this file to where your other schema files are (maybe
dc724d5
/usr/local/openldap/etc/openldap/schema/).  The second line sets up an index
dc724d5
for the dhcpHWAddress parameter.  The third parameter is for reading subclasses
dc724d5
from LDAP every time a DHCP request comes in. Make sure you run the slapindex
dc724d5
command and restart slapd to have these changes to into effect.
dc724d5
dc724d5
Now that you have LDAP setup, you should be able to use gq
dc724d5
(http://biot.com/gq/) to verify that the dhcp schema file is loaded into LDAP.
dc724d5
Pull up gq, and click on the Schema tab.  Go under objectClasses, and you
dc724d5
should see at least the following object classes listed: dhcpClass, dhcpGroup,
dc724d5
dhcpHost, dhcpOptions, dhcpPool, dhcpServer, dhcpService, dhcpSharedNetwork,
dc724d5
dhcpSubClass, and dhcpSubnet.  If you do not see these, you need to check over
dc724d5
your LDAP configuration before you go any further.
dc724d5
dc724d5
You should now be ready to build DHCP.  If you would like to enable LDAP over
dc724d5
SSL, you will need to perform the following steps:
dc724d5
dc724d5
  * Edit the includes/site.h file and uncomment the USE_SSL line
dc724d5
    or specify "-DUSE_SSL" via CFLAGS.
dc724d5
  * Edit the dst/Makefile.dist file and remove md5_dgst.c and md5_dgst.o
dc724d5
    from the SRC= and OBJ= lines (around line 24)
dc724d5
  * Now run configure in the base source directory. If you chose to enable
dc724d5
    LDAP over SSL, you must append -lcrypto -lssl to the LIBS= line in the
dc724d5
    file work.os/server/Makefile (replace os with your operating system,
dc724d5
    linux-2.2 on my machine).  You should now be able to type make to build
dc724d5
    your DHCP server.
dc724d5
dc724d5
If you choose to not enable LDAP over SSL, then you only need to run configure
dc724d5
and make in the toplevel source directory.
dc724d5
dc724d5
Once you have DHCP installed, you will need to setup your initial plaintext
dc724d5
config file. In my /etc/dhcpd.conf file, I have:
dc724d5
dc724d5
ldap-server "localhost";
dc724d5
ldap-port 389;
dc724d5
ldap-username "cn=DHCP User, dc=ntelos, dc=net";
dc724d5
ldap-password "blah";
dc724d5
ldap-base-dn "dc=ntelos, dc=net";
dc724d5
ldap-method dynamic;
dc724d5
ldap-debug-file "/var/log/dhcp-ldap-startup.log";
dc724d5
dc724d5
If SSL has been enabled at compile time using the USE_SSL flag, the dhcp
dc724d5
server trys to use TLS if possible, but continues without TLS if not.
dc724d5
dc724d5
You can modify this behaviour using following option in /etc/dhcpd.conf:
dc724d5
dc724d5
ldap-ssl <off | ldaps | start_tls | on>
dc724d5
   off:       disables TLS/LDAPS.
dc724d5
   ldaps:     enables LDAPS -- don't forget to set ldap-port to 636.
dc724d5
   start_tls: enables TLS using START_TLS command
dc724d5
   on:        enables LDAPS if ldap-port is set to 636 or TLS in 
dc724d5
              other cases.
dc724d5
dc724d5
See also "man 5 ldap.conf" for description the following TLS related 
dc724d5
options:
dc724d5
   ldap-tls-reqcert, ldap-tls-ca-file, ldap-tls-ca-dir, ldap-tls-cert
dc724d5
   ldap-tls-key, ldap-tls-crlcheck, ldap-tls-ciphers, ldap-tls-randfile
dc724d5
dc724d5
All of these parameters should be self explanatory except for the ldap-method.
dc724d5
You can set this to static or dynamic.  If you set it to static, the
dc724d5
configuration is read once on startup, and LDAP isn't used anymore.  But, if
dc724d5
you set this to dynamic, the configuration is read once on startup, and the
dc724d5
hosts that are stored in LDAP are looked up every time a DHCP request comes
dc724d5
in.
dc724d5
dc724d5
When the optional statement ldap-debug-file is specified, on startup the DHCP
dc724d5
server will write out the configuration that it generated from LDAP.  If you
dc724d5
are getting errors about your LDAP configuration, this is a good place to
dc724d5
start looking.
dc724d5
dc724d5
The next step is to set up your LDAP tree. Here is an example config that will
dc724d5
give a 10.100.0.x address to machines that have a host entry in LDAP.
dc724d5
Otherwise, it will give a 10.200.0.x address to them.  (NOTE: replace
dc724d5
dc=ntelos, dc=net with your base dn). If you would like to convert your
dc724d5
existing dhcpd.conf file to LDIF format, there is a script
dc724d5
contrib/dhcpd-conf-to-ldap.pl that will convert it for you.  Type
dc724d5
dhcpd-conf-to-ldap.pl --help to see the usage information for this script.
dc724d5
dc724d5
# You must specify the server's host name in LDAP that you are going to run
dc724d5
# DHCP on and point it to which config tree you want to use.  Whenever DHCP
dc724d5
# first starts up, it will do a search for this entry to find out which
dc724d5
# config to use
dc724d5
dn: cn=brian.ntelos.net, dc=ntelos, dc=net
dc724d5
objectClass: top
dc724d5
objectClass: dhcpServer
dc724d5
cn: brian.ntelos.net
dc724d5
dhcpServiceDN: cn=DHCP Service Config, dc=ntelos, dc=net
dc724d5
dc724d5
# Here is the config tree that brian.ntelos.net points to.
dc724d5
dn: cn=DHCP Service Config, dc=ntelos, dc=net
dc724d5
cn: DHCP Service Config
dc724d5
objectClass: top
dc724d5
objectClass: dhcpService
dc724d5
dhcpPrimaryDN: dc=ntelos, dc=net
dc724d5
dhcpStatements: ddns-update-style none
dc724d5
dhcpStatements: default-lease-time 600
dc724d5
dhcpStatements: max-lease-time 7200
dc724d5
dc724d5
# Set up a shared network segment
dc724d5
dn: cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net
dc724d5
cn: WV
dc724d5
objectClass: top
dc724d5
objectClass: dhcpSharedNetwork
dc724d5
dc724d5
# Set up a subnet declaration with a pool statement.  Also note that we have
dc724d5
# a dhcpOptions object with this entry
dc724d5
dn: cn=10.100.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net
dc724d5
cn: 10.100.0.0
dc724d5
objectClass: top
dc724d5
objectClass: dhcpSubnet
dc724d5
objectClass: dhcpOptions
dc724d5
dhcpOption: domain-name-servers 10.100.0.2
dc724d5
dhcpOption: routers 10.100.0.1
dc724d5
dhcpOption: subnet-mask 255.255.255.0
dc724d5
dhcpOption: broadcast-address 10.100.0.255
dc724d5
dhcpNetMask: 24
dc724d5
dc724d5
# Set up a pool for this subnet.  Only known hosts will get these IPs
dc724d5
dn: cn=Known Pool, cn=10.100.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net
dc724d5
cn: Known Pool
dc724d5
objectClass: top
dc724d5
objectClass: dhcpPool
dc724d5
dhcpRange: 10.100.0.3 10.100.0.254
dc724d5
dhcpPermitList: deny unknown-clients
dc724d5
dc724d5
# Set up another subnet declaration with a pool statement
dc724d5
dn: cn=10.200.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net
dc724d5
cn: 10.200.0.0
dc724d5
objectClass: top
dc724d5
objectClass: dhcpSubnet
dc724d5
objectClass: dhcpOptions
dc724d5
dhcpOption: domain-name-servers 10.200.0.2
dc724d5
dhcpOption: routers 10.200.0.1
dc724d5
dhcpOption: subnet-mask 255.255.255.0
dc724d5
dhcpOption: broadcast-address 10.200.0.255
dc724d5
dhcpNetMask: 24
dc724d5
dc724d5
# Set up a pool for this subnet. Only unknown hosts will get these IPs
dc724d5
dn: cn=Known Pool, cn=10.200.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net
dc724d5
cn: Known Pool
dc724d5
objectClass: top
dc724d5
objectClass: dhcpPool
dc724d5
dhcpRange: 10.200.0.3 10.200.0.254
dc724d5
dhcpPermitList: deny known clients
dc724d5
dc724d5
# Set aside a group for all of our known MAC addresses
dc724d5
dn: cn=Customers, cn=DHCP Service Config, dc=ntelos, dc=net
dc724d5
objectClass: top
dc724d5
objectClass: dhcpGroup
dc724d5
cn: Customers
dc724d5
dc724d5
# Host entry for my laptop
dc724d5
dn: cn=brianlaptop, cn=Customers, cn=DHCP Service Config, dc=ntelos, dc=net
dc724d5
objectClass: top
dc724d5
objectClass: dhcpHost
dc724d5
cn: brianlaptop
dc724d5
dhcpHWAddress: ethernet 00:00:00:00:00:00
dc724d5
dc724d5
You can use the command slapadd to load all of these entries into your LDAP 
dc724d5
server. After you load this, you should be able to start up DHCP. If you run
dc724d5
into problems reading the configuration, try running dhcpd with the -d flag. 
dc724d5
If you still have problems, edit the site.conf file in the DHCP source and
dc724d5
add the line: COPTS= -DDEBUG_LDAP and recompile DHCP. (make sure you run make 
dc724d5
clean and rerun configure before you rebuild).
dc724d5