1.2.1.5 DHCP Server Module (V2)
The DHCP Server module is used to assign IP addresses to DHCP clients from the configured IP address database. When the server receives a request from a client, the DHCP server determines the network to which the DHCP client is connected, and then allocates an IP address that is appropriate for the client, and sends configuration information appropriate for that client. DHCP servers typically grant IP addresses to clients only for a limited interval. DHCP clients are responsible for renewing their IP address before that interval has expired, and must stop using the address once the interval has expired, if they have not been able to renew it.
The DHCP server module implements the 'RFC 2131 - Dynamic Host Configuration Protocol' standard. It assigns an IP address to a requesting DHCP client. The server address range is defined when the module is configured.
Some of the known issues and implementation limitations:
there is no support for multiple sub-net pools
Operation for clients using relay agents may be impacted The server will assign a lease in the server network, not in the relay agent 'down link' network
Abstraction Model
This module provides software abstraction of the DHCP Server module existent in any TCP/IP Stack implementation. It removes the overhead of address configuration from all other clients on the local network
How the Library Works
To use DHCP Server, include the files dhcp_server.c, and dhcp_server.h in your project, and add or uncomment the definition "#define TCPIP_STACK_USE_DHCP_SERVER_V2" to configuration.h. You should use a configuration tool (MHC, MCC).
The DHCP Server module will assign IP addresses to DHCP clients from the configured IP address database.
When the server receives a request from a client, the DHCP server allocates an IP address that is appropriate for the client, and sends configuration information appropriate for that client.
The IP addresses will be granted for a limited interval. DHCP clients are responsible for renewing their IP address before that interval has expired.
A DHCP client must stop using the leased address once the interval has expired, if they have not been able to renew it.
Library Interface
| Name | Description |
|---|---|
| Macros | |
| TCPIP_DHCPS_TASK_PROCESS_RATE | DHCPS task processing rate, in milliseconds. |
| The DHCPS module will process a timer event with this rate for maintaining its own queues, processing timeouts, etc. | |
| Choose it so that the other TMO are multiple of this | |
| The default value is 200 milliseconds. | |
| The lower the rate (higher the frequency) the higher the module priority and higher module performance can be obtained | |
| The value cannot be lower than the TCPIP_STACK_TICK_RATE. | |
| TCPIP_DHCPS_CLIENT_ID_MAX_SIZE | Maximum size of the client identifier field |
| Needs to be >= size of a MAC Address | |
| Note: when a client is requesting a lease using a longer client ID, the ID will be truncated! | |
| TCPIP_DHCPS_INTERFACE_COUNT | Maximum number of interfaces on which DHCPs could run for this build |
| Note that this could be less than the maximum number of interfaces in the stack for this build (TCPIP_STACK_NETWORK_INTERAFCE_COUNT)! | |
| TCPIP_DHCPS_MAX_LEASES | Maximum number of leases that the DHCP server can support for an interface |
| The actual number of leases per interface could be smaller than this | |
| Multiple of 32 | |
| TCPIP_DHCPS_ICMP_ECHO_DATA_SIZE | Size of the buffer when sending a ICMP echo request for address conflict detection |
| Should be between 8 and 32 bytes | |
| TCPIP_DHCPS_ICMP_ECHO_RETRIES | number of retries if ICMP is not able to send a ping |
| This should only happen if there are too many ICMP echo requests ongoing | |
| TCPIP_DHCPS_OPTION_ROUTER_VALUES | Maximum number of router values to be sent to clients |
| A value defined as 0 excludes that option | |
| TCPIP_DHCPS_OPTION_DNS_VALUES | Maximum number of DNS values to be sent to clients |
| A value defined as 0 excludes that option | |
| TCPIP_DHCPS_OPTION_TIME_SERVER_VALUES | Maximum number of time server values to be sent to clients |
| A value defined as 0 excludes that option | |
| TCPIP_DHCPS_OPTION_NAME_SERVER_VALUES | Maximum number of name server values to be sent to clients |
| A value defined as 0 excludes that option | |
| TCPIP_DHCPS_OPTION_NTP_SERVER_VALUES | Maximum number of NTP server values to be sent to clients |
| A value defined as 0 excludes that option | |
| TCPIP_DHCPS_OPTION_T1_T2_SUPPRESS | Suppress the 'renewal T1' and 'rebinding T2' options when replying to a client request |
| By default these options are enabled | |
| TCPIP_DHCPS_REPORT_ERROR_EVENT | Enable the report of error events using the event notification mechanism |
| TCPIP_DHCPS_REPORT_CLIENT_EVENT | Enable the report of client events using the event notification mechanism |
| TCPIP_DHCPS_MAX_EVENT_REGISTRATIONS | Maximum number of event registrations |
| If 0 or not defined, there is no event registration | |
| TCPIP_DHCPS_ENABLE_STATISTICS | Maintain DHCPs statistics counts |
| TCPIP_DHCPS_DYNAMIC_DB_ACCESS | Allow dynamic manipulation of the DHCPs DB |
| TCPIP_DHCPS_MULTI_THREADED_ACCESS | Enable multi-threaded access |
| API Functions | |
| TCPIP_DHCPS_IsEnabled | Determines if the DHCP Server is enabled on the specified interface. |
| TCPIP_DHCPS_Disable | Disables the DHCP Server for the specified interface. |
| TCPIP_DHCPS_Enable | Enables the DHCP Server for the specified interface. |
| TCPIP_DHCPS_LeaseEntriesGet | Get the total and in use number of lease entries for the selected interface. |
| TCPIP_DHCPS_LeaseGetInfo | Get the lease entry details for the requested lease index |
| TCPIP_DHCPS_LeaseGetInfoById | Get the lease entry details for the requested client ID |
| TCPIP_DHCPS_LeaseRemove | Remove one entry from the DHCP server DB |
| TCPIP_DHCPS_LeaseRemoveById | Remove one entry from the DHCP server DB |
| TCPIP_DHCPS_LeaseRemoveAll | Remove all entries from the DHCP server DB |
| TCPIP_DHCPS_LeaseAddById | Add a lease to the DHCP server DB |
| TCPIP_DHCPS_Configure | Configure the DHCP server on multiple interfaces |
| TCPIP_DHCPS_StatisticsDataGet | Returns the DHCPS statistics data |
| TCPIP_DHCPS_HandlerRegister | Registers a DHCP server Handler |
| TCPIP_DHCPS_HandlerDeRegister | Deregisters a previously registered DHCP handler |
| TCPIP_DHCPS_Task | Standard TCP/IP stack module task function |
| Data Types and Constants | |
| TCPIP_DHCPS_CONFIG_FLAGS | DHCP server configuration flags for a specific interface |
| TCPIP_DHCPS_CLIENT_OPTION_TYPE | DHCP server options to be provided to the clients for a specific interface. |
| TCPIP_DHCPS_CLIENT_OPTION_CONFIG | DHCP server configuration of client options |
| TCPIP_DHCPS_INTERFACE_CONFIG | DHCP server configuration for a specific interface. |
| TCPIP_DHCPS_MODULE_CONFIG | DHCP Server module runtime and initialization configuration data. |
| TCPIP_DHCPS_RES | DHCPs operation result |
| TCPIP_DHCPS_REQ_FORMAT_ERR_MASK | DHCPs error mask for a TCPIP_DHCPS_EVENT_REQ_FORMAT_ERROR event |
| TCPIP_DHCPS_EVENT_TYPE | A DHCP Server reported event. |
| TCPIP_DHCPS_EVENT_HANDLE | DHCP server event handle |
| TCPIP_DHCPS_EVENT_HANDLER | DHCP event handler prototype. |
| TCPIP_DHCPS_LEASE_STATE | DHCP Server lease state |
| TCPIP_DHCPS_LEASE_INFO | DHCP Server module lease data |
| TCPIP_DHCPS_LEASE_SET | DHCP Server module lease set data |
| TCPIP_DHCPS_STATISTICS_DATA | DHCP Server module statistics data |