1LDAP Support in DHCP 2Original Author: Brian Masney <masneyb@gftp.org> 3Current Maintainer: David Cantrell <dcantrell@redhat.com> 4Last updated 07-Jul-2009 5 6This document describes setting up the DHCP server to read it's configuration 7from LDAP. This work is based on the IETF document 8draft-ietf-dhc-ldap-schema-01.txt included in the doc directory. For the 9latest version of this document, please see 10http://dcantrel.fedorapeople.org/dhcp/ldap-patch/ 11 12First question on most people's mind is "Why do I want to store my 13configuration in LDAP?" If you run a small DHCP server, and the configuration 14on it rarely changes, then you won't need to store your configuration in LDAP. 15But, if you have several DHCP servers, and you want an easy way to manage your 16configuration, this can be a solution. 17 18The first step will be to setup your LDAP server. I am using OpenLDAP from 19www.openldap.org. Building and installing OpenLDAP is beyond the scope of 20this document. There is plenty of documentation out there about this. Once 21you have OpenLDAP installed, you will have to edit your slapd.conf file. I 22added the following 2 lines to my configuration file: 23 24include /etc/ldap/schema/dhcp.schema 25index dhcpHWAddress eq 26index dhcpClassData eq 27 28The first line tells it to include the dhcp schema file. You will find this 29file under the contrib directory in this distribution. You will need to copy 30this file to where your other schema files are (maybe /etc/openldap/schema/). 31The second line sets up an index for the dhcpHWAddress parameter. The third 32parameter is for reading subclasses from LDAP every time a DHCP request comes 33in. Make sure you run the slapindex command and restart slapd to have these 34changes to into effect. 35 36Now that you have LDAP setup, you should be able to use gq 37(http://biot.com/gq/) to verify that the dhcp schema file is loaded into LDAP. 38Pull up gq, and click on the Schema tab. Go under objectClasses, and you 39should see at least the following object classes listed: dhcpClass, dhcpGroup, 40dhcpHost, dhcpOptions, dhcpPool, dhcpServer, dhcpService, dhcpSharedNetwork, 41dhcpSubClass, and dhcpSubnet. If you do not see these, you need to check over 42your LDAP configuration before you go any further. 43 44You should now be ready to build DHCP. If you would like to enable LDAP in 45dhcpd, you will need to perform the following steps: 46 47 * Apply the patch here to the unpacked ISC dhcp source tree. 48 * Regenerate the configure script (requires GNU autoconf and automake): 49 aclocal 50 libtoolize --copy --force 51 autoconf 52 autoheader 53 automake --foreign --add-missing --copy 54 * Run ./configure with the '--with-ldap' argument to enable OpenLDAP. 55 If you want LDAP over SSL, also use the '--with-ldapcrypto' argument. 56 * Run 'make' to build ISC dhcp. 57 58Once you have DHCP installed, you will need to setup your initial plaintext 59config file. In my /etc/dhcpd.conf file, I have: 60 61ldap-server "localhost"; 62ldap-port 389; 63ldap-username "cn=DHCP User, dc=ntelos, dc=net"; 64ldap-password "blah"; 65ldap-base-dn "dc=ntelos, dc=net"; 66ldap-method dynamic; 67ldap-debug-file "/var/log/dhcp-ldap-startup.log"; 68 69If SSL has been enabled at compile time, the dhcp server trys to use TLS if 70possible, but continues without TLS if not. 71 72You can modify this behaviour using following option in /etc/dhcp/dhcpd.conf: 73 74ldap-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 79 other cases. 80 81See also "man 5 ldap.conf" for description the following TLS related 82options: 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 85 86The ldap-init-retry <num> enables an optional ldap connect retry loop with 87the specified number of retries with a one second sleep between each try 88during the initial startup of the dhcp server. 89It allows to catch the condition, that the (remote) ldap server is not yet 90started at the start time of the dhcp server. 91 92All of these parameters should be self explanatory except for the ldap-method. 93You can set this to static or dynamic. If you set it to static, the 94configuration is read once on startup, and LDAP isn't used anymore. But, if 95you set this to dynamic, the configuration is read once on startup, and the 96hosts that are stored in LDAP are looked up every time a DHCP request comes 97in. 98 99When the optional statement ldap-debug-file is specified, on startup the DHCP 100server will write out the configuration that it generated from LDAP. If you 101are getting errors about your LDAP configuration, this is a good place to 102start looking. 103 104The next step is to set up your LDAP tree. Here is an example config that will 105give a 10.100.0.x address to machines that have a host entry in LDAP. 106Otherwise, it will give a 10.200.0.x address to them. (NOTE: replace 107dc=ntelos, dc=net with your base dn). If you would like to convert your 108existing dhcpd.conf file to LDIF format, there is a script 109dhcpd-conf-to-ldap that will convert it for you. Type 110dhcpd-conf-to-ldap --help to see the usage information for this script. 111 112# You must specify the server's host name in LDAP that you are going to run 113# DHCP on and point it to which config tree you want to use. Whenever DHCP 114# first starts up, it will do a search for this entry to find out which 115# config to use 116dn: cn=brian.ntelos.net, dc=ntelos, dc=net 117objectClass: top 118objectClass: dhcpServer 119cn: brian.ntelos.net 120dhcpServiceDN: cn=DHCP Service Config, dc=ntelos, dc=net 121 122# Here is the config tree that brian.ntelos.net points to. 123dn: cn=DHCP Service Config, dc=ntelos, dc=net 124cn: DHCP Service Config 125objectClass: top 126objectClass: dhcpService 127dhcpPrimaryDN: dc=ntelos, dc=net 128dhcpStatements: ddns-update-style none 129dhcpStatements: default-lease-time 600 130dhcpStatements: max-lease-time 7200 131 132# Set up a shared network segment 133dn: cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net 134cn: WV 135objectClass: top 136objectClass: dhcpSharedNetwork 137 138# Set up a subnet declaration with a pool statement. Also note that we have 139# a dhcpOptions object with this entry 140dn: cn=10.100.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net 141cn: 10.100.0.0 142objectClass: top 143objectClass: dhcpSubnet 144objectClass: dhcpOptions 145dhcpOption: domain-name-servers 10.100.0.2 146dhcpOption: routers 10.100.0.1 147dhcpOption: subnet-mask 255.255.255.0 148dhcpOption: broadcast-address 10.100.0.255 149dhcpNetMask: 24 150 151# Set up a pool for this subnet. Only known hosts will get these IPs 152dn: cn=Known Pool, cn=10.100.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net 153cn: Known Pool 154objectClass: top 155objectClass: dhcpPool 156dhcpRange: 10.100.0.3 10.100.0.254 157dhcpPermitList: deny unknown-clients 158 159# Set up another subnet declaration with a pool statement 160dn: cn=10.200.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net 161cn: 10.200.0.0 162objectClass: top 163objectClass: dhcpSubnet 164objectClass: dhcpOptions 165dhcpOption: domain-name-servers 10.200.0.2 166dhcpOption: routers 10.200.0.1 167dhcpOption: subnet-mask 255.255.255.0 168dhcpOption: broadcast-address 10.200.0.255 169dhcpNetMask: 24 170 171# Set up a pool for this subnet. Only unknown hosts will get these IPs 172dn: cn=Known Pool, cn=10.200.0.0, cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net 173cn: Known Pool 174objectClass: top 175objectClass: dhcpPool 176dhcpRange: 10.200.0.3 10.200.0.254 177dhcpPermitList: deny known clients 178 179# Set aside a group for all of our known MAC addresses 180dn: cn=Customers, cn=DHCP Service Config, dc=ntelos, dc=net 181objectClass: top 182objectClass: dhcpGroup 183cn: Customers 184 185# Host entry for my laptop 186dn: cn=brianlaptop, cn=Customers, cn=DHCP Service Config, dc=ntelos, dc=net 187objectClass: top 188objectClass: dhcpHost 189cn: brianlaptop 190dhcpHWAddress: ethernet 00:00:00:00:00:00 191 192You can use the command ldapadd to load all of these entries into your LDAP 193server. After you load this, you should be able to start up DHCP. If you run 194into problems reading the configuration, try running dhcpd with the -d flag. 195If you still have problems, edit the site.conf file in the DHCP source and 196add the line: COPTS= -DDEBUG_LDAP and recompile DHCP. (make sure you run make 197clean and rerun configure before you rebuild). 198 199DHCPv6 requires a separate instance of the dhcpd server from the 200DHCPv4 server. 201 202It is convenient to use distinct LDAP login DNs for the two servers, 203and setup LDAP access restrictions in the LDAP server, so that each 204DHCP server only has access to its own data. 205 206You will need to create a separate configuration file, 207call it /etc/dhcpd6.conf. For example: 208 209ldap-server "localhost"; 210ldap-port 389; 211ldap-username "cn=DHCPv6 User, dc=ntelos, dc=net"; 212ldap-password "blahblah"; 213ldap-base-dn "dc=ntelos, dc=net"; 214ldap-method dynamic; 215ldap-debug-file "/var/log/dhcp-ldap-startup.log"; 216 217And use these command line arguments to dhcpd: 218 219dhcpd eth... -6 -cf /etc/dhcpd6.conf -pf /var/run/dhcpd6.pid -lf /var/lib/dhcpd6/dhcpd.leases 220 221For DHCPv6, the client configuration is the same, but substitute the 222Client ID for the Ethernet hardware address. Here is an example of a 223host definition for a DHCPv6 client: 224 225dn: cn=examplehost,cn=XXXX:XXXX:XXXX:XXXX::/64,cn=Network-eth1,cn=DHCPv6,dc=example,dc=com 226objectClass: top 227objectClass: dhcpHost 228cn: examplehost 229dhcpClientId: XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX 230dhcpStatements: fixed-address6 XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX 231option host-name "examplehost.ipv6.example.com" 232option domain-name "ipv6.example.com" 233