dhcprelay

DHCP relay agent

Syntax:

You must be root to run this utility.

dhcprelay [-a] [-A value] [-d] [-D] [-q] [-i en0] 
[... -i enX] [-p port] [-pf pid-file] 
[-m] dhcp-server1 [... serverX] 

Runs on:

All supported platforms.

Options:

-a

Append an agent option field to each request before forwarding it to the server.

-A value

Support maximum packet size (default is 576).

-d

Don't move to the background. This is useful when running dhcprelay under a debugger.

-D

Drop packets that don't contain a relay agent information option field for this agent.

-i interface

Specify the interface(s) that dhcprelay will service. By default, dhcprelay listens for DHCP packets on all interfaces capable of handling broadcast messages. If you want to prevent certain interfaces from accessing DHCP relay services, use this option to specify the interfaces dhcprelay will listen on.

-p port

The UDP receiving port that dhcprelay will listen to. By default, dhcprelay listens for datagrams on port 67 or as specified in /etc/services. The port dhcprelay transmits on is the one with the next highest number (e.g. if dhcprelay receives on port 67, it transmits on port 68). This option is mostly used for debugging purposes.

-pf file

An alternative file to store the PID of dhcprelay. The default is /var/run/dhcprelay.pid.

-q

Quiet mode. Use when you want to avoid printing on startup (e.g. when starting dhcprelay from a script).

-mappend|replace|forward|discard

Take action if a packet is received with the gateway address (giaddr) set.

dhcp-server1 [... serverX]

You must specify the IP address of at least one DHCP server where client requests will be forwarded to.

Description:

The dhcprelay DHCP relay agent relays DHCP and BOOTP requests from a subnet that doesn't have a DHCP server to one that does.

The agent normally runs in the foreground until it has configured an interface, and then runs as a daemon in the background.

The dhcprelay daemon listens for DHCP requests on all interfaces attached to a host (or those specified by the -i option).

When a query is received, dhcprelay forwards it to the list of DHCP servers specified on the command line. When a reply is received, it is broadcast or unicast on the network where the original request came.

Relay agent information options

When you set the -a flag, the relay agent appends an agent option field to each request before forwarding it to the server. In responses back to the client from the server, the agent option fields are stripped.

The agent option field contains two agent options: the circuit ID suboption and the agent ID suboption. Currently, the circuit ID is the printable name of the interface on which the client request is received. The agent ID is the value that the relay agent stores in the DHCP packet's giaddr field. The client supports inclusion of a remote ID suboption as well, but this is not used by default.

The agent ID suboption is not defined in the current relay agent information option draft (draft-ietf-dhc-agent-options-03.txt), but has been proposed for inclusion in the next draft.

Relay agent options are added to a DHCP packet without the knowledge of the DHCP client. If the client has filled the DHCP packet option buffer completely, then there's no space to add agent options. The DHCP server, however, can handle a much larger packet than most DHCP clients send. The current agent options draft requires that the relay agent use a maximum packet size of 576 bytes.

With the Internet software consortium DHCP server, we recommend that you set the maximum packet size to about 1400, allowing plenty of extra space in which the relay agent can put the agent option field, while still fitting into the Ethernet MTU size. You can do this by specifying the -A flag, followed by the desired maximum packet size (e.g. 1400).

It's reasonably safe to do even if the MTU between the server and the client is less than 1500, as long as the hosts on which the server and client are running support IP fragmentation (and they should). With some knowledge as to how large the agent options might get in a particular configuration, this parameter can be tuned as finely as necessary.

It's possible for a relay agent to receive a packet that contains an agent option field. If this packet doesn't have a giaddr set, the packet is discarded.

If giaddr is set, the server may handle the situation in one of four ways. It may:

• append its own set of relay options to the packet, leaving the supplied option field intact
• replace the existing agent option field
• forward the packet unchanged
• discard it.

To do the above, use the -m flag with one of the arguments: append, replace, forward, or discard.

The relay agent usually scans a response from a server and removes the relay agent information option if the relay agent information option processing is enabled. However, if it finds a relay agent information option field containing an agent ID suboption that matches one of its IP addresses, that is recognized as its own. If no such option is found, the relay agent can either drop the packet or relay it anyway. If the -D option is specified, all packets that don't contain a match are dropped.

Specifying DHCP servers

You must specify on the command line the name or IP address of at least one DHCP server to which DHCP and BOOTP requests should be relayed.

Examples:

Start dhcprelay using defaults:

dhcprelay 10.0.0.1

Start dhcprelay in quiet mode, servicing only en0:

dhcprelay -q -i en0 10.0.0.1

Errors:

When an error occurs, dhcprelay sends a description of the error to syslogd and stderr only if dhcprelay is running on the foreground.

Author:

Ted Lemon in cooperation with Vixie Enterprises.

License:

This utility is based on copyright software of The Internet Software Consortium; for the copyright notice, see dhcprelay in the appendix Third-Party Copyright Notices.

Caveats:

The tiny stack (npm-ttcpip.so) does not support dhcprelay.

See also:

dhcp.client, dhcpd, syslogd.

RFC2131, RFC2132.