Table of Contents

Configuring LDAP

This chapter describes the Lightweight Directory Access Protocol (LDAP) that allows you to use directory services to integrate Network Registrar client and lease information. By building on your existing standard schema for objects stored in LDAP directories, you can handle information about DHCP client entries. Thus, instead of maintaining client information in the DHCP server's database, you can ask the Network Registrar DHCP server to issue queries to one or more LDAP servers for information in response to DHCP client requests.

Table 13-1 lists the LDAP configuration tasks described in this chapter and the sections where you can find more information about them.

About LDAP Directory Servers

LDAP directory servers provide a way to name, manage, and access collections of attribute-value pairs. You can enter information into your LDAP server in any number of ways, because Network Registrar is not dependent on any specific LDAP object classes or schema:

• You can store DHCP client information in unused attributes. For example, you could use the givenname attribute to hold the DHCP client-class name.
  
  
• You can add new attributes to an object class if you disable schema checking. For example, you could add the attribute client-class-name to the organizational person object class.
  
  
• You can create a new object class and define the appropriate attributes. For example, you could create the DHCP client object class and define the client attributes that you want to use.
  
  

When you configure the DHCP server to read from LDAP, a query dictionary tells the DHCP server which LDAP attributes to query for. The DHCP server converts the resulting data into DHCP client-data attributes.

Tip You can configure Network Registrar to generate SNMP traps when an LDAP server stops responding or resumes responding to requests from the Network Registrar DHCP server. For more information, see the trap command in the Network Registrar CLI Reference Guide.

Configuring DHCP Client Queries in LDAP

This section explains how to configure and deprovision DHCP client queries and configure embedded policies in an LDAP client entry.

Configuring a DHCP-Server-to-LDAP Client Query

To enable the DHCP server to query your LDAP server for client data, perform the following steps. Like local client-entries, LDAP client-entries are keyed by the client's MAC address. For more information about the MAC address format, see the Network Registrar CLI Reference Guide.

Note   When connecting to an LDAP server, specify the user's distinguished name. The distinguished name is the way to uniquely identify an object in the LDAP schema. It is like a unique key in a database or a fully qualified path name for a file. For example, a distinguished name for a person might be dn: cn=Beth Jones, ou=Marketing, o=Example Corporation. In this company there may be many people named Beth and many people named Jones, but no one else named Beth Jones works in Marketing at Example Corporation.

Step 1   Tell DHCP about your LDAP server. Supply a host name. The following example creates the LDAP server object myserver with a host name of myserver.example.com.

nrcmd> ldap myserver create myserver.example.com 
 

Step 2   Configure the credentials to use when connecting to the LDAP server. The following example sets the admin to be joe and his password to be access. Use the distinguished name for the user.

nrcmd> ldap myserver set username="cn=joe, o=Example Corp, c=US" 
nrcmd> ldap myserver set password=access 
 

Step 3   Set the search-path. This is a point in the directory from which to start searches. The following example sets the base of the search to be the organization, Example Corp., and the country, US.

nrcmd> ldap myserver set search-path="o=Example Corp, c=US" 
 

Step 4   Set the search-filter to be the attribute for which DHCP will substitute the clients' MAC addresses. In this example the attribute is the common name (cn).

nrcmd> ldap myserver set search-filter=(cn=%s) 
 

Step 5   Configure a query-dictionary, which contains all the LDAP-to-DHCP mappings.

Use the ldap setEntry command to set these mappings.

nrcmd> ldap myserver setEntry query-dictionary 
sn=host-name 

nrcmd> ldap myserver setEntry query-dictionary 
givenname=client-class-name 
 

nrcmd> ldap myserver setEntry query-dictionary 
localityname=domain-name 
 

Step 6   Enable queries for the LDAP server. The following example enables queries for myserver.

nrcmd> ldap myserver enable can-query 
 

Step 7   Enable client-class processing for the DHCP server.

nrcmd> dhcp enable client-class 
 

Step 8   Enable the DHCP server to use LDAP for client-entry queries.

nrcmd> dhcp enable use-ldap-client-data 
 

