2 Brian Masney <masneyb@ntelos.net>
5 This document describes setting up the DHCP server to read it's configuration
6 from LDAP. This work is based on the IETF document
7 draft-ietf-dhc-ldap-schema-01.txt included in the doc directory. For the
8 latest version of this document, please see http://home.ntelos.net/~masneyb.
10 First question on most people's mind is "Why do I want to store my
11 configuration in LDAP?" If you run a small DHCP server, and the configuration
12 on it rarely changes, then you won't need to store your configuration in LDAP.
13 But, if you have several DHCP servers, and you want an easy way to manage your
14 configuration, this can be a solution.
16 The first step will be to setup your LDAP server. I am using OpenLDAP from
17 www.openldap.org. Building and installing OpenLDAP is beyond the scope of
18 this document. There is plenty of documentation out there about this. Once
19 you have OpenLDAP installed, you will have to edit your slapd.conf file. I
20 added the following 2 lines to my configuration file:
22 include /etc/ldap/schema/dhcp.schema
23 index dhcpHWAddress eq
24 index dhcpClassData eq
26 The first line tells it to include the dhcp schema file. You will find this
27 file under the contrib directory in this distribution. You will need to copy
28 this file to where your other schema files are (maybe
29 /usr/local/openldap/etc/openldap/schema/). The second line sets up an index
30 for the dhcpHWAddress parameter. The third parameter is for reading subclasses
31 from LDAP every time a DHCP request comes in. Make sure you run the slapindex
32 command and restart slapd to have these changes to into effect.
34 Now that you have LDAP setup, you should be able to use gq
35 (http://biot.com/gq/) to verify that the dhcp schema file is loaded into LDAP.
36 Pull up gq, and click on the Schema tab. Go under objectClasses, and you
37 should see at least the following object classes listed: dhcpClass, dhcpGroup,
38 dhcpHost, dhcpOptions, dhcpPool, dhcpServer, dhcpService, dhcpSharedNetwork,
39 dhcpSubClass, and dhcpSubnet. If you do not see these, you need to check over
40 your LDAP configuration before you go any further.
42 You should now be ready to build DHCP. If you would like to enable LDAP over
43 SSL, you will need to perform the following steps:
45 * Edit the includes/site.h file and uncomment the USE_SSL line
46 or specify "-DUSE_SSL" via CFLAGS.
47 * Edit the dst/Makefile.dist file and remove md5_dgst.c and md5_dgst.o
48 from the SRC= and OBJ= lines (around line 24)
49 * Now run configure in the base source directory. If you chose to enable
50 LDAP over SSL, you must append -lcrypto -lssl to the LIBS= line in the
51 file work.os/server/Makefile (replace os with your operating system,
52 linux-2.2 on my machine). You should now be able to type make to build
55 If you choose to not enable LDAP over SSL, then you only need to run configure
56 and make in the toplevel source directory.
58 Once you have DHCP installed, you will need to setup your initial plaintext
59 config file. In my /etc/dhcpd.conf file, I have:
61 ldap-server "localhost";
63 ldap-username "cn=DHCP User, dc=ntelos, dc=net";
65 ldap-base-dn "dc=ntelos, dc=net";
67 ldap-debug-file "/var/log/dhcp-ldap-startup.log";
69 If SSL has been enabled at compile time using the USE_SSL flag, the dhcp
70 server trys to use TLS if possible, but continues without TLS if not.
72 You can modify this behaviour using following option in /etc/dhcpd.conf:
74 ldap-ssl <off | ldaps | start_tls | on>
75 off: disables TLS/LDAPS.
76 ldaps: enables LDAPS -- don't forget to set ldap-port to 636.
77 start_tls: enables TLS using START_TLS command
78 on: enables LDAPS if ldap-port is set to 636 or TLS in
81 See also "man 5 ldap.conf" for description the following TLS related
83 ldap-tls-reqcert, ldap-tls-ca-file, ldap-tls-ca-dir, ldap-tls-cert
84 ldap-tls-key, ldap-tls-crlcheck, ldap-tls-ciphers, ldap-tls-randfile
86 All of these parameters should be self explanatory except for the ldap-method.
87 You can set this to static or dynamic. If you set it to static, the
88 configuration is read once on startup, and LDAP isn't used anymore. But, if
89 you set this to dynamic, the configuration is read once on startup, and the
90 hosts that are stored in LDAP are looked up every time a DHCP request comes
93 When the optional statement ldap-debug-file is specified, on startup the DHCP
94 server will write out the configuration that it generated from LDAP. If you
95 are getting errors about your LDAP configuration, this is a good place to
98 The next step is to set up your LDAP tree. Here is an example config that will
99 give a 10.100.0.x address to machines that have a host entry in LDAP.
100 Otherwise, it will give a 10.200.0.x address to them. (NOTE: replace
101 dc=ntelos, dc=net with your base dn). If you would like to convert your
102 existing dhcpd.conf file to LDIF format, there is a script
103 contrib/dhcpd-conf-to-ldap.pl that will convert it for you. Type
104 dhcpd-conf-to-ldap.pl --help to see the usage information for this script.
106 # You must specify the server's host name in LDAP that you are going to run
107 # DHCP on and point it to which config tree you want to use. Whenever DHCP
108 # first starts up, it will do a search for this entry to find out which
110 dn: cn=brian.ntelos.net, dc=ntelos, dc=net
112 objectClass: dhcpServer
114 dhcpServiceDN: cn=DHCP Service Config, dc=ntelos, dc=net
116 # Here is the config tree that brian.ntelos.net points to.
117 dn: cn=DHCP Service Config, dc=ntelos, dc=net
118 cn: DHCP Service Config
120 objectClass: dhcpService
121 dhcpPrimaryDN: dc=ntelos, dc=net
122 dhcpStatements: ddns-update-style none
123 dhcpStatements: default-lease-time 600
124 dhcpStatements: max-lease-time 7200
126 # Set up a shared network segment
127 dn: cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net
130 objectClass: dhcpSharedNetwork
132 # Set up a subnet declaration with a pool statement. Also note that we have
133 # a dhcpOptions object with this entry
134 dn: cn=10.100.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net
137 objectClass: dhcpSubnet
138 objectClass: dhcpOptions
139 dhcpOption: domain-name-servers 10.100.0.2
140 dhcpOption: routers 10.100.0.1
141 dhcpOption: subnet-mask 255.255.255.0
142 dhcpOption: broadcast-address 10.100.0.255
145 # Set up a pool for this subnet. Only known hosts will get these IPs
146 dn: cn=Known Pool, cn=10.100.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net
149 objectClass: dhcpPool
150 dhcpRange: 10.100.0.3 10.100.0.254
151 dhcpPermitList: deny unknown-clients
153 # Set up another subnet declaration with a pool statement
154 dn: cn=10.200.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net
157 objectClass: dhcpSubnet
158 objectClass: dhcpOptions
159 dhcpOption: domain-name-servers 10.200.0.2
160 dhcpOption: routers 10.200.0.1
161 dhcpOption: subnet-mask 255.255.255.0
162 dhcpOption: broadcast-address 10.200.0.255
165 # Set up a pool for this subnet. Only unknown hosts will get these IPs
166 dn: cn=Known Pool, cn=10.200.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net
169 objectClass: dhcpPool
170 dhcpRange: 10.200.0.3 10.200.0.254
171 dhcpPermitList: deny known clients
173 # Set aside a group for all of our known MAC addresses
174 dn: cn=Customers, cn=DHCP Service Config, dc=ntelos, dc=net
176 objectClass: dhcpGroup
179 # Host entry for my laptop
180 dn: cn=brianlaptop, cn=Customers, cn=DHCP Service Config, dc=ntelos, dc=net
182 objectClass: dhcpHost
184 dhcpHWAddress: ethernet 00:00:00:00:00:00
186 You can use the command slapadd to load all of these entries into your LDAP
187 server. After you load this, you should be able to start up DHCP. If you run
188 into problems reading the configuration, try running dhcpd with the -d flag.
189 If you still have problems, edit the site.conf file in the DHCP source and
190 add the line: COPTS= -DDEBUG_LDAP and recompile DHCP. (make sure you run make
191 clean and rerun configure before you rebuild).