DHCPv6 Server

Jump to: navigation, search

DHCPv6 server Description

This section of the manual describes the general usage and operation of the DHCPv6 server which implements RFC 3315. For an overview of the DHCPv6 protocol from the client's perspective, please see DHCP client. For the Lightweight DHCPv6 Relay Agent (RFC 6221), see Lightweight DHCPv6 Relay Agent.

Introduction

The Dynamic Host Configuration Protocol for IPv6 (DHCPv6) enables DHCP servers to pass configuration parameters such as IPv6 network addresses to IPv6 nodes. It offers the capability of automatic allocation of reusable network addresses and additional configuration flexibility. This protocol is a stateful counterpart to "IPv6 Stateless Address Autoconfiguration" (RFC 2462), and can be used separately or concurrently with the latter to obtain configuration parameters.

The DHCP server assigns IPv6 configuration information to DHCPv6 clients. It manages address assignment within a given range on each interface it is configured.

Protocol Operation

When started, the DHCP server will listen on the default UDP port 547 or a port specified by the user code. It receives DHCPv6 client requests and responds to them according to its configuration address range and information.

When an assigned address is expired and there is no unassigned addresses left, the server will reassign it to other clients.

If a file system is presented and the compile time macro TM_DHCPD_USE_FS is defined, the DHCPv6 server persists all lease information on the file system. When the server is stopped and restarted, all saved lease will be loaded into the memory.

Compiling the DHCPv6 Server

The DHCPv6 server code is encapsulated by the macro TM_6_USE_DHCP_SERVER. This macro must be defined in <trsystem.h> to include the DHCPv6 server code when compiling the stack.

The DHCPv6 server can load configuration from either a file, or a string buffer. It also uses the file system to save the leases. Both of these two features require the presence of a file system. Macro TM_DHCPD_USE_FS must be defined in <trsystem.h> to include the file system related DHCPv6 server code when compiling the stack.

Note Note: The DHCPv4 server and the Lightweight DHCPv6 Relay Agent share this macro.

Configuring the DHCPv6 Server

Before starting the DHCP server, the DHCPv6 server must be configured by calling either tf6DhcpdUserConfigFromFile() or tf6DhcpdUserConfigFromBuffer(). Otherwise tf6DhcpdUserStart() will return TM_ENOENT

Below is a sample showing the simple format of the configuration file. The leading spaces and new line characters are decorative and optional.

interface eth0;
{
    start-address 2001::1:1000;
    end-address 2001::1:2000;
    server-preference 255;
    max-clients 255;
    must-accept-reconfig false;
    allow-rapid-commit true;
    lease-time 86400;
    lease-file files\\dhcpv6_leases_eth0.txt;
    dns-server 2001:db8::6 2001:db8::7;
}
 
interface eth1;
{
    start-address 2001::2:1000;
    end-address 2001::2:2000;
    server-preference 255;
    max-clients 255;
    must-accept-reconfig false;
    allow-rapid-commit true;
    lease-time 86400;
    lease-file files\\dhcpv6_leases_eth1.txt;
}

Start the DHCPv6 server

After the server is configured, tf6DhcpdUserStart() can be called to start the server.

Execute the DHCPv6 server

After the server is started, tf6DhcpdUserExecute() should be called in order for the incoming requests to be processed. This function picks up incoming packets, processes them, update the leases in memory and lease file if necessary, and send reply back to the requesting DHCPv6 client if needed. In blocking mode, it should be called in a a separate task/thread. It'll run in an infinite loop until the server is stopped. In non-blocking mode, it should be called periodically in your main loop.

Stop the DHCPv6 server

tf6DhcpdUserStop() can be called to stop the server. All current leases will be saved into the lease file.

Usage Scenario

This is a common usage scenario for the DHCP server:

  1. Call tf6DhcpdUserConfigFromFile() or tf6DhcpdUserConfigFromBuffer() to configure the DHCPv6 server.
  2. Call tf6DhcpdUserStart() to start the server.
  3. Call tf6DhcpdUserExecute() periocially in non-blocking mode or call once in a separate task/thread in blocking mode
  4. Call tf6DhcpdUserStop() to stop the server

Macro Reference

These macros can be defined in <trsystem.h> to affect the behavior of the DHCP server.

For more details see the DHCPv6 Option Macros section of the Compile Time Macros page.

TM_6_USE_DHCP_SERVER
TM_DHCPD_USE_FS

Function Reference

tf6DhcpdUserConfigFromFile()
tf6DhcpdUserConfigFromBuffer()
tf6DhcpdUserStart()
tf6DhcpdUserExecute()
tf6DhcpdUserStop()


User Application Code Example

Non-blocking mode example:

int errorCode;
 
/* Load DHCPv6 configuration from a file */
errorCode = tf6DhcpdUserConfigFromFile("files\\dhcpv6d.conf.txt");
 
if(errorCode != TM_ENOERROR)
{
/* Start the DHCPv6 server on the default port in non-blocking mode*/
    errorCode = tf6DhcpdUserStart(0, 0);
}
 
/* Main program loop
while(...)
{
    ... 
/* Process DHCPv6 incoming packets */    
    errorCode = tf6DhcpdUserExecute();
    ...
}
 
/* Stop the DHCPv6 server */
errorCode = tf6DhcpdUserStop();

Blocking mode example:

Main task/thread:

/* Load DHCPv6 configuration from a file */
errorCode = tf6DhcpdUserConfigFromFile("files\\dhcpv6d.conf.txt");
 
if(errorCode != TM_ENOERROR)
{
/* Start the DHCPv6 server on the default port in blocking mode */
    errorCode = tf6DhcpdUserStart(0, TM_BLOCKING_ON);
}
 
...
 
/* Stop the DHCPv6 server */
errorCode = tf6DhcpdUserStop();


Another task/thread:

/* Process DHCPv6 incoming packets */    
/* Will block until tf6DhcpdUserStop is called in the main task/thread */    
    errorCode = tf6DhcpdUserExecute();
    ...