DHCP Server

Jump to: navigation, search

Table of Contents >> Optional Protocols

The Dynamic Host Configuration Protocol (DHCP) Server allows a DHCP client to obtain a useful IP address, and other configuration parameters without having any knowledge about the subnet to which the DHCP client interface is connected.

The Treck DHCP sever also supports the DHCPINFORM message, which allows a DHCP client user to obtain static configuration information (e.g. IP addresses for routers and DNS servers) from the Treck DHCP Server without having an IP address dynamically allocated by the server. Presumably, the DHCP client user would obtain an IP address in some other manner and configure the address manually.


DHCP Server Code Configuration

The Treck DHCP server, the associated code will be disabled by default. You can adjust the Treck DHCP server behavior and code size by defining or commenting out the following DHCP macros in your trsystem.h.

TM_USE_DHCP_SERVER Enable DHCP Server. Uncomment this macro in trsystem.h to enable all Treck DHCP server code in your build.

Default: undefined

TM_DHCPD_USE_FS Enable the DHCP Server file system interface. Uncomment this macro in trsystem.h if you need the DHCP server file interface.

Default: undefined

Configuring the DHCP Server

The DHCP server must be configured by calling either tfDhcpdUserConfigFromFile(), if a file system is available, or tfDhcpdUserConfigFromBuffer() otherwise. The configuration should be done prior to calling tfDhcpdUserStart(), so that the DHCP server will have DHCP configuration information and parameters to give to the DHCP clients. The DHCP server will listen for incoming DHCP client messages on all interfaces, but will respond only on DHCP configured interfaces.

DHCP Server configuration file format

The DHCP server configuration file consists of a series of lines with or without leading spaces. Comment lines start with the '#' character, and are ignored. Non comment lines start with a keyword followed by one or more values and the ';' character. 'option' is a special keyword followed by an option name, and value.

The following keywords are recognized:

   "host"
   "interface"
   "range"
   "default-lease-time"
   "max-lease-time"
   "max-clients"
   "sname"
   "file"
   "siaddr"
   "hardware ethernet"
   "ethernet"
   "fixed-address"

The following DHCP protocol option names are recognized. Each one must be preceded by the keyword 'option' as shown below:

   "option subnet-mask"
   "option routers"
   "option domain-name-servers"
   "option domain-name"
   "option boot-file-size"
   "option ip_forwarding"
   "option domain-search"
   "option broadcast-address"
   "option ntp-servers"
   "option netbios-name-servers"
   "option host-name"

The keywords 'interface' and 'host' are special keywords. They start a new subsection. The 'interface', and 'host' lines must end with the '{' character which marks the beginning of the subsection. The end of the subsection is marked by a line containing the '}' and nothing else. An interface subsection contains configuration lines that are relevant only for that interface. The interface keyword must be followed by an interface name that matches the name given to the tfAddInterface() API Similarly a host subsection contains configuration lines that are relevant only for that host. There may be multiple interface subsections, and multiple host subsections. If there is no interface sub-section, then the configuration lines apply to all the interfaces. All other lines in the configuration file must end with the semi-colon ';' character. The 'range' configuration keyword allows the user to specify a range of IP addresses that the DHCP server can attribute to DHCP clients. The 'fixed-addres' configuration keyword (placed inside a host sub-section) allows the DHCP server to attribute a fixed IP address for a given host. This is very useful when a fixed address is desired for a printer for example.

DHCP Server configuration file example

Below ia a DHCP configuration file sample. The leading spaces are optional.

# Sample dhcpd.conf
# (add your comments here) 
 
interface "Server" { 
# The range of IP addresses the server
# will issue to DHCP enabled PC clients
# booting up on the network
range 192.168.1.201 192.168.1.220;
# Set the amount of time in seconds that
# a client may keep the IP address
default-lease-time 86400;
max-lease-time 86400;
max-clients 255;
# Set the default gateway to be used by
# the PC clients
option routers 192.168.1.1;
# Set the broadcast address and subnet mask
# to be used by the DHCP clients
option broadcast-address 192.168.1.255;
option subnet-mask 255.255.255.0;
   # Set the DNS server to be used by the
   # DHCP clients
option domain-name-servers 192.168.1.100, 192.168.1.200;
   # You can also assign specific IP addresses based on the clients''
   # ethernet MAC address as follows (Host''s name is "laser-printer":
 
  host laser-printer {
      hardware ethernet 08:00:2b:4c:59:23;
      option subnet-mask 255.255.255.252;
      fixed-address 192.168.1.222;
   }
# Set the NTP server to be used by the
# DHCP clients
option ntp-servers 192.168.1.100;
option domain-name "mydomain.org";
}

DHCP Server configuration when no File System is available

When no File System is available, the user can configure the DHCP server by calling tfDhcpdUserConfigFromBuffer() multiple times.

Adding custom, or unsupported DHCP option

The user can add a DHCP option (in the RFC 2132 format) when it is not supported by the current configuration file or buffer format, by calling tfDhcpdUserSetOption()

Running the DHCP server

Starting the DHCP server

After the DHCP server has been configured, tfDhcpdUserStart() can be called to start the server.

Executing the DHCP server

After the server has been started, tfDhcpdUserExecute() should be called so that incoming requests can be processed. This function receives incoming packets, processes them, updates the leases and lease file if necessary, and sends appropriate replies back to the requesting DHCP client(s).

DHCP server execution mode

The DHCP server can be started in either blocking mode, or non-blocking mode. The blocking mode is set when calling tfDhcpdUserStart(). In blocking mode, tfDhcpdUserExecute() should be called once in its own thread. In a loop, the function will either process incoming packets, or block if there is none, until tfDhcpdUserStop() is called. In non blocking mode, tfDhcpdUserExecute() should be called from your main loop. It will process incoming packets, and return when done.

Stopping the DHCP server

tfDhcpdUserStop() can be called to stop the DHCP server. All current leases will be saved into a file. All internal DHCP server buffers will be freed.

Usage Scenario

Common usage scenario for the DHCP server:

  1. Call tfDhcpdUserConfigFromFile() or tfDhcpdUserConfigFromBuffer() to load the DHCP server configuration.
  2. Optionally call tfDhcpdUserSetOption() to load the DHCP server with an option not supported in the configuration file/buffer format.
  3. Call tfDhcpdUserStart() to start the server.
  4. Call tfDhcpdUserExecute() periodically in non-blocking mode or once in a separate task/thread in blocking mode
  5. Call tfDhcpdUserStop() to stop the server, and free all memory allocated by the server (including loaded configuration.)

Function Calls