Lightweight DHCPv6 Relay Agent

Jump to: navigation, search

Lightweight DHCPv6 Relay Agent Description

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

Introduction

DHCPv6 Relay Agents are deployed to forward DHCPv6 messages between clients and servers when they are not on the same IPv6 link and are often implemented alongside a routing function in a common node. A Lightweight DHCPv6 Relay Agent(LDRA) allows Relay Agent Information to be inserted by an access node that performs a link- layer bridging (i.e., non-routing) function. An LDRA resides on the same IPv6 link as the client and a DHCPv6 Relay Agent or server, and is functionally the equivalent of the Layer 2 Relay Agent proposed for DHCPv4 operation.

Protocol Operation

When started, the LDRA will listen on the default UDP port 547 or a port specified by the user code. It receives DHCPv6 client requests and forward them to the network facing interface in a RELAY-FORWARD message encapsulating the original request (SOLICIT, REQUEST, DECLINE, RENEW, REBIND, INFO-REQUEST, CONFIRM, etc). When a server responds back with RELAY-REPLY message, the LDRA will extract the encapsulated message and forward it back to the client which originally made the request.

Compiling the LDRA

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

The LDRA can load configuration from either a file or a string buffer. A file system is requred to use the configuration file. Macro TM_DHCPD_USE_FS must be defined in <trsystem.h> to include the file system related LDRA code when compiling the stack.

Note Note: The DHCP v4 server and DHCPv6 Server share this macro.

Configuring the LDRA

Before starting the LDRA, it must be configured by calling either tf6DhcprUserConfigFromFile() or tf6DhcprUserConfigFromBuffer(). Otherwise tf6DhcprUserStart() 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;
{
  facing client;
  trusted yes;
}
 
interface eth1;
{
  facing network;
  trusted no;
}

The LDRA MUST have each of its interfaces configured as either client-facing or network-facing, either trusted or not untrusted.

The LDRA receives request from the client-facing interfaces and forward them on to the network-facing interfaces, and relays back server responses. It discards all packets from the other direction.

When a client-facing interface is configured as untrusted, the LDRA MUST discard any message of type RELAY-FORW received from the that interface.

Start the LDRA

After being configured, tf6DhcprUserStart() can be called to start the LDRA.

Execute the LDRA

After the LDRA is started, tf6DhcprUserExecute() should be called in order for the incoming requests to be processed. This function picks up incoming packets, processes them, and relay either to the server or the client. In blocking mode, it should be called in a seperate task/thread. It'll run in an infinite loop until the LDRA is stopped. In non-blocking mode, it should be called perodically in your main loop.

Stop the LDRA

tf6DhcprUserStop() can be called to stop the LDRA.

Usage Scenario

This is a common usage scenario for the LDRA :

  1. Call tf6DhcprUserConfigFromFile() or tf6DhcprUserConfigFromBuffer() to configure the LDRA.
  2. Call tf6DhcprUserStart() to start the LDRA.
  3. Call tf6DhcprUserExecute() periocially in non-blocking mode or call once in a sperate task/thread in blocking mode
  4. Call tf6DhcprUserStop() to stop the LDRA

Macro Reference

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

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

TM_6_USE_DHCP_RELAY
TM_DHCPD_USE_FS

Function Reference

tf6DhcprUserConfigFromFile()
tf6DhcprUserConfigFromBuffer()
tf6DhcprUserStart()
tf6DhcprUserExecute()
tf6DhcprUserStop()


User Application Code Example

Non-blocking mode example:

int errorCode;
 
/* Load LDRA configuration from a file */
errorCode = tf6DhcprUserConfigFromFile("files\\dhcpv6r.conf.txt");
 
if(errorCode != TM_ENOERROR)
{
/* Start the LDRA on the default port in non-blocking mode*/
    errorCode = tf6DhcprUserStart(0, 0);
}
 
/* Main program loop
while(...)
{
    ... 
/* Process LDRA incoming packets */    
    errorCode = tf6DhcprUserExecute();
    ...
}
 
/* Stop the LDRA */
errorCode = tf6DhcprUserStop();

Blocking mode example:

Main task/thread:

/* Load LDRA configuration from a file */
errorCode = tf6DhcprUserConfigFromFile("files\\dhcpv6r.conf.txt");
 
if(errorCode != TM_ENOERROR)
{
/* Start the LDRA on the default port in blocking mode */
    errorCode = tf6DhcprUserStart(0, TM_BLOCKING_ON);
}
 
...
 
/* Stop the LDRA */
errorCode = tf6DhcprUserStop();


Another task/thread:

/* Process LDRA incoming packets */    
/* Will block until tf6DhcprUserStop is called in the main task/thread */    
    errorCode = tf6DhcprUserExecute();
    ...