external/bsd/dhcp/dist/contrib/ldap/README.ldap

   1 LDAP Support in DHCP
   2 Original Author: Brian Masney <masneyb@gftp.org>
   3 Current Maintainer: David Cantrell <dcantrell@redhat.com>
   4 Last updated 07-Jul-2009
   5
   6 This document describes setting up the DHCP server to read it's configuration
   7 from LDAP.  This work is based on the IETF document
   8 draft-ietf-dhc-ldap-schema-01.txt included in the doc directory.  For the
   9 latest version of this document, please see
  10 http://dcantrel.fedorapeople.org/dhcp/ldap-patch/
  11
  12 First question on most people's mind is "Why do I want to store my
  13 configuration in LDAP?"  If you run a small DHCP server, and the configuration
  14 on it rarely changes, then you won't need to store your configuration in LDAP.
  15 But, if you have several DHCP servers, and you want an easy way to manage your
  16 configuration, this can be a solution.
  17
  18 The first step will be to setup your LDAP server.  I am using OpenLDAP from
  19 www.openldap.org.  Building and installing OpenLDAP is beyond the scope of
  20 this document.  There is plenty of documentation out there about this.  Once
  21 you have OpenLDAP installed, you will have to edit your slapd.conf file.  I
  22 added the following 2 lines to my configuration file:
  23
  24 include         /etc/ldap/schema/dhcp.schema
  25 index           dhcpHWAddress eq
  26 index           dhcpClassData eq
  27
  28 The first line tells it to include the dhcp schema file.  You will find this
  29 file under the contrib directory in this distribution.  You will need to copy
  30 this file to where your other schema files are (maybe /etc/openldap/schema/).
  31 The second line sets up an index for the dhcpHWAddress parameter.  The third
  32 parameter is for reading subclasses from LDAP every time a DHCP request comes
  33 in.  Make sure you run the slapindex command and restart slapd to have these
  34 changes to into effect.
  35
  36 Now 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.
  38 Pull up gq, and click on the Schema tab.  Go under objectClasses, and you
  39 should see at least the following object classes listed: dhcpClass, dhcpGroup,
  40 dhcpHost, dhcpOptions, dhcpPool, dhcpServer, dhcpService, dhcpSharedNetwork,
  41 dhcpSubClass, and dhcpSubnet.  If you do not see these, you need to check over
  42 your LDAP configuration before you go any further.
  43
  44 You should now be ready to build DHCP.  If you would like to enable LDAP in
  45 dhcpd, 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
  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:
  60
  61 ldap-server "localhost";
  62 ldap-port 389;
  63 ldap-username "cn=DHCP User, dc=ntelos, dc=net";
  64 ldap-password "blah";
  65 ldap-base-dn "dc=ntelos, dc=net";
  66 ldap-method dynamic;
  67 ldap-debug-file "/var/log/dhcp-ldap-startup.log";
  68
  69 If SSL has been enabled at compile time, the dhcp server trys to use TLS if
  70 possible, but continues without TLS if not.
  71
  72 You can modify this behaviour using following option in /etc/dhcp/dhcpd.conf:
  73
  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
  79               other cases.
  80
  81 See also "man 5 ldap.conf" for description the following TLS related
  82 options:
  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
  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
  91 in.
  92
  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
  96 start looking.
  97
  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 dhcpd-conf-to-ldap that will convert it for you.  Type
 104 dhcpd-conf-to-ldap --help to see the usage information for this script.
 105
 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
 109 # config to use
 110 dn: cn=brian.ntelos.net, dc=ntelos, dc=net
 111 objectClass: top
 112 objectClass: dhcpServer
 113 cn: brian.ntelos.net
 114 dhcpServiceDN: cn=DHCP Service Config, dc=ntelos, dc=net
 115
 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
 119 objectClass: top
 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
 125
 126 # Set up a shared network segment
 127 dn: cn=WV Test, cn=DHCP Service Config, dc=ntelos, dc=net
 128 cn: WV
 129 objectClass: top
 130 objectClass: dhcpSharedNetwork
 131
 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
 135 cn: 10.100.0.0
 136 objectClass: top
 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
 143 dhcpNetMask: 24
 144
 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
 147 cn: Known Pool
 148 objectClass: top
 149 objectClass: dhcpPool
 150 dhcpRange: 10.100.0.3 10.100.0.254
 151 dhcpPermitList: deny unknown-clients
 152
 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
 155 cn: 10.200.0.0
 156 objectClass: top
 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
 163 dhcpNetMask: 24
 164
 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
 167 cn: Known Pool
 168 objectClass: top
 169 objectClass: dhcpPool
 170 dhcpRange: 10.200.0.3 10.200.0.254
 171 dhcpPermitList: deny known clients
 172
 173 # Set aside a group for all of our known MAC addresses
 174 dn: cn=Customers, cn=DHCP Service Config, dc=ntelos, dc=net
 175 objectClass: top
 176 objectClass: dhcpGroup
 177 cn: Customers
 178
 179 # Host entry for my laptop
 180 dn: cn=brianlaptop, cn=Customers, cn=DHCP Service Config, dc=ntelos, dc=net
 181 objectClass: top
 182 objectClass: dhcpHost
 183 cn: brianlaptop
 184 dhcpHWAddress: ethernet 00:00:00:00:00:00
 185
 186 You can use the command ldapadd 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).