Step 9   Save and reload the DHCP server.

nrcmd> server dhcp reload 
 

For details about the ldap command and client-class properties, see the Network Registrar CLI Reference Guide.

Deprovisioning Client Entries

You can deprovision LDAP client entries so that the client information remains in LDAP, but the DHCP server treats the client as if that information does not exist. The DHCP server then supplies the client with the default behavior.

Configure the search filter set in Step 4 of the preceding section so that the LDAP server does not return a client entry containing a specified attribute with a value.

For example, if you want to deprovision the LDAP entry givenname, configure the following search filter:

nrcmd> ldap myserver set 
search-filter=(&(cn=%s)(!(givenname=deprovision))) 
 

Whenever the givenname attribute in the LDAP client entry is set to the deprovision string, the LDAP server does not return the client entry to the DHCP server. In other words, the DHCP server treats the client as if it has no LDAP client entry.

Note   This procedure has no measurable performance impact on either the DHCP or the LDAP server.

Configuring Embedded Policies in LDAP

To configure embedded policies in LDAP, follow these steps:

Step 1   Configure an LDAP server for the DHCP server, naming it myserver, for example.

Step 2   Map the LDAP attribute that you want the DHCP server to interpret as the embedded policy to the internal embedded-policy property. The following example maps the businessCategory LDAP attribute to the property.

nrcmd> ldap myserver setEntry query-dictionary businessCategory=embedded-policy 
 

Step 3   Add a string to the LDAP attribute that the DHCP server can interpret as an embedded policy. The most practical way to determine what this string should look like is to create a dummy client in the Network Registrar database and use the mcdadmin utility to determine the proper string to add to the LDAP attribute. Note that this dummy client will never be used, because you are using LDAP, and you can subsequently delete it. Have the embedded policy include the option data types you need.

nrcmd> client 1,6,01:02:03:04:05:06 create 
100 Ok
nrcmd> client-policy 1,6,01:02:03:04:05:06 set 
dhcp-reply-options=packet-file-name,packet-server-name 
100 Ok
dhcp-reply-options=packet-file-name,packet-server-name
nrcmd> client-policy 1,6,01:02:03:04:05:06 setOption routers 1.2.3.4,5.6.7.8 
100 Ok
routers=1.2.3.4,5.6.7.8
nrcmd> save 
100 Ok
 

mcdadmin -p /servers/name/dhcp/1/cliententry -e filename 
user:
password:
 

On NT, run this utility from the Bin folder in the Network Registrar installation directory. On Solaris, it is located in the opt/nwreg2/usrbin directory of the installation directory. The user name and password are required.

1,6,01:02:03:04:05:06 = bin:[256] ((ClassName ClientEntry)

(embedded-policy 

((ClassName Policy)

(name client-policy:1,6,01:02:03:04:05:06)

(vendoroptions ())

(version 1)

(dhcp-reply-options [packet-file-name packet-server-name ])

(dhcp-reply-options-number [257 258 ])

(options ((routers 01:03:01:02:03:04:05:06:07:08))))

))
 

The ((ClassName Policy) entry is the start of the embedded policy string, with a single closing parentheses ending the string. (The entire entry normally runs together. It is presented here for clarity as parenthesized groupings on separate lines. The final three parentheses close, respectively, the ClassName Policy, embedded-policy, and ClassName Client Entry groupings.)

businessCategory:((ClassName Policy)(name 
client-policy:1,6,01:02:03:04:05:06)(vendoroptions ())(version 1)(dhcp-reply-options 
[packet-file-name packet-server-name ])(dhcp-reply-options-number [257 258 ])(options 
((routers 01:03:01:02:03:04:05:06:07:08))))

---

Note   The option values are translated into hexadecimal field syntax, including multiple values that were originally comma-separated. For example, setOption routers 1.2.3.4, 5.6.7.8 translates into (options ((routers 01:03:01:02:03:04:05:06:07:08))). The first field of the option value is the number of bytes in the option number (01 or 02). The second field is the option number itself in hex (option 03, routers, in the example).

---

nrcmd> client 1,6,01:02:03:04:05:06 delete

100 Ok
nrcmd> save 
100 Ok
 

Configuring the DHCP LDAP Update and Create Service

You can configure the DHCP LDAP service to copy lease state data to existing attributes in the LDAP server. The service converts the lease state data to string form, and uses an update dictionary to map the LDAP attributes to the DHCP data values.

Each time the state of a lease changes, the DHCP server makes a copy of the data and then transfers it to the LDAP server that you have configured to store lease state data.

Lease State Attributes

You can store any of the following attributes about the lease's state information in your LDAP server:

• address—The IP address of this lease.
  
  
• client-dns-name—The name the DHCP server attempted to enter into the DNS server for this client.
  
  
• client-domain-name—The domain name specified into which to put the client's DNS name.
  
  
• client-flags—A variety of flags relating to the client.
  
  
• client-host-name—The DNS name that the client requested the DHCP server place into the DNS server.
  
  
• client-id—The client-id specified by the client, or one synthesized by the DHCP server for this client.
  
  
• client-mac-addr—The MAC address that the client presented to the DHCP server.
  
  

---

Note   Although the MAC addresses in LDAP have to be formatted exactly the way they are formatted by Network Registrar when it creates local client-entries, they are separate instances and thus unique to lease data.

---

• expiration—The time at which the lease will expire.
  
  
• flags—Flags for the lease: reserved or de-activated.
  
  
• lease-renewal-time—The earliest time in which the client is expected to issue a lease renewal.
  
  
• start-time-of-state—The time at which the state last changed to its current value.
  
  
• state—Represented as either available, leased, expired, or unavailable.
  
  
• vendor-class-identifier—The name of the vendor, used by clients and servers to exchange vendor-specific information.
  
  

Not every lease has all these attributes. The client-mac-addr and client-id are not present if a client releases its lease or is forced available through Network Registrar. In addition, the lease-renewal-time may not be present if the save-lease-renewal-time property is disabled through DHCP. Similarly, the vendor-class-identifier property may not be present if the save-vendor-class-id property is disabled through DHCP, using the CLI.

Configuring LDAP for Lease State Updates

There are three steps to configuring lease state updates:

Step 1   Choose the lease state update scheme.

Step 2   Add entries to the directory or modify existing entries to store the lease state information. You may need to extend entries through the addition of attributes or custom object classes.

Step 3   Configure Network Registrar to perform the updates.

Given the flexibility of directories, there are many different ways in which you could choose to store a copy of lease state attributes in a directory. For example, you could choose to store the lease state data as part of an existing entry, or you could store the lease state data independently.

Storing Lease State Data As Part of an Existing Entry

You can store lease state data as part of an existing entry, like a person. It is even possible to store the client-entry information, the lease state information, and employee data in the same entry. As part of the setup for this method, you must decide how you want to store the lease data attributes. You may store data attributes using the following methods:

• Map attributes from the entry.
  
  
• Add attributes to the entry.
  
  
• Extend the entry by creating a new object class.
  
  

The advantage to this method is that lease data is stored directly with other associated client information. The disadvantage is that there are scenarios, albeit unlikely, related to client-class and reservations that could result in stale data being in the directory for a short period of time when a client is moved off a lease by the server.

Note   If the lease (whose state is being updated) does not have a client, it will not have an associated MAC address. This situation occurs when a client gets a lease, and then is moved off of that lease by client-class, or when a client has a lease, and has a reservation for a different lease in the same LAN segment. When the reserved lease is available, the server moves the client off of its existing lease and onto the reservation. Both of these transfers result in an LDAP update for the old lease without a client MAC address. In general this is benign (except for the log message), because the update for the client's new lease should come through too, and of course that update has an associated MAC address.

Also, this method requires two LDAP interactions to write the lease information. When updating lease state information, the DHCP LDAP service contacts the directory twice because when updating an entry it is not enough just to know how to find the entry. You must specifically know the entry's distinguished name.

The DHCP LDAP service first finds the appropriate entry in the directory by using one of the lease state attributes that you chose (preferably the MAC address) as the search criteria. This is necessary because none of the lease state attributes is part of the distinguished name of the entry. When the DHCP LDAP service locates the entry, the distinguished name is returned. The DHCP LDAP service then updates that same entry with the appropriate information. For an example how to use this method, see the "Configuring LDAP State Updates" section.

Storing Lease State Data Independently

You can store lease state data by IP address in its own entries. This method results in a copy of the server lease-data database in a directory, and is the most straightforward way to configure the database. As part of the setup for this method, create new entries for each IP address that the server can serve. The advantage to this method is that there are no scenarios in which the lease state data in the directory will be stale. The disadvantage is that lease data is not stored directly with other associated client information.

To update the lease state information, the DHCP LDAP service contacts the directory service once. When performing the update, DHCP LDAP service uses the IP address to construct the distinguished name.

Using LDAP Updates

There are two ways you can use the LDAP update feature:

• To keep track of clients that use LDAP client-entry information and to associate some of the attributes of that LDAP host with lease state attributes.
  
  
• To create and update objects that can be located by their IP address. When Network Registrar creates these objects, it can make a level of LDAP objects that matches (or is) the DHCP server's lease state.
  
  

When using Network Registrar, you should be aware of the following:

• The DHCP server only reads from a single object and writes to a single object. You can use separate objects to hold the client-entry data read and the lease state date written, but Network Registrar cannot read some attributes from one object, and some from another.
  
  
• The performance of LDAP queries is, like all database access, dependent upon indexed attributes. If you have not indexed the attributes that you have configured to use in query filters, you will experience poor performance.
  
  
• When configured for update, Network Registrar does not create new objects in the directory. The DHCP server only writes to existing objects. However, if you configure for update and create, it does create new objects (if no object exists).
  
  

Configuring LDAP State Updates

There are two options available for performing a lease state update to an LDAP server.

• Using update-search-path. The DHCP server first queries to locate the dn (distinguished name) for an update.
  
  
• Using dn-format. The DHCP server is provided with the distinguished name for an update. In other words, the DHCP performs a direct update without having to query before an update.
  
  

Option 1: Using the update-search-path Option

The following example illustrates the first option, update-search-path. It shows what to do when the LDAP object's dn cannot be constructed from data that is available in the lease state. The DHCP server creates an LDAP query based on the update-search-xxx information, locates the LDAP object, and uses its distinguished name to issue an LDAP update.

The example shown in Table 13-2 assumes you are using the standard LDAP organizational person object class attributes to hold lease update data.

Step 1   Tell DHCP about your LDAP server.

You must supply the server's host name. The following example creates the LDAP server object myserver with a host name of myserver.example.com.

nrcmd> ldap myserver create myserver.example.com 
 

Step 2   Configure the credentials to use when connecting to the LDAP server.

The following example sets the admin to be joe and his password to be access. Use the distinguished name for the user.

nrcmd> ldap myserver set username="cn=joe, o=Example Corporation, 
c=US" 
nrcmd> ldap myserver set password=access 
 

Step 3   Configure the update-search-path, which is the starting point in the directory for the objects that the DHCP server will update.

The following example sets the search path to begin at the organizational unit (ou) IT, the organization Example Corporation, and country US.

nrcmd> ldap myserver set update-search-path="ou=IT, o=Example Corp, 
c=US" 
 

Step 4   Set the ID of the attribute you want to use to search for the LDAP object that will be updated.

The following example sets the search attribute to be the client's MAC address.

nrcmd> ldap myserver set update-search-attribute=client-mac-addr 
 

Step 5   Configure a filter expression into which the update-search-attribute should be formatted.

This expression must contain a %s, which indicates where the search-attribute's data should be substituted.

nrcmd> ldap myserver set update-search-filter=(cn=%s) 
 

Step 6   Configure an update-dictionary, which allows you to identify the LDAP attributes that you want set with the values of the corresponding lease state attributes.

The following example specifies that the LDAP uid should be updated to contain the IP address, and that the attribute carlicense should be updated to contain the DHCP lease state information.

nrcmd> ldap myserver setEntry update-dictionary uid=address 
carlicense=state 
 

Step 7   Enable updates for the new LDAP server.

nrcmd> ldap myserver enable can-update 
 

Step 8   Save and reload the DHCP server.

nrcmd> server dhcp reload 
 

Option 2: Using the dn-format Option

The following example illustrates using the second option, dn-format:

Step 1   Tell DHCP about your LDAP server.

nrcmd> ldap myserver_option2 create myserver.example.com 
 

Step 2   Configure the credentials to use when connecting to the LDAP server.

The following example sets the admin to be joe and his password to be access. Use the distinguished name for the user.

nrcmd> ldap myserver_option2 set username="cn=joe, o=Example 
Corporation, c=US" 
 
nrcmd> ldap myserver_option2 set password=access 
 

Step 3   Use the dn-format string to specify where in the LDAP server database hierarchy you want to begin searching for the update.

nrcmd> ldap myserver_option2 set dn-format="cn=\"%s\", ou=IT, 
o=Example Corp, c=US" 
 

Step 4   Set the dn-attribute to which you want the dn-format string to refer.

The following example sets the dn-attribute to be the client's MAC address.

nrcmd> ldap myserver_option2 set dn-attribute=client-mac-addr 
 

Step 5   Specify the entries to be updated.

nrcmd> ldap myserver_option2 setEntry update-dictionary 
uid=address carlicense=state 
 

Step 6   Enable the can-update feature.

nrcmd> ldap myserver_option2 enable can-update 
 

Step 7   Reload the server.

nrcmd> server dhcp reload 
 

Configuring LDAP Entry Creation

This section explains how to create LDAP entries. LDAP entry creation provides the ability to locate entries and update them with current lease information. Entries are created only if a state update operation fails because it cannot locate an entry.

After performing the steps in the previous example, follow these steps to configure LDAP entry creation.

Step 1   Set the dn-attribute property for the LDAP server for the lease object attribute, such as the client-mac-addr field, and set the dn-format string.

nrcmd> ldap myserver set dn-attribute=client-mac-addr 
nrcmd> ldap myserver set dn-format="cn=\"%s\", ou=IT, o=Example Corp, 
c=US" 

Note   This step is required only if you configure the lease state updates using the update-search-path option. (See "Option 1: Using the update-search-path Option" section). Skip this step if you configure lease state updates using the dn-format string. (See "Option 2: Using the dn-format Option" section.)

Step 2   Create the distinguished name of the entry to be created when combined with the existing dn-attribute property.

nrcmd> ldap myserver set dn-create-format= "cn=\"%s\",ou=IT,o=Example 
Corp, c=US" 

---

Note   Network Registrar's client-mac-addr field uses this form: 1,6:xx:xx:xx:xx:xx:xx. Since the comma character is a special separator in LDAP, you must use the \" characters to quote distinguished names.

---

Step 3   Using the create-dictionary property, establish mappings between LDAP attributes and lease state attributes by entering a series of name=value pairs.

The LDAP attributes indicate the entry attributes set to the value of their corresponding lease state attributes.

nrcmd> ldap myserver setEntry create-dictionary sn=client-host-name 
nrcmd> ldap myserver setEntry create-dictionary 
givenname=client-class-name 
nrcmd> ldap myserver setEntry create-dictionary localityname=client-domain-name 
 

Step 4   Using the create-object-classes property, specify the object classes to be used when creating the entry. Use a comma-delimited list format.

nrcmd> ldap myserver set create-object-classes= 
        "top,person,organizationalPerson,inetorgperson" 
 

Step 5   Enable entry creation for the LDAP server myserver.

nrcmd> ldap myserver enable can-create 

---

Note   Be sure you enable the can-update feature before enabling the can-create feature. For an example, see the "Configuring LDAP State Updates" section.

---

Step 6   Save and reload the DHCP server.

nrcmd> server dhcp reload 
 

Note   To see if creation, queries, and updates were successful, view LDAP log settings. For more information, refer to the ldap command in Chapter 2 of the Network Registrar CLI Reference Guide.