Cisco Prime Network Registrar (CPNR) is a high-performance, fast and extremely reliable product that allows companies to implement Domain Name System (DNS), Dynamic Host Configuration Protocol (DHCP) and IP Address Management (IPAM) services for both IPv4 and IPv6 networks.
If you’re a developer who’s always working to stay up to date and be aware of the latest technology, we’d like to talk with you. Are you looking for a challenging opportunity to further your career? Check out our open positions.
Extension points
One of CPNR’s major capabilities is to provide users with extension points to manipulate how CPNR handles and responds to device requests and that allows the application to change DHCP behavior, and process the information in a way that aligns the company requirements. Basically, it allows programmers to define what to do instead of what is already doing on the DHCP server. These extension points can be defined both to DHCPv4 and DHCPv6.
So, you can code what you want in these extension points to give value to the DHCP processes and it can be done in Tcl or C/C++. However, have in mind that C/C++ provides better performance and flexibility despite the API is more complex than Tcl API.
First of all, you have to think and determine the task to perform, that is, what DHCP packet do you want to extend and how it would work. After that, we need to determine the extension point that will be used. We have a list of extension points and they are all different. After coding it in C++, it must be compiled and then it must be added to the DHCP server configuration. Finally, we need to attach the written extension to the extension point and reload the DHCP server to see the changes and perform a variety of tests to be sure its functionality aligns with what we wanted to achieve.
Multiple extensions can be associated with one extension point and each developed extension would be executed in a specific order and it depends on a sequence number established when the attachment is created in the server. This sequence number is necessary when you attach more than one extension point to one extension point, and the number goes from 1 to 32.
You can develop and apply an extension to these DHCP server processing points, from receiving a request to responding to the client:
- Receive and decode the packet
- Look up, modify, and process any client-class
- Build a response type
- Determine the subnet (or link, in the case of DHCPv6)
- Find any existing leases
- Serialize the lease requests
- Determine the lease acceptability for the client
- Gather and encode the response packet
- Update stable storage of the packet
- Return the packet
The extension developed must be defined as a routine in a file, which can contain multiple extension functions. Then you attach the extension to one or more DHCP server extension points. So, when the DHCP server reaches the extension point, it calls the routine that the extension defines. The routine can return a success or failure.
In C/C++ the routine signature is like this:
typedef int (DEXAPI * DexEntryPointFunction)(
int iExtensionPoint,
dex_AttributeDictionary_t* pRequest,
dex_AttributeDictionary_t* pResponse,
dex_EnvironmentDictionary_t* pEnviron);
The integer is the extension point number, and the other three pointers are the structures for request, response, and environment.
You can find examples of this in /opt/nwreg2/examples/dhcp/dex directory.
Communication with other servers
Extensions can communicate with external servers or databases if you want, to alter the client class or validate incoming DHCP client requests. But you have to be careful to preserve the DHCP performance. If these communications take more than 50 to 100 ms, that can seriously affect the server performance.
So, my advice is to write the extension using multithreading and when establishing the communication with external servers, do it in an asynchronous way, maybe using a caching method.
Thread-safe
We know that the DHCP server is multithreaded, so our extensions must be capable of managing that. If not we can cause memory corruptions, failures and more. So we need to be careful and write strong and well-tested code. Our C++ shared library runs in the same address space as the DHCP server, and receives pointers to structures in the DHCP server, so any bug in the extension can break the DHCP server memory.
It is a good practice to write the extension in Tcl and then in C++ for better performance.
Stages and available extension points
Extension points are tied to the processing of requests from DHCP clients.
These requests come in 3 stages:
- Initial request
- DHCPv4 or DHCPv6 processing
- Final response
Here is a list of available extension points for each stage and processing step.
Stage 1 – Initial request
Client Request Stage | Available Extension Point |
1. Receive a packet from a DHCP client. | pre-packet-decode |
2. Decode the packet. | post-packet-decode |
3. Determines the client-classes. | – |
4. Modifies the client-class. | post-class-lookup |
5. Processes the client-classes, looking up clients. | pre-client-lookup
post-client-lookup |
6. Build a response container from the request. | – |
Stage 2 – DHCPv4 or DHCPv6 processing
Client Request Stage | Available Extension Point |
1. (DHCPv4) find a lease associated with this client or locate a new lease | – |
2. Serialize all requests associated with this client | – |
3. (DHCPv6) processes the client request, generating leases | generate-lease lease-state-change |
4. Determine if the lease is acceptable for this client | check-lease-acceptable |
5. DNS update operations as necessary | – |
Stage 3 – Final response
Client Response Stage | Available Extension Point |
1. Gather all data to include in the response packet. | – |
2. Write lease to database. | – |
3. Prepare the response packet for encoding. | pre-packet-encode |
4. Encode the response packet for transmission to the client. | post-packet-encode |
5. Send the packet to the client. | post-send-packet |
6. Release all context | environment-destructor |
Conclusion
CPNR brings us the possibility to change its DHCP native functionalities attaching our own code to a variety of extension points. This is an utterly helpful tool that allows us to manipulate requests and response packets and process them aligned to our company’s benefit.
If you’re a developer who’s always working to stay up to date and be aware of the latest technology, we’d like to talk with you. Are you looking for a challenging opportunity to further your career? Check out our open positions.