| blob | 1e4b4989531dbb222cf751c31e1e335029e2acdf |
1 .\" $NetBSD: dhcrelay.8,v 1.1.1.3 2014/07/12 11:58:01 spz Exp $
2 .\"
3 .\" dhcrelay.8
4 .\"
5 .\" Copyright (c) 2009-2013 by Internet Systems Consortium, Inc. ("ISC")
6 .\" Copyright (c) 2004,2007 by Internet Systems Consortium, Inc. ("ISC")
7 .\" Copyright (c) 1997-2003 by Internet Software Consortium
8 .\"
9 .\" Permission to use, copy, modify, and distribute this software for any
10 .\" purpose with or without fee is hereby granted, provided that the above
11 .\" copyright notice and this permission notice appear in all copies.
12 .\"
13 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
14 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
16 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
19 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 .\"
21 .\" Internet Systems Consortium, Inc.
22 .\" 950 Charter Street
23 .\" Redwood City, CA 94063
24 .\" <info@isc.org>
25 .\" https://www.isc.org/
26 .\"
27 .\" This software has been written for Internet Systems Consortium
28 .\" by Ted Lemon in cooperation with Vixie Enterprises.
29 .\"
30 .\" Support and other services are available for ISC products - see
31 .\" https://www.isc.org for more information or to learn more about ISC.
32 .\"
33 .\" Id: dhcrelay.8,v 1.20 2012/05/14 23:17:43 sar Exp
34 .\"
35 .TH dhcrelay 8
36 .SH NAME
37 dhcrelay - Dynamic Host Configuration Protocol Relay Agent
38 .SH SYNOPSIS
39 .B dhcrelay
40 [
41 .B -4
42 ]
43 [
44 .B -dqaD
45 ]
46 [
47 .B -p
48 .I port
49 ]
50 [
51 .B -c
52 .I count
53 ]
54 [
55 .B -A
56 .I length
57 ]
58 [
59 .B -pf
60 .I pid-file
61 ]
62 [
63 .B --no-pid
64 ]
65 [
66 .B -m
67 .I append
68 |
69 .I replace
70 |
71 .I forward
72 |
73 .I discard
74 ]
75 [
76 .B -i
77 .I interface0
78 [
79 .B ...
80 .B -i
81 .I interfaceN
82 ]
83 ]
84 .I server0
85 [
86 .I ...serverN
87 ]
88 .PP
89 .B dhcrelay -6
90 [
91 .B -dqI
92 ]
93 [
94 .B -p
95 .I port
96 ]
97 [
98 .B -c
99 .I count
100 ]
101 [
102 .B -pf
103 .I pid-file
104 ]
105 [
106 .B --no-pid
107 ]
108 [
109 .B -s
110 .I subscriber-id
111 ]
112 .B -l
113 .I lower0
114 [
115 .B ...
116 .B -l
117 .I lowerN
118 ]
119 .B -u
120 .I upper0
121 [
122 .B ...
123 .B -u
124 .I upperN
125 ]
126 .SH DESCRIPTION
127 The Internet Systems Consortium DHCP Relay Agent, dhcrelay, provides a
128 means for relaying DHCP and BOOTP requests from a subnet to which
129 no DHCP server is directly connected to one or more DHCP servers on
130 other subnets. It supports both DHCPv4/BOOTP and DHCPv6 protocols.
131 .SH OPERATION
132 .PP
133 The DHCP Relay Agent listens for DHCPv4 or DHCPv6 queries from clients or
134 other relay agents on one or more interfaces, passing them along to
135 ``upstream'' servers or relay agents as specified on the command line.
136 When a reply is received from upstream, it is multicast or unicast back
137 downstream to the source of the original request.
138 .SH COMMAND LINE
139 .PP
140 \fIProtocol selection options:\fR
141 .TP
142 -6
143 Run dhcrelay as a DHCPv6 relay agent. Incompatible with the \fB-4\fR
144 option.
145 .TP
146 -4
147 Run dhcrelay as a DHCPv4/BOOTP relay agent. This is the default mode of
148 operation, so the argument is not necessary, but may be specified for
149 clarity. Incompatible with \fB-6\fR.
150 .PP
151 \fISpecifying DHCPv4/BOOTP servers\fR
152 .PP
153 In DHCPv4 mode, a list of one or more server addresses must be specified on
154 the command line, to which DHCP/BOOTP queries should be relayed.
155 .PP
156 \fIOptions available for both DHCPv4 and DHCPv6:\fR
157 .TP
158 -c COUNT
159 Maximum hop count. When forwarding packets, dhcrelay discards packets
160 which have reached a hop count of COUNT. Default is 10. Maximum is 255.
161 .TP
162 -d
163 Force dhcrelay to run as a foreground process. Useful when running
164 dhcrelay under a debugger, or running out of inittab on System V systems.
165 .TP
166 -p PORT
167 Listen and transmit on port PORT. This is mostly useful for debugging
168 purposes. Default is port 67 for DHCPv4/BOOTP, or port 547 for DHCPv6.
169 .TP
170 -q
171 Quiet mode. Prevents dhcrelay6 from printing its network configuration
172 on startup.
173 .TP
174 -pf pid-file
175 Path to alternate pid file.
176 .TP
177 --no-pid
178 Option to disable writing pid files. By default the program
179 will write a pid file.
180 .PP
181 \fIOptions available in DHCPv4 mode only:\fR
182 .TP
183 -a
184 Append an agent option field to each request before forwarding it to
185 the server. Agent option fields in responses sent from servers to
186 clients will be stripped before forwarding such responses back to the
187 client. The agent option field will contain two agent options: the Circuit
188 ID suboption and the Remote ID suboption. Currently, the Circuit ID will
189 be the printable name of the interface on which the client request was
190 received. The client supports inclusion of a Remote ID suboption as well,
191 but this is not used by default.
192 .TP
193 -A LENGTH
194 Specify the maximum packet size to send to a DHCPv4/BOOTP server. This
195 might be done to allow sufficient space for addition of relay agent
196 options while still fitting into the Ethernet MTU size.
197 .TP
198 -D
199 Drop packets from upstream servers if they contain Relay Agent
200 Information options that indicate they were generated in response to
201 a query that came via a different relay agent. If this option is not
202 specified, such packets will be relayed anyway.
203 .TP
204 -i \fIifname\fR
205 Listen for DHCPv4/BOOTP queries on interface \fIifname\fR. Multiple
206 interfaces may be specified by using more than one \fB-i\fR option. If
207 no interfaces are specified on the command line, dhcrelay will identify
208 all network interfaces, eliminating non-broadcast interfaces if possible,
209 and attempt to listen on all of them.
210 .TP
211 -m \fIappend\fR|\fIreplace\fR|\fIforward\fR|\fIdiscard\fR
212 Control the handling of incoming DHCPv4 packets which already contain
213 relay agent options. If such a packet does not have \fIgiaddr\fR set in
214 its header, the DHCP standard requires that the packet be discarded.
215 However, if \fIgiaddr\fR is set, the relay agent may handle the situation
216 in four ways: It may \fIappend\fR its own set of relay options to the
217 packet, leaving the supplied option field intact; it may \fIreplace\fR the
218 existing agent option field; it may \fIforward\fR the packet unchanged; or,
219 it may \fIdiscard\fR it.
221 To use this option you must also enable the \fB-a\fR option.
222 .PP
223 \fIOptions available in DHCPv6 mode only:\fR
224 .TP
225 -I
226 Force use of the DHCPv6 Interface-ID option. This option is
227 automatically sent when there are two or more downstream interfaces
228 in use, to disambiguate between them. The \fB-I\fR option causes
229 dhcrelay to send the option even if there is only one downstream
230 interface.
231 .TP
232 -s subscriber-id
233 Add an option with the specified subscriber-id into the packet. This
234 feature is for testing rather than production as it will put the same
235 subscriber-id into the packet for all clients.
236 .TP
237 -l [\fIaddress%\fR]\fIifname\fR[\fI#index\fR]
238 Specifies the ``lower'' network interface for DHCPv6 relay mode: the
239 interface on which queries will be received from clients or from other
240 relay agents. At least one \fB-l\fR option must be included in the command
241 line when running in DHCPv6 mode. The interface name \fIifname\fR is a
242 mandatory parameter. The link address can be specified by \fIaddress%\fR;
243 if it isn't, dhcrelay will use the first non-link-local address configured
244 on the interface. The optional \fI#index\fR parameter specifies the
245 interface index.
246 .TP
247 -u [\fIaddress%\fR]\fIifname\fR
248 Specifies the ``upper'' network interface for DHCPv6 relay mode: the
249 interface to which queries from clients and other relay agents should be
250 forwarded. At least one \fB-u\fR option must be included in the command
251 line when running in DHCPv6 mode. The interface name \fIifname\fR is a
252 mandatory parameter. The destination unicast or multicast address can be
253 specified by \fIaddress%\fR; if not specified, the relay agent will forward
254 to the DHCPv6 \fIAll_DHCP_Relay_Agents_and_Servers\fR multicast address.
255 .PP
256 It is possible to specify the same interface with different addresses
257 more than once, and even, when the system supports it, to use the same
258 interface as both upper and lower interfaces.
259 .SH SEE ALSO
260 dhclient(8), dhcpd(8), RFC3315, RFC2132, RFC2131.
261 .SH BUGS
262 .PP
263 Using the same interface on both upper and lower sides may cause
264 loops, so when running this way, the maximum hop count should be set
265 to a low value.
266 .PP
267 The loopback interface is not (yet) recognized as a valid interface.
268 .SH AUTHOR
269 .B dhcrelay(8)
270 To learn more about Internet Systems Consortium, see
271 .B https://www.isc.org