Creating, Editing, and Attaching Extensions

Determining Tasks

Deciding on Approaches

Choosing Extension Languages

The task to which to apply an extension is usually some modification of the DHCP server processing so that it better meets the needs of your environment. You can apply an extension at each of these DHCP server processing points, from receiving a request to responding to the client:

1. Receive and decode the packet.
2. Look up, modify, and process any client-class.
3. Build a response type.
4. Determine the subnet (or link, in the case of DHCPv6).
5. Find any existing leases.
6. Serialize the lease requests.
7. Determine the lease acceptability for the client.
8. Gather and encode the response packet.
9. Update stable storage of the packet.
10. Return the packet.

A more complete list of these steps (along with the extension points to use at each step) appears in DHCP Request Processing Using Extensions.

For example, you might have an unusual routing hub that uses BOOTP configuration. This device issues a BOOTP request with an Ethernet hardware type (1) and MAC address in the chaddr field. It then sends out another BOOTP request with the same MAC address, but with a hardware type of Token Ring (6). Specifying two different hardware types causes the DHCP server to allocate two IP addresses to the device. The DHCP server normally distinguishes between a MAC address with hardware type 1 and one with type 6, and considers them different devices. In this case, you might want to write an extension that prevents the DHCP server from handing out two different addresses to the same device.

Many solutions are often available to a single problem. When choosing the type of extension to write, you should first consider rewriting the input DHCP packet. This is a good approach, because it avoids having to know the internal processing of the DHCP server.

For the problem described in Determining Tasks, you can write an extension to solve it in either of these ways:

• Drop the Token Ring (6) hardware type packet.
• Change the packet to an Ethernet packet and then switch it back again on exit.

Although the second way involves a more complex extension, the DHCP client could thereby use either reply from the DHCP server. The second approach involves rewriting the packet, in this case using the post-packet-encode extension point (see post-packet-encode). Other approaches require other extensions and extension points.

You can write extensions in Tcl or C/C++. The capabilities of each language, so far as the DHCP server is concerned, are similar, although the application programming interface (API) is slightly different to support the two very different approaches to language design:

• Tcl —Although scripting in Tcl might be somewhat easier than scripting in C/C++, it is interpreted and single-threaded, and might require more resources. However, you might be less likely than in C/C++ to introduce a serious bug, and there are fewer chances of a server failure. Cisco Prime Network Registrar currently supports Tcl version 8.4.
• C/C++ —This language provides the maximum possible performance and flexibility, including communicating with external processes. However, the C/C++ API is more complex than the Tcl API. Also, the possibility of a bug in the extension causing a server failure is also more likely in C/C++.

Routine Signature

Dictionaries

Utility Methods in Dictionaries

Configuration Errors

Recognizing Extensions

Multiple Extension Considerations

You need to define the extension as a routine in a file, which can contain multiple extension functions. You then attach the extension to one or more of the DHCP server extension points. When the DHCP server reaches that extension point, it calls the routine that the extension defines. The routine returns with a success or failure. You can configure the DHCP server to drop a packet on an extension failure.

You can configure one file—Tcl source file or C/C++ .dll or .so file—as multiple extensions to the DHCP server by specifying a different entry point for each configured extension.

The server calls every routine entry point with at least three arguments, the three dictionaries—request, response, and environment. Each dictionary contains many data items, each being a key-value pair:

• The extension can retrieve data items from the DHCP server by performing a get method on a dictionary for a particular data item.
• The extension can alter data items by performing a put or remove operation on many of the same named data items.

Although you cannot use all dictionaries at every extension point, the calling sequence for all routines is the same for every extension point. The extension encounters an error if it tries to reference a dictionary that is not present at a particular extension point. (See Extension Dictionaries.)

You access data in the request, response, and server through a dictionary interface. Extension points include three types of dictionaries—request, response, and environment:

• Request dictionary —Information associated with the DHCP request, along with all that came in the request itself. Data is string-, integer-, IP address-, and blob-valued.
• Response dictionary —Information associated with generating a DHCP response packet to return to the DHCP client. Data is string-, integer-, IP address-, and blob-valued.
• Environment dictionary —Information passed between the DHCP server and extension.

For a description of the dictionaries, see Extension Dictionaries.

You can also use the environment dictionary to communicate between an extension attached at different extension points. When encountering the first extension point at which some extension is configured, the DHCP server creates an environment dictionary. The environment dictionary is the only one in which the DHCP server does not fix the names of the allowable data items. You can use the environment dictionary to insert any string-valued data item.

Every extension point in the flow of control between the request and response for the DHCP client (all extension points except lease-state-change , depending on the cause of the change) share the same environment dictionary. Thus, an extension can determine that some condition exists, and place a sentinel in the environment dictionary so that a subsequent extension can avoid determining the same condition.

In the previous example, the extension at the post-packet-decode extension point determines that the packet was the interesting one—from a particular manufacturer device, BOOTP, and Token Ring—and then rewrites the hardware type from Token Ring to Ethernet. It also places a sentinel in the environment dictionary and then, at a very simple extension at the post-packet-encode extension point, rewrites the hardware type back to Token Ring.

Each dictionary has associated utility methods with which you can reset the trace level for an extension and log values to an output file.

Extensions can fail for many reasons. For example:

• The server cannot find the file.
• The entry point or init-entry point does not appear in the file.
• The extension itself can return a failure from an init-entry call.

By itself, an extension failure is not fatal and does not prevent the DHCP server from starting. However, if you configure that failed extension at any extension point, the server will not start. Therefore, to debug the configuration process, you can configure the extension at the init-entry point (see init-entry) without attaching it to an extension point. When you complete that process successfully, you can attach your extension to an extension point.

You can write extensions that communicate with external servers or databases to affect the client class or validate incoming DHCP client requests. Writing such extensions is a complex task, requiring considerable skill and debugging expertise. Such extensions must be multithreaded, and need to communicate very swiftly with the external server if the DHCP server performance is to remain at an acceptable level.

Performance degradations can result from extensions stalling the threads that are processing requests. A thread stalls while an extension communicates with an external server. If this interaction takes more than 50 to 100 milliseconds, this severely affects server performance. This might or might not impact you in the particular environment in which you deploy this extension.

One way to avoid having to communicate with an external server synchronously (that is, stalling the incoming DHCP client request processing to communicate with the external server) is to avoid performing this communication while processing the DHCP client request. This sounds obvious, and it also sounds, on the face of it, impossible. However, due to the nature of the DHCP client-server protocol, there is a way to decouple the access to the external server from the DHCP client request processing.

This caching mechanism requires the extension to have a receiver thread (started and stopped in the init-entry extension point). This thread reads the socket and updates the cache with the response. This thread (or a separate one) would also need to time out and remove old items from the cache. Using a single thread, however, might require setting a larger receive socket buffer size.

These techniques are only necessary if the load on the DHCP server is high and the speed of the external server is not high enough to support the required performance of the DHCP server load. However, this situation turns out to be all too common in practice. And, consider what can happen if the external server is unreachable (when connection timeouts are likely to be for minutes and not seconds).

The DHCP server only recognizes extensions when it initially configures itself at start or reload time. You can change an extension or the configuration for extensions in general. However, until you reload or restart the server, the changes have no effect. Forgetting to reload the DHCP server can be a frequent source of errors while debugging extensions.

The reason Cisco Prime Network Registrar requires a reload is to ensure minimum processing impact by preloading extensions and getting them ready at server configuration time. While this approach is useful in production mode, it might cause some frustration when you debug extensions.

You can register multiple extensions at any extension point. The DHCP server runs all the extensions attached to an extension point before resuming processing, the conditions being:

• An extension should not explicitly set a data item unless the extension explicitly requires that behavior. For example (as described for the drop environment dictionary data item in Table 31-5 on page 31-25), extensions can request dropping the client packet at most extension points.

  The server calls the first extension registered at an extension point with drop set to False. One or more extensions can set this to True or False. If all extensions were to explicitly set drop to either True or False, then the server would take whatever action the last extension to run requested.

  This might not be the desired behavior. Thus, for this data item, it is better for an extension to set drop to True only if it wants the packet to be dropped. That way, if all extensions play by this rule, the packet would be dropped if any of the extensions request it.

• An extension might want to return immediately if drop is True, as there may not be a need for the extension to do its processing if another one desires the packet to be discarded.
• If the environment dictionary is used to store items for use in later extension points, those data item names might want to use a prefix or suffix that is unique to that extension. This reduces the chance for data item name conflicts.
• At least one environment dictionary data item, the user-defined-data (see Table 30) that you can use to store data with a lease (for DHCPv4) or client (DHCPv6), requires special attention.

  This data item can be difficult for more than one extension to use, unless those extensions take special care to preserve and recognize each other’s values. Thus, it might not be possible for more than one extension to assume it can use this data item.

• You must specify whether the extensions should be run first, or last, if such a need exists. For example, you should run extensions that cause the server to drop certain packets first, because this reduces the processing burden on the server (assuming the remaining extensions return immediately if drop is true).

Tcl Application Program Interface

Dealing with Tcl errors

Handling Boolean Variables in Tcl

Configuring Tcl Extensions

Init-Entry Extension Point in Tcl

Every Tcl extension has the same routine signature:

proc yourentry { request response environ } { # your-code }

To operate on the data items in any dictionary, you must treat these arguments as commands. Thus, to get the giaddr of the input packet, you would write:

set my_giaddr [ $request get giaddr ]

This sets the Tcl variable my_giaddr to the string value of the giaddr in the packet; for example, 10.10.1.5 or 0.0.0.0.

You could rewrite the giaddr in the input packet by using this Tcl statement:

$request put giaddr "1.2.3.4"

To configure one routine entry for multiple extension points and to alter its behavior depending on the extension point from which the server calls it, the DHCP server passes the ASCII name of the extension point in the environment dictionary under the key extension-point .

For some sample Tcl extensions, see the Cisco Prime Network Registrar directory; by default:

• Linux —/opt/nwreg2/local/examples/dhcp/tcl
• Windows —\Program Files\Cisco Prime Network Registrar\examples\dhcp\tcl

You generate a Tcl error if you:

• Reference a dictionary that is not available.
• Reference a dictionary data item that is not available.
• Request a put operation on an invalid data item, for example, an invalid IP address.

In these cases, the extension immediately fails unless you surround the statement with a catch error statement:

catch { $request put giaddr "1.2.3.a" } error

You generate a Tcl error if you:

• Reference a dictionary that is not available.
• Reference a dictionary data item that is not available.
• Request a put operation on an invalid data item, for example, an invalid IP address.

In these cases, the extension immediately fails unless you surround the statement with a catch error statement:

catch { $request put giaddr "1.2.3.a" } error

In the environment dictionary, the Boolean variables are string-valued and have a value of true or false . The DHCP server expects an extension to set the value to true or false . However, in the request or response dictionaries, Boolean values are single-byte numeric format, and true is 1 and false is 0 . While more efficient for the C/C++ extensions, this approach does make the Tcl API a bit more complex.

Tcl extensions support the init-entry extension point (see init-entry), and the arguments supplied in the init-args parameter to the command line appear in the environment dictionary associated with the key arguments .

Multiple Tcl interpreters can run in the DHCP server, for performance purposes, each in its own Tcl context. The server calls the Tcl extension once at the init-entry point for every Tcl context (interpreter) it runs. Ensure that your Tcl extension init-entry is robust, given multiple calls.

Information cannot flow between the Tcl contexts, but the init-entry can initialize global Tcl variables in each Tcl interpreter that any Tcl extension can access, regardless of the interpreter.

Note that all Tcl extensions share the Tcl interpreters. If your Tcl extension initializes global variables or defines procedures, ensure that these do not conflict with some other Tcl extension global variables or procedure names.

C/C++ API

Using Types in C/C++

Building C/C++ Extensions

Using Thread-Safe Extensions in C/C++

Configuring C/C++ Extensions

Debugging C/C++ Extensions

The routine signature for both the entry and init-entry routines for the C/C++ API is:

typedef int (DEXAPI * DexEntryPointFunction)(
int iExtensionPoint,
dex_AttributeDictionary_t* pRequest,
dex_AttributeDictionary_t* pResponse,
dex_EnvironmentDictionary_t* pEnviron );

Along with pointers to three structures, the integer value of the extension point is one of the parameters of each routine.

The C/C++ API is specifically constructed so that you do not have to link your shared library with any Cisco Prime Network Registrar DHCP server files. You configure the entry to your routine when you configure the extension. The necessary call-back information for the operations to perform on the request, response, and environment dictionaries is in the structures that comprise the three dictionary parameters passed to your extension routine.

The DHCP server returns all binary information in network order, which is not necessarily properly aligned for the executing architecture.

Many C/C++ routines are available that use types, for example, getByType() . These routines are designed for use in performance-sensitive environments. The reasoning behind these routines is that the extension can acquire pointers to types once, for example, in the init-entry point, and thereafter use the pointers instead of string-valued names when calling the routines of the C/C++ API. Using types in this manner removes one hash table lookup from the extension processing flow of execution, which should improve (at least fractionally) the performance of any extension.

The directories /opt/nwreg2/local/examples/dhcp/dex (UNIX and Linux) and \Program Files\Cisco Prime Network Registrar\examples\dhcp\dex (Windows) contain sample C/C++ extension code, as well as a short makefile designed to build the sample extensions. To build your own extensions, you need to modify this file. It has sections for Microsoft Visual C++ and GNU C++. Simply move the comment lines to configure the file for your environment.

Your extension needs to reference the include file dex.h. This file contains the information your program needs to use the C/C++ API. When building C/C++ extensions on Windows, remember to add your entry points to the .def file.

After you build the .dll (Windows) or .so (UNIX) file (all dex extensions are shared libraries), you need to move them into the /opt/nwreg2/local/extensions/dhcp/dex directory (UNIX), or the \Program Files\Cisco Prime Network Registrar\extensions\dhcp\dex directory (Windows). You can then configure them.

The DHCP server is multithreaded, so any C/C++ extensions written for it must be thread-safe. Multiple threads, and possibly multiple processors, must be capable of calling these extensions simultaneously at the same entry point. You should have considerable experience writing code for a multithreaded environment before designing C/C++ extensions for Cisco Prime Network Registrar.

Caution

All C/C++ extensions must be thread-safe. If not, the DHCP server will not operate correctly and will fail in ways that are extremely difficult to diagnose. All libraries and library routines that these extensions use must also be thread-safe.

On several operating systems, you must ensure that the runtime functions used are really thread-safe. Check the documentation for each function. Special thread-safe versions are provided (often functionname _r) on several operating systems. Because Windows provides different versions of libraries for multithreaded applications that are thread-safe, this problem usually does not apply.

Be aware that if any thread makes a non-thread-safe call, it affects any of the threads that make up the safe or locked version of the call. This can cause memory corruptions, server failures, and so on.

Diagnosing these problems is extremely difficult, because the cause of these failures are rarely apparent. To cause a server failure, you need very high server loads or multiprocessor machines with many processes. You might need running times of several days. Often, problems in extension implementation might not appear until after sustained periods of heavy load.

Because some runtime or third-party libraries might make non-thread-safe calls that you cannot detect, check your executables as to what externals are being linked (nm on UNIX).

If the routines of a library call the routines without the _r suffixes, displayed in the following table, the library is not thread-safe, and you cannot use it. The interfaces to the thread-safe versions of these library routines can vary based on operating system.

Because the .dll and .so files are active when the server is running, it is not a good idea to overwrite them. After you stop the server, you can overwrite the .dll and .so files with newer versions.

Because your C/C++ shared library runs in the same address space as the DHCP server, and receives pointers to information in the DHCP server, any bugs in your C/C++ extension can very easily corrupt the DHCP server memory, leading to a server failure. For this reason, use extreme care when writing and testing a C/C++ extension. Frequently, you should try the approach to an extension with a Tcl extension and then code the extension in C/C++ for increased performance.

Enabling DHCPv6 Extensions

Receiving Packets

Decoding Packets

Determining Client-Classes

Modifying Client-Classes

Processing Client-Classes

Building Response Containers

Determining Networks and Links

Finding Leases

Serializing Lease Requests

Determining Lease Acceptability

DHCPv6 Leasing

Gathering Response Packet Data

Encoding Response Packets

Updating Stable Storage

Sending Packets

Processing DNS Requests

Tracing Lease State Changes

Controlling Active Leasequery Notifications

By default, extensions are assumed to support only DHCPv4. To write DHCPv6 extensions, you must implement an init-entry extension point that must:

1. Set the dhcp-support environment data item to v4 (for DHCPv4 only, the preset value), v6 (for DHCPv6 only), or v4,v6 (for DHCPv4 and DHCPv6). This data item indicates to the server what the extension is willing to support.
2. Set the extension-extensionapi-version environment data item to 2 . (The dhcp-support data item is ignored unless the extension-extension-api-version is set to 2 .)

You might need to write separate extensions for DHCPv4 and DHCPv6, because of the differences in packet formats, DHCP protocol, and internal server data. However, the fundamentals of both kinds of extensions are very much the same.

The server calls these extension points at essentially the same places during processing, although it can call some DHCPv6 extension points multiple times due to the possibility of multiple lease requests per client.

The DHCP server receives DHCPv4 packets on port 67 and DHCPv6 packets on port 547 (the DHCP input ports) and queues them for processing. It attempts to empty the UDP input queue as quickly as possible and keeps all of the requests that it receives on an internal list for processing as soon as a free thread is available to process them. You can configure the length of this queue, and it will not grow beyond its maximum configured length.

When a free thread is available, the DHCP server allocates to it the task of processing an input request. The first action it takes is to decode the input packet to determine if it is a valid DHCP client packet. As part of this decoding process, the DHCP server checks all options to see if they are valid—if the lengths of the options make sense in the overall context of the request packet. It also checks all data in the DHCP request packet, but takes no action on any data in the packet at this stage.

Use the pre-packet-decode extension point to rewrite the input packet. After the DHCP server passes this extension point, it stores all information from the packet in several internal data structures to make subsequent processing more efficient.

If you configure an expression in the client-class-lookup-id, it is at this stage that the DHCP server evaluates the expression (see Using Expressions for a description of expressions). The result of the expression is either <null>, or something converted to a string. The value of the string must be either a client-class name or <none>. In the case of <none>, the server continues to process the packet in the same way as if there were no client-class-lookup-id configured. In the case of a <null> response or an error evaluating the client-class-lookup-id, the server logs an error message and drops the packet (unless an extension configured at the post-class-lookup extension point specifically instructs the server not to drop the packet). As part of the process of setting the client-class, the DHCP server evaluates any limitation-id configured for that client-class and stores it with the request.

After the DHCP server evaluates the client-class-lookup-id and sets the client-class, it calls any extension attached to the post-class-lookup extension point. You can use that extension to change any data that the client-class caused to become associated with the request, including the limitation-id. The extension also learns if the evaluation of the client-class-lookup-id dropped the packet. The extension not only finds out if it needs to drop the packet, it instructs the server not to drop the packet if it wants the server not to do so.

Also, an extension running at the post-class-lookup extension point can set a new client-class for the request, and uses the data from that client-class instead of the current one. This is the only extension point where setting the client-class actually uses that client-class for the request.

If you enabled client-class processing, the DHCP server performs it at this stage.

Use the pre-client-lookup extension point to affect the client to look up, possibly by preventing the lookup or supplying data that overrides the existing data. After the DHCP server passes the pre-client-lookup extension point, it looks up the client (unless the extension specifically prevents it) in the local database or in an LDAP database, if one was configured.

After the server looks up the client, it uses the data in the client entry to fill in additional internal data structures. The DHCP server uses data in the specified client-class entry to complete any data that the client entry does not specify. When the DHCP server retrieves all the data stored in the various places in the internal data structures for additional processing, it runs the next extension point.

Use the post-client-lookup extension point to review the operation of the client-class lookup process, such as examining the internal server data structures filled in from the client-class processing. You can also use the extension point to change any data before the DHCP server does additional processing.

At this stage, the DHCP server determines the request type and builds an appropriate response container based on the input. For example, if the request is a DHCPDISCOVER, the server creates a DHCPOFFER response to perform the processing. If the input request is a BOOTP request, the server creates a BOOTP response to perform the response processing.

For DHCPv6, a server creates an ADVERTISE or REPLY packet, depending on the request.

The DHCP server must determine the subnet from which every request originated and map that into a set of address pools, scopes, prefixes, or links that contain IP addresses.

For DHCPv4, internal to the DHCP server is the concept of a network, which, in this context, refers to a LAN segment or physical network. In the DHCP server, every scope or prefix belongs to a single network.

Some scopes or prefixes are grouped together on the same network because their network numbers and subnet masks are identical. Others are grouped because they are related through the primary-scope or prefix pointer.

The Cisco Prime Network Registrar DHCP server determines the network to use to process a DHCP client request in the following sequence:

1. Determining the source address, either the giaddr or, if the giaddr is zero, the address of the interface on which the request arrived.
2. Using this address to search for any scope or prefix that was configured in the server that is on the same subnet as this address. If the server does not find a scope or prefix, it drops the request.
3. After finding the scope or prefix, using its network in subsequent processing.

For DHCPv6 processing, see Determining Links and Prefixes.

For DHCPv4, now that when the DHCP server establishes the network, it searches the hash table held at the network level to see if the network already knows the client-id. “Already knows,” in this context, means that this client previously received an offer or a lease on this network, and the lease was not offered to or leased by a different client since that time. Thus, a current lease or an available expired lease appears in the network level hash table. If the DHCP server finds a lease, it proceeds to the next step, which is to serialize all requests for the same IP address.

If the DHCP server does not find a lease, and if this is a BOOTP or DHCPDISCOVER request, the server looks for a reserved lease from a scope or prefix in the network.

If it finds a reserved lease, the server checks whether the scope or prefix and lease are both acceptable. The following must be true regarding the reserved lease and the scope or prefix that contains it:

• The lease must be available (not leased to another DHCP client).
• The scope or prefix must support the request type (BOOTP or DHCP).
• The scope or prefix must not be in a deactivated state.
• The lease must not be in a deactivated state.
• The selection tags must contain all of the client selection-criteria and none of the client selection-criteria-excluded.
• The scope or prefix must not be in a renew-only state.

If the reserved lease is acceptable, the server proceeds to the next step, which is to serialize all requests for the IP address. Having failed to find an existing or reserved lease for this client, the server now attempts to find any available IP addresses for this client.

The general process the DHCP server uses is to scan all of the scopes or prefixes associated with this network in round-robin order, looking for one that is acceptable for the client and also has available addresses. An acceptable scope or prefix has the following characteristics:

• If the client has selection-criteria associated with it, the selection tags must contain all of the client inclusion criteria.
• If the client has selection-criteria-excluded associated with it, the selection tags must contain none of the client exclusion criteria.
• The scope or prefix must support the client request type—If the client request is a DHCPREQUEST, you must enable the scope or prefix for DHCP. Likewise, if the request is a BOOTP request, you must enable the scope or prefix for BOOTP and dynamic BOOTP.
• It must not be in a renew-only state.
• It must not be in deactivated state.
• It must have an available address.

If the server does not find an acceptable scope or prefix, it logs a message and drops the packet.

For DHCPv6 processing, see Determining Links and Prefixes.

Because multiple DHCP requests can be in process simultaneously for one client and lease, you must serialize DHCPv4 requests at the lease level. The server queues them on the lease and processes them in the order of queueing.

For DHCPv6, the server serializes on the client (per link) and not on the lease.

For DHCPv4, the DHCP server now determines if the lease is (still) acceptable for the client. In the case where this is a newly acquired lease for a first-time client, it will be acceptable. However, in the case where the server processes a renewal for an existing lease, the acceptability criteria might have changed since the server granted the lease, and you need to check its acceptability again.

If the client has a reservation that is different from the current lease, the server first determines if the reserved lease is acceptable. The criteria for release acceptability are:

• The reserved lease must be available.
• The reserved lease must not be in a deactivated state.
• The scope or prefix must not be in a deactivated state.
• If the request is BOOTP, the scope or prefix must support BOOTP.
• If the request is DHCP, the scope or prefix must support DHCP.
• If the client has any selection-criteria, the selection tags must contain all of the client inclusion criteria.
• If the client has any selection-criteria-excluded, the selection tags must contain none of the client exclusion criteria.
• If the client previously associated with this lease is not the current client, the scope or prefix must not be in a renew-only state.

If the reserved lease meets all of these criteria, the DHCP server considers the current lease unacceptable. If there is no reserved lease for this client, or the reserved lease did not meet the criteria for acceptability, the DHCP server examines the current lease for acceptability.

The criteria for acceptability are:

• The lease must not be in a deactivated state.
• The scope or prefix must not be in a deactivated state.
• If the request is BOOTP, the scope or prefix must support BOOTP. If the request is DHCP, the scope or prefix must support DHCP.
• If the client does not have a reservation for this lease, and the request is BOOTP, the scope or prefix must support dynamic BOOTP.
• If the client does not have a reservation for this lease, no other client can either.
• If the client has any selection-criteria, the selection tags must contain all of the client inclusion criteria.
• If the client has any selection-criteria-excluded, the selection tags must contain none of the client exclusion criteria.
• If the client previously associated with this lease is not the current client, the scope or prefix must not be in a renew-only state.

Tip	At this point in the DHCP server processing, you can use the check-lease-acceptable extension point. You can use it to change the results of the acceptability test. Do this only with extreme care.

Upon determining that a lease is unacceptable, the DHCP server takes different actions, depending on the particular DHCP request currently being processed.

• DHCPDISCOVER —The DHCP server releases the current lease and attempts to acquire a different, acceptable lease for this client.
• DHCPREQUEST SELECTING —The DHCP server sends a NACK to the DHCP client because the lease is invalid. The client should then immediately issue a DISCOVER request to acquire a new DHCPOFFER.
• DHCPRENEW , DHCPREBIND —The DHCP server sends a NACK to the DHCP client to attempt to force the DHCP client into the INIT phase (attempt to force the DHCP client into issuing a DHCPDISCOVER request). The lease is still valid until the client actually issues the request.
• BOOTP —The DHCP server releases the current lease and attempts to acquire a different, acceptable lease for this client.

Caution

Take extreme care with the check-lease-acceptable extension point. If the answer the extension point returns does not match the acceptability checks in the search for an available lease performed in a DHCPDISCOVER or dynamic BOOTP request, an infinite server loop can result (either immediately or on the next DHCPDISCOVER or BOOTP request). In this case, the server would acquire a newly available lease, determine that it was not acceptable, try to acquire a newly available lease, and determine that it was not acceptable, in a continuous loop.

The DHCP server processes IPv6 lease requests by scanning the client request for IA_NA, IA_TA, and IA_PD options (see DHCPv6 Bindings). For each of these options, the server considers any leases that the client explicitly requests. If the lease already exists for the client and binding (IA option and IAID), the server determines if the lease is still acceptable. For leases that the client requests that do not already exist for the client, the server tries to give that lease to the client if:

• Another client or binding is not already using the lease.
• The prefix for the lease has the client-request flag set in its allocation-algorithms attribute.
• The lease is usable and on a usable prefix (see the DHCPv6 Prefix Usability).

Next, the server tries to assure that clients are using reservations and that a client has a usable lease with a nonzero preferred lifetime on each usable prefix on the link. Thus, the server processes each of these bindings as follows:

1. Adds any client reservations (not already in use) to the binding, provided the reservation flag is set in the prefix allocation-algorithms attribute. The server uses the first binding of the appropriate type for the reservation; that is, it uses address leases for IA_NA bindings and prefix leases for IA_PD bindings.
2. If the client has no lease with a nonzero preferred lifetime on each prefix that the client can use, the server tries to allocate a lease to the client. The prefix allocation-algorithms flags control how the server allocates the lease.

In this stage of processing, the DHCP server collects all the data to send back in the DHCP response and determines the address and port to which to send the response. You can use the pre-packet-encode extension point to change the data sent back to the DHCP client in the response, or to change the address to which to send the DHCP response. (See pre-packet-encode.)

Caution

Any packets dropped at the pre-packet-encode extension point, whether they be DHCP or BOOTP packets, still show the address to be leased in the Cisco Prime Network Registrar lease state database, for as long as the remaining lease time. Because of this, it is advisable to drop packets at an earlier point.

In this stage, the DHCP encodes the information in the response data structure into a network packet. If this DHCP client requires DNS activity, the DHCP server queues a DNS work request to the DNS processing subsystem in the DHCP server. That request runs whenever it can, but generally not before sending the packet to the client. (See pre-packet-encode.)

At this stage, the DHCP server ensures that the on-disk copy of the information is up to date with respect to the IP address before proceeding. For DHCPv6, this can involve multiple leases.

Use the post-send-packet extension point (see post-send-packet) for any processing that you want to perform outside of the serious time constraints of the DHCP request-response cycle. After the server sends the packet to the client, it calls this extension point.

Here is a simplified view of what the DHCP server does to add names to DNS:

1. Builds up a name to use for the A record —The DHCP server creates the name that it will use in the forward (A record) DNS request. For DHCPv6, these are AAAA records. The DNS name comes from a variety of sources including the client-requested-host-name and client-domain-name data items, which are usually populated from options in the DHCP request, and the DNS update configuration (including the host-name-generator/v6-host-name-generator expressions).
2. Tries to add the name, asserting that none exists yet —At this stage, the prerequisites for the DNS name update request indicate that the name should not exist. If it succeeds, the DHCP server proceeds to update the reverse record.
3. Tries to add the name, asserting that the server should supply it —The server tries to add the hostname, asserting that the host exists and has the same TXT record (or DHCID record for DHCPv6) as the one that was sent.
   • If this succeeds, the server proceeds to the next step.
   • If it fails, the server checks if it exhausted its naming retries, in which case it exits and logs an error.
   • If it did not exhaust its naming entries, it returns to the first step, which is to build up a name for the A record.

   For DHCPv6, the server uses DHCID records instead of TXT records. Also, DHCPv6 clients can have multiple leases and the forward zones can be the same or potentially different.

4. Updates the reverse record —Now that the DHCP server knows which name to associate with the reverse (PTR) record, it can update the reverse record with no prerequisites, because it can assume it is the owner of the record. If the update fails, the DHCP server logs an error.

The server calls the lease-state-change extension point whenever (and only when) a lease changes state. The existing state is in the response dictionary lease-state data item. The new state is in the environment dictionary under new-state . The new-state never equals the existing state (if it did, the server would not call the extension). You should consider this extension to be read-only and not make modifications to any dictionary items, because the server calls it in many different places. Use this extension point only for tracking changes to a lease state.

The server determines whether a lease is queued for active leasequery notifications based on the leasequery-send-all attribute of dhcp-listener. If this attribute is enabled, the DHCP server always sends a notification to an active leasequery client. If disabled or unset, the DHCP server only sends notifications which are necessary to maintain accurate state in the active leasequery client.

To allow customer written extensions to control the sending of a lease (such as only on specific state changes), a new data item, active-leasequery-control, has been added to both the request and response dictionaries. These data items have three values:

• 0—unspecified (the server determines whether to send the notification)
• 1—send (the server will send the notification)
• 2—do not send (the server will not send the notification)

The active-leasequery-control data item is initialized as 0, unspecified.

Note	These data items may be written and read, but the value that is read is only the value that might have been previously written.

These data items can force the DHCP server to take specific actions after being written, but reading them without previously writing them will always return 0, unspecified. These data items will not let you determine the choices that the DHCP server makes when it comes to deciding whether or not to send a message to an active leasequery client concerning the changes (if any) made to a lease that is being processed. Thus, these data items are technically read/write, but reading them will only allow you to determine what you may have previously written into them.

These data items are examined (the response dictionary is examined first, then the request) when the lease is written to the internal lease state database as that is when the lease is also queued for active leasequery notification. This occurs after the check-lease-acceptable and lease-state-change extensions points, but prior to the pre-packet-encode extension point. Therefore, any changes made to these attributes at or after the pre-packet-encode extension point will be ignored.

Whether a lease is queued for active leasequery notification is determined as follows:

Note	The active-leasequery-control of response and request is examined prior to any examination of the leasequery-send-all attribute.

If either of these dictionary data items has a value other than unspecified, that value will override any value configured in the leasequery-send-all attribute of the dhcp listener.

Note	You cannot control the sending of active leasequery information by writing a single extension that runs only at the lease-state-change extension point, because that extension point is only called when there is a change in state of a lease.

Lease state changes may not occur when you might expect them to. For example, if a lease is leased, and that same client goes through a DISCOVER/OFFER/REQUEST/ACK cycle, the lease-state-change extension point is not called since the lease does not actually go through a state change internally and it remains leased throughout the cycle. Thus, to gain absolute control over the transmission of information to active leasequery clients, you have to initialize the active-leasequery-control attribute in request processing, and then possibly alter it or override it by operating on the response dictionary value at the lease-state-change extension point.

Environment Dictionary

Request and Response Dictionaries

The environment dictionary is available at all extension points. It is strictly a set of name-value pairs in which both the name and the value are strings.

The DHCP server uses the environment dictionary to communicate with extensions in different ways at different extension points. At some extension points, the server places information in the environment dictionary for the extension to modify. In others, the extension can place values in the environment dictionary to control the flow or data after the extension finishes its processing.

The environment dictionary is unique in that an extension can put any name-value pair in it. Although you do not get an error for using undocumented name-value pairs, the server does not recognize them. These name-value pairs can be useful for your extension points to communicate data among them.

The DHCP server creates the environment dictionary when a DHCP request arrives and the dictionary remains with that request through the processing. Thus, an extension that runs at the post-packet-decode extension point can put data into the environment dictionary, and then an extension run at the pre-packet-encode extension point might read that data from the dictionary.

Note	The init-entry extension point has a unique environment dictionary.

Decoded DHCP Packet Data Items

Using Parameter List Option

The DHCP protocol is a request-response UDP-based protocol and, thus, the stimulation for a DHCP server operation is usually a DHCP request from a client. The result is usually a DHCP response sent back to that client.

The DHCP extension facility makes the information input in the DHCP request available to extensions at most of the extension points, and the information to be sent as a response to a DHCP request available at the pre-packet-encode extension point (see pre-packet-encode).

In addition to this DHCP packet-based information, there is additional data that the DHCP server uses when processing DHCP requests. This data becomes associated with either the DHCP request or the DHCP response as part of the architecture of the server. Much of this data is also made available to extensions, and much of it can be both read and written—in many cases altering the processing algorithms of the DHCP server.

The request and response dictionaries, therefore, contain two classes of data in each dictionary. They contain decoded packet data items as well as other request or response associated data items. The decoded packet data items are those data items directly contained in or derived from the DHCP request or DHCP response. Access to the decoded packet data items allows you to read and, in some cases, rewrite the DHCP request and DHCP response packet. The following figure shows the relationship between the request and the response dictionaries.

You can access information from the DHCP request packet, such as the giaddr, ciaddr, and all the incoming DHCP options by using the decoded packet data items in the request dictionary. Similarly, you can set the giaddr and ciaddr, and add and remove DHCP options in the outgoing DHCP response by accessing the decoded packet data items in the response dictionary.

It is important to realize that access to the packet information provided by the decoded packet data items is not all available to you. The specific data items available to that extension point are listed in the description of each extension point. Because the decoded packet data items are always accessible as a group, they are listed as a group.

You access DHCP options by name. If the option is not present, the server returns no data for that option. If you place an option into the decoded request or decoded response, it replaces any option with the same name already in the decoded request or decoded response, unless, in the put operation, you want the data specifically appended to existing data.

Some DHCP options can have multiple values. For example, the routers option can have one or more IP addresses associated with it. Access to these multiple values is by indexed operations on the option name.

Tip	A clear operation on the request or response dictionary removes all the options in the decoded packet.

There is one option, dhcp-parameter-request-list, that the DHCP server specially handles in two ways, available as either a:

• Multiple-valued option of bytes under the name dhcp-parameter-request-list.
• Blob (sequence of bytes) option under the name dhcp-parameter-request-list-blob.

You can get or put the option using either name. The DHCP server handles the dhcp-parameter-request-list (and its -blob variant as well) differently in the response dictionary than in the request dictionary. When you access this option in the request dictionary, it is just another DHCP option in the request dictionary. In the response dictionary, however, special processing takes place.

You can use the dhcp-parameter-request-list option in the response dictionary to control the order of the options returned to the DHCP or BOOTP client. When you put the option in the response dictionary, the DHCP server reorders the existing options so that the ones listed in the option are first and in the order that they appear in the list. Then, the remaining options appear in their current order after the last ones that were in the list. The DHCP server retains the list, and uses it to order any future options that it puts into the response, until it replaces the list with a new one.

When an extension does a get operation for the dhcp-parameter-request-list in the response dictionary, it does not look in the decoded response packet to find an option. Instead, the DHCP server synthesizes one that contains the list of all options currently in the decoded response packet.

init-entry

post-packet-decode

pre-packet-decode

post-class-lookup

pre-client-lookup

post-client-lookup

generate-lease

check-lease-acceptable

lease-state-change

pre-packet-encode

post-packet-encode

pre-dns-add-forward

post-send-packet

environment-destructor

The init-entry extension point is an additional one that the DHCP server calls when it configures or unconfigures the extension, which occurs when starting, stopping, or reloading the server. This entry point has the same signature as the others for the extension, but you can use only the environment dictionary. You do not configure the init-entry extension with dhcp attachExtension in the CLI, but you do so implicitly by defining an init-entry on an already configured extension. See the following table for the environment dictionary data items specific to init-entry .

Note	You must supply an init-entry extension point to enable extension points for DHCPv6 (or disable them for DHCPv4).

In addition to configuring an init-entry with the name of the entry point, you can also configure a string of arguments that the DHCP server loads in the environment dictionary under the string arguments before calling the init-entry point. Using arguments, you can create a customized extension by giving it different initialization arguments and thus not require a change to the code to elicit different behavior.

Note	The order in which the server calls extensions at the init-entry extension point can be different from reload to reload, or release to release.

Caution

An extension, when called to uninitialize, must terminate any threads it creates and clean up after itself before returning. Once the extension returns, the DHCP server unloads the extension from memory, which could result in a server failure if a thread an extension created is left running.

The dictionaries available for pre-packet-decode are request and environment.

This extension point is the first one the DHCP server encounters when a request arrives. The server calls it after receiving a packet but before it decodes the packet (at the post-packet-decode extension point). An extension can use this extension point to examine a packet and alter it before the server decodes it, or cause the server to drop it.

Two key data items in the request dictionary are for use with pre-packet-decode are client-packet and packet. These can be used to examine the received packet, modify the packet, and write it back.

Caution

The request dictionary client-packet and packet data items used for pre-packet-decode are available at any extension point that has a request dictionary. However, you should not directly alter or replace the packet at any extension point other than pre-packet-decode , because doing so can have unexpected side effects. For example, the server might never pick up the changes to the packet, or options data can change unexpectedly during processing.

An extension that uses getBytes with client-packet or packet directly alters the bytes of packet by writing into the returned buffer. However, an extension must use put or putBytes to adjust the length of the packet (and the operation can fail if the packet is too big). For DHCPv6, adjusting the length of the client portion of the packet, if relayed, requires updating the lengths in the Relay Message options in the packet.

It is up to an extension to handle parsing the packet to locate what it needs and properly alter the packet, if that is the intent.

Because the server has not yet decoded the received packet, most request dictionary data items are not available (as the server normally fills them in from the received packet). Thus, this extension point must extract data directly from the packet. The extension must also properly handle incorrectly formatted packets.

If you enable incoming-packet-detail logging, the server logs the received packet after calling the extensions registered at this extension point. If DHCP server debug tracing is configured with V is 3 or more, the server also logs the packet before calling the extensions registered for this extension point, if at least one extension is registered.

The dictionaries available for post-packet-decode are request and environment.

The dictionaries available for post-class-lookup are request and environment.

The server calls this extension point only if there is a client-class-lookup-id ; otherwise, it is similar to a post-packet-decode . The server calls the post-class-lookup extension point after evaluating the client-class-lookup-id and setting the client-class data for this client.

On input to this extension point, the environment dictionary has the drop data item set to true or false. You can change this setting by extension to drop the packet (or not drop it), and the server recognizes the change. The server also looks at the log-drop-message to decide whether to log the drop.

The extension point can also set the client-class-name in the environment dictionary, which sets the named client-class for this packet, regardless of the previous client-class. This setting has an effect only if the drop environment dictionary data item value is false on exiting the extension point.

The dictionaries available for pre-client-lookup are request and environment.

You can use this extension point only if you enabled client-class processing for your DHCP server. This extension point allows an extension to perform any or all of these actions:

• Modify the client that the server looks up during client-class processing.
• Specify individual data items to override those found from the client entry or client-class it specifies.
• Instruct the server to skip the client lookup altogether. In this case, the only client data used is data that the extension supplied in the environment dictionary.

Although the request dictionary is available to make decisions about the operation of an extension running at this extension point, the environment dictionary controls all the operations.

The environment dictionary data items in the table below are the control data items available at pre-client-lookup for clients and client-classes.

If you set the environment dictionary data items in Table 34, their values override those determined from the client lookup (either in the internal database or from LDAP). If you do not add anything to the dictionary, the server uses what is available in the client lookup.

The dictionaries available for post-client-lookup are request and environment.

You can use this extension point to examine the results of the entire client-class processing operation, and take an action based on those results. You might want to use it to rewrite some of the results, or to drop the packet. If you want to override the hostname in the packet returned from the client-class processing from an extension running at the post-client-lookup extension point, set the hostname to the client-requested-host-name data item in the request dictionary. This causes Cisco Prime Network Registrar to look to the server as though the packet came in with whatever string you specified in that data item.

You also can use this extension point to place some data items in the environment dictionary to affect the processing of an extension running at the pre-packet-encode extension point (see pre-packet-encode), where it might load different options into the response packet or take other actions.

The environment dictionary data items included in the following table are available at post-client-lookup .

The dictionaries available for generate-lease are request, response, and environment. This extension point is available for DHCPv6 only. See the table below for the environment dictionary data items that apply to this extension point.

You can use this extension point to generate a DHCPv6 address or prefix and allow the extension to control the address or prefix.

The server calls generate-lease only if the prefix is configured to allow extensions to be called during address allocation or prefix delegation—the extension flag must be set in the allocation-algorithms attribute for the prefix. When the server calls the generate-lease extension:

• The server sets the prefix context for the response dictionary to the prefix on which the lease is to be created. (Calling setObject with DEX_PREFIX and DEX_INITIAL will return to this context.)
• No lease context exists, because the server has not yet created a lease. However, lease-binding data items, in particular lease-binding-type and lease-binding-iaid are available. (Calling setObject with DEX_LEASE and DEX_INITIAL returns to this context and also sets the prefix, because a lease context sets three contexts: lease, binding, and prefix.)
• The server sets the skip-lease environment dictionary data item to false.
• The server sets the (read-only) attempts environment dictionary data item with the number of times (starting with 1) it called the extension to create this lease.
• For prefix delegation, the following environment dictionary data items are available:
  • prefix-length —Prefix length (requested or default prefix length).
  • default-prefix-length —Default prefix length (from policies).
  • longest-prefix-length —Longest allowable prefix (from policies).
  • shortest-prefix-length —Shortest allowable prefix (from policies).

When the extension returns, it can:

• Request an explicit address (for stateful address assignment) by setting the address on the generated-address environment dictionary data item. If the address is not available for the client (that is, if the address is already in use) or is not contained by the prefix, the server might call this extension again.
• Request an explicit prefix (for prefix delegation assignment) by setting the prefix on the generated-prefix environment dictionary data item. If the prefix is not available for the client or is not contained by the prefix, the server might call this extension again. The prefix is not available for the client under the following conditions:
  • if the prefix is already in use
  • if it is contained in a shorter prefix that has already been delegated
  • if a longer prefix contained in it has already been delegated by the server

The server will not reject the prefix if it is shorter or longer than allowed by the policy.

• Cause the server not to assign a lease by setting the skip-lease environment dictionary data item to true.
• Allow normal address assignment or prefix delegation to occur by not setting any of the above.

The server calls the extension point at most 500 times for each lease (this limit is the same one that currently applies when the server randomly generates leases). The server calls an extension multiple times only if the extension supplies an unusable address or delegated prefix (that is not in range for the prefix or already exists).

Note	You cannot request the server to drop the packet at this extension point.

The dictionaries available for check-lease-acceptable are request, response, and environment.

This extension point comes immediately after the server determines whether the current lease is acceptable for this client. You can use this extension to examine the results of that operation, and to cause the routine to return different results. See Determining Lease Acceptability.

The acceptable data item is available in the environment dictionary at this extension point. This is a read/write data item that the DHCP server initializes depending on if the lease is acceptable for this client. You can read and change this result in an extension. Setting the acceptable data item to true indicates that it is acceptable; setting it to false indicates that it is unacceptable.

The dictionaries available for lease-state-change are response and environment.

The server calls this extension point when a lease state changes for either all state changes or when exiting the state specified in the exiting-state environment data item (see the following table). The existing state is in the lease-state response dictionary data item. The new state is in the environment dictionary data item new-state. The server never calls the extension point if the new state matches the existing one.

Use this extension point mainly for read-only purposes, although you can place data in the environment dictionary so that other extension points can get it later.

The lease-state-change can also have a different environment dictionary, such as for lease expirations.

The current state is in the lease-state lease information data item in the response dictionary, and the state being changed to is in the environment dictionary under the new-state data item. The response lease-state and environment new-state data items are read-only.

The dictionaries available for pre-packet-encode are request, response, and environment.

Note	For DHCPv6 Reconfigure messages, there is no request dictionary (because Reconfigure is a server-initiated message). Thus, enabled extensions should check the response msg-type for ADVERTISE or REPLY or use isValid on the request to ensure that the Reconfigure message exists.

The dictionaries available for post-packet-encode are request, response, and environment.

Note	For DHCPv6 Reconfigure messages, there is no request dictionary (because Reconfigure is a server-initiated message). Thus, enabled extensions should check the response msg-type for ADVERTISE or REPLY or use isValid on the request to ensure that the request dictionary exists.

The server calls this extension point after encoding a packet, but before sending it to the client. The server can thereby examine and alter the packet before it sends the packet to the client, or the extension can cause the server to drop the packet (although the server might have made changes to its internal and on-disk data that will not be backed out if the packet is dropped).

The client-packet and packet data items were added to the response dictionary with similar behavior as described for the request dictionary in pre-packet-decode. Note that this extension point is the only one that can request the response client-packet or packet data items, because no packet exists at any other extension point. Also, the server does not process the changes made to the packet; the server simply sends the altered packet to the client.

If you enable outgoing-packet-detail logging, the server logs the packet after calling the extensions registered at this extension point. If DHCP server debug tracing is configured with X>=3, the server also logs the packet before calling the extensions registered for this extension point, but only if at least one extension is registered.

Instead of using the pre-dns-add-forward extension point, you can use the host-name-generator (for DHCPv4) and v6-host-name-generator (for DHCPv6) expressions configurable on the DNS update configurations.

Note

The pre-dns-add-forward extension point is deprecated and documentation for it removed. A future Cisco Prime Network Registrar release may remove the extension point completely. Instead, use an earlier request extension point (such as post-client-lookup ) to set the required options, such as the client-fqdn option.

Use the post-send-packet extension point for any processing that you want to perform outside of the serious time constraints of the DHCP request-response cycle. After the server sends the packet to the client, it calls this extension point.

Note	For DHCPv6 Reconfigure messages, there is no request dictionary (because Reconfigure is a server-initiated message). Thus, enabled extensions should check the response msg-type for ADVERTISE or REPLY or use isValid on the request to ensure that the request dictionary exists.

The environment-destructor extension point allows an extension to clean up any context that it might be holding. The only dictionary available for this extension point is environment.

The environment dictionary is available for all extension points called for a single client request. Because some extensions may need to maintain context information between the multiple extension points called for a single client request, and because the server might drop requests at several places during processing, an extension cannot reliably release context that it might have created for that request. The environment-destructor extension point now makes it possible to reliably remove this context when processing of a request has completed, for whatever reason.

Note	The server calls all extensions attached to the environment-destructor extension point, even if the server did not call each extension at any other attachment point.