3 .\" Copyright (c) 2004-2017 by Internet Systems Consortium, Inc. ("ISC")
4 .\" Copyright (c) 1997-2003 by Internet Software Consortium
6 .\" This Source Code Form is subject to the terms of the Mozilla Public
7 .\" License, v. 2.0. If a copy of the MPL was not distributed with this
8 .\" file, You can obtain one at http://mozilla.org/MPL/2.0/.
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
16 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 .\" Internet Systems Consortium, Inc.
20 .\" Newmarket, NH 03857 USA
22 .\" https://www.isc.org/
24 .\" This software has been written for Internet Systems Consortium
25 .\" by Ted Lemon in cooperation with Vixie Enterprises.
27 .\" Support and other services are available for ISC products - see
28 .\" https://www.isc.org for more information or to learn more about ISC.
30 .\" $Id: dhcrelay.8,v 1.20 2012/05/14 23:17:43 sar Exp $
34 dhcrelay - Dynamic Host Configuration Protocol Relay Agent
152 The Internet Systems Consortium DHCP Relay Agent, dhcrelay, provides a
153 means for relaying DHCP and BOOTP requests from a subnet to which
154 no DHCP server is directly connected to one or more DHCP servers on
155 other subnets. It supports both DHCPv4/BOOTP and DHCPv6 protocols.
158 The DHCP Relay Agent listens for DHCPv4 or DHCPv6 queries from clients or
159 other relay agents on one or more interfaces, passing them along to
160 ``upstream'' servers or relay agents as specified on the command line.
161 When a reply is received from upstream, it is multicast or unicast back
162 downstream to the source of the original request.
165 \fIProtocol selection options:\fR
168 Run dhcrelay as a DHCPv6 relay agent. Incompatible with the \fB-4\fR
172 Run dhcrelay as a DHCPv4/BOOTP relay agent. This is the default mode of
173 operation, so the argument is not necessary, but may be specified for
174 clarity. Incompatible with \fB-6\fR.
176 \fISpecifying DHCPv4/BOOTP servers\fR
178 In DHCPv4 mode, a list of one or more server addresses must be specified on
179 the command line, to which DHCP/BOOTP queries should be relayed.
181 \fIOptions available for both DHCPv4 and DHCPv6:\fR
184 Maximum hop count. When forwarding packets, dhcrelay discards packets
185 which have reached a hop count of COUNT. Default is 10. Maximum is 255.
188 Force dhcrelay to run as a foreground process. Useful when running
189 dhcrelay under a debugger, or running out of inittab on System V systems.
192 Listen and transmit on port PORT. This is mostly useful for debugging
193 purposes. Default is port 67 for DHCPv4/BOOTP, or port 547 for DHCPv6.
194 Incompatible with \fB-rp\fR.
197 Alternative source port for upstream (i.e toward the server) messages
198 with DHCPv4 RAI relay-port sub-option or DHCPv6 relay-source-port
199 option. Relay port support is only available if the code was compiled
200 with (./configure --enable-relay-port) and requires LPF or BPF link
204 Quiet mode. Prevents dhcrelay6 from printing its network configuration
208 Path to alternate pid file.
211 Option to disable writing pid files. By default the program
212 will write a pid file.
214 \fIOptions available in DHCPv4 mode only:\fR
217 Append an agent option field to each request before forwarding it to
218 the server. Agent option fields in responses sent from servers to
219 clients will be stripped before forwarding such responses back to the
220 client. The agent option field will contain two agent options: the Circuit
221 ID suboption and the Remote ID suboption. Currently, the Circuit ID will
222 be the printable name of the interface on which the client request was
223 received. The client supports inclusion of a Remote ID suboption as well,
224 but this is not used by default.
227 Specify the maximum packet size to send to a DHCPv4/BOOTP server. This
228 might be done to allow sufficient space for addition of relay agent
229 options while still fitting into the Ethernet MTU size.
232 Drop packets from upstream servers if they contain Relay Agent
233 Information options that indicate they were generated in response to
234 a query that came via a different relay agent. If this option is not
235 specified, such packets will be relayed anyway.
238 Listen for DHCPv4/BOOTP traffic on interface \fIifname\fR. Multiple
239 interfaces may be specified by using more than one \fB-i\fR option. If
240 no interfaces are specified on the command line, dhcrelay will identify
241 all network interfaces, eliminating non-broadcast interfaces if possible,
242 and attempt to listen on all of them.
245 Specifies an upstream network interface: an interface from which replies
246 from servers and other relay agents will be accepted. Multiple interfaces
247 may be specified by using more than one \fB-iu\fR option. This argument is
248 intended to be used in conjunction with one or more -i or -id arguments.
251 Specifies a downstream network interface: an interface from which requests
252 from clients and other relay agents will be accepted. Multiple interfaces
253 may be specified by using more than one \fB-id\fR option. This argument is
254 intended to be used in conjunction with one or more -i or -iu arguments.
256 -m \fIappend\fR|\fIreplace\fR|\fIforward\fR|\fIdiscard\fR
257 Control the handling of incoming DHCPv4 packets which already contain
258 relay agent options. If such a packet does not have \fIgiaddr\fR set in
259 its header, the DHCP standard requires that the packet be discarded.
260 However, if \fIgiaddr\fR is set, the relay agent may handle the situation
261 in four ways: It may \fIappend\fR its own set of relay options to the
262 packet, leaving the supplied option field intact; it may \fIreplace\fR the
263 existing agent option field; it may \fIforward\fR the packet unchanged; or,
264 it may \fIdiscard\fR it.
267 Enables the addition of a RFC 3527 compliant link selection suboption for
268 clients directly connected to the relay. This RFC allows a relay to
269 specify two different IP addresses: one for the server to use when
270 communicating with the relay (giaddr) the other for choosing the subnet
271 for the client (the suboption). This can be useful if the server is
272 unable to send packets to the relay via the address used for the subnet.
274 When enabled, dhcrelay will add an agent option (as per \fB-a\fR above) that
275 includes the link selection suboption to the forwarded packet. This will only
276 be done to packets received from clients that are directly connected to the
277 relay (i.e. giaddr is zero). The address used in the suboption will be that
278 of the link upon which the inbound packet was received (which would otherwise
279 be used for giaddr). The value of giaddr will be set to that of interface
282 Only one interface should be marked in this fashion. Currently enabling
283 this option on an interface causes the relay to process all DHCP traffic
284 similar to the \fI-i\fR option, in the future we may split the two more
287 This option is off by default. Note that enabling this option automatically
288 enables the \fB-a\fR option.
290 Keep in mind that using options such as \fB-m replace\fR or \fB-m discard\fR
291 on relays upstream from one using \fB-U\fR can pose problems. The upstream
292 relay will wipe out the initial agent option containing the link selection
293 while leaving the re-purposed giaddr value in place, causing packets to go
297 \fIOptions available in DHCPv6 mode only:\fR
300 Force use of the DHCPv6 Interface-ID option. This option is
301 automatically sent when there are two or more downstream interfaces
302 in use, to disambiguate between them. The \fB-I\fR option causes
303 dhcrelay to send the option even if there is only one downstream
307 Add an option with the specified subscriber-id into the packet. This
308 feature is for testing rather than production as it will put the same
309 subscriber-id into the packet for all clients.
311 -l [\fIaddress%\fR]\fIifname\fR[\fI#index\fR]
312 Specifies the ``lower'' network interface for DHCPv6 relay mode: the
313 interface on which queries will be received from clients or from other
314 relay agents. At least one \fB-l\fR option must be included in the command
315 line when running in DHCPv6 mode. The interface name \fIifname\fR is a
316 mandatory parameter. The link address can be specified by \fIaddress%\fR;
317 if it isn't, dhcrelay will use the first non-link-local address configured
318 on the interface. The optional \fI#index\fR parameter specifies the
321 -u [\fIaddress%\fR]\fIifname\fR
322 Specifies the ``upper'' network interface for DHCPv6 relay mode: the
323 interface to which queries from clients and other relay agents should be
324 forwarded. At least one \fB-u\fR option must be included in the command
325 line when running in DHCPv6 mode. The interface name \fIifname\fR is a
326 mandatory parameter. The destination unicast or multicast address can be
327 specified by \fIaddress%\fR; if not specified, the relay agent will forward
328 to the DHCPv6 \fIAll_DHCP_Relay_Agents_and_Servers\fR multicast address.
330 It is possible to specify the same interface with different addresses
331 more than once, and even, when the system supports it, to use the same
332 interface as both upper and lower interfaces.
334 dhclient(8), dhcpd(8), RFC3315, RFC2132, RFC2131.
337 Using the same interface on both upper and lower sides may cause
338 loops, so when running this way, the maximum hop count should be set
341 The loopback interface is not (yet) recognized as a valid interface.
344 To learn more about Internet Systems Consortium, see
345 .B https://www.isc.org