Lightweight DHCPv6 Relay Agent
Contents
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: | 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 :
- Call tf6DhcprUserConfigFromFile() or tf6DhcprUserConfigFromBuffer() to configure the LDRA.
- Call tf6DhcprUserStart() to start the LDRA.
- Call tf6DhcprUserExecute() periocially in non-blocking mode or call once in a sperate task/thread in blocking mode
- 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.
Function Reference
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(); ...