]>
Commit | Line | Data |
---|---|---|
0e7affc7 TL |
1 | .\" dhcrelay.8 |
2 | .\" | |
49a7fb58 | 3 | .\" Copyright (C) 2004-2022 Internet Systems Consortium, Inc. ("ISC") |
98311e4b | 4 | .\" Copyright (c) 1997-2003 by Internet Software Consortium |
0e7affc7 | 5 | .\" |
7512d88b TM |
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/. | |
0e7affc7 | 9 | .\" |
98311e4b DH |
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. | |
0e7affc7 | 17 | .\" |
98311e4b | 18 | .\" Internet Systems Consortium, Inc. |
429a56d7 TM |
19 | .\" PO Box 360 |
20 | .\" Newmarket, NH 03857 USA | |
98311e4b | 21 | .\" <info@isc.org> |
2c85ac9b | 22 | .\" https://www.isc.org/ |
0e7affc7 | 23 | .\" |
98311e4b | 24 | .\" This software has been written for Internet Systems Consortium |
5a38e43f | 25 | .\" by Ted Lemon in cooperation with Vixie Enterprises. |
99038d39 | 26 | .\" |
5a38e43f SR |
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. | |
29 | .\" | |
aa099cba | 30 | .\" $Id: dhcrelay.8,v 1.20 2012/05/14 23:17:43 sar Exp $ |
99038d39 | 31 | .\" |
0e7affc7 TL |
32 | .TH dhcrelay 8 |
33 | .SH NAME | |
d73361d0 | 34 | dhcrelay - Dynamic Host Configuration Protocol Relay Agent |
0e7affc7 TL |
35 | .SH SYNOPSIS |
36 | .B dhcrelay | |
37 | [ | |
7de20a95 | 38 | .B -4 |
0e7affc7 TL |
39 | ] |
40 | [ | |
7de20a95 | 41 | .B -dqaD |
0e7affc7 TL |
42 | ] |
43 | [ | |
7de20a95 EH |
44 | .B -p |
45 | .I port | |
563f0b8a FD |
46 | | |
47 | .B -rp | |
48 | .I relay-port | |
866428dd TL |
49 | ] |
50 | [ | |
98311e4b DH |
51 | .B -c |
52 | .I count | |
53 | ] | |
54 | [ | |
866428dd TL |
55 | .B -A |
56 | .I length | |
57 | ] | |
58 | [ | |
4a5bfeac SR |
59 | .B -pf |
60 | .I pid-file | |
61 | ] | |
62 | [ | |
63 | .B --no-pid | |
64 | ] | |
65 | [ | |
866428dd TL |
66 | .B -m |
67 | .I append | |
68 | | | |
69 | .I replace | |
70 | | | |
71 | .I forward | |
72 | | | |
73 | .I discard | |
74 | ] | |
7de20a95 EH |
75 | [ |
76 | .B -i | |
77 | .I interface0 | |
78 | [ | |
79 | .B ... | |
80 | .B -i | |
f6b8f48d | 81 | .I interfaceN |
7de20a95 | 82 | ] |
edd6d888 | 83 | ] |
f2e70402 TM |
84 | [ |
85 | .B -iu | |
86 | .I interface0 | |
87 | [ | |
88 | .B ... | |
89 | .B -iu | |
90 | .I interfaceN | |
91 | ] | |
7de20a95 | 92 | ] |
edd6d888 TM |
93 | [ |
94 | .B -id | |
95 | .I interface0 | |
96 | [ | |
97 | .B ... | |
98 | .B -id | |
99 | .I interfaceN | |
100 | ] | |
101 | ] | |
102 | [ | |
b12e0ca9 TM |
103 | .B -U |
104 | .I interface | |
105 | ] | |
0e7affc7 TL |
106 | .I server0 |
107 | [ | |
108 | .I ...serverN | |
109 | ] | |
7de20a95 EH |
110 | .PP |
111 | .B dhcrelay -6 | |
112 | [ | |
113 | .B -dqI | |
114 | ] | |
115 | [ | |
116 | .B -p | |
117 | .I port | |
563f0b8a FD |
118 | | |
119 | .B -rp | |
120 | .I relay-port | |
7de20a95 EH |
121 | ] |
122 | [ | |
123 | .B -c | |
124 | .I count | |
125 | ] | |
4a5bfeac SR |
126 | [ |
127 | .B -pf | |
128 | .I pid-file | |
129 | ] | |
130 | [ | |
131 | .B --no-pid | |
132 | ] | |
619304cd SR |
133 | [ |
134 | .B -s | |
135 | .I subscriber-id | |
136 | ] | |
7de20a95 EH |
137 | .B -l |
138 | .I lower0 | |
139 | [ | |
140 | .B ... | |
141 | .B -l | |
142 | .I lowerN | |
143 | ] | |
144 | .B -u | |
f6b8f48d | 145 | .I upper0 |
7de20a95 EH |
146 | [ |
147 | .B ... | |
148 | .B -u | |
149 | .I upperN | |
150 | ] | |
0e7affc7 | 151 | .SH DESCRIPTION |
98311e4b | 152 | The Internet Systems Consortium DHCP Relay Agent, dhcrelay, provides a |
0e7affc7 | 153 | means for relaying DHCP and BOOTP requests from a subnet to which |
7de20a95 EH |
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. | |
0e7affc7 TL |
156 | .SH OPERATION |
157 | .PP | |
7de20a95 EH |
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. | |
0e7affc7 TL |
163 | .SH COMMAND LINE |
164 | .PP | |
7de20a95 EH |
165 | \fIProtocol selection options:\fR |
166 | .TP | |
167 | -6 | |
168 | Run dhcrelay as a DHCPv6 relay agent. Incompatible with the \fB-4\fR | |
98311e4b | 169 | option. |
7de20a95 EH |
170 | .TP |
171 | -4 | |
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. | |
175 | .PP | |
176 | \fISpecifying DHCPv4/BOOTP servers\fR | |
177 | .PP | |
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. | |
180 | .PP | |
181 | \fIOptions available for both DHCPv4 and DHCPv6:\fR | |
182 | .TP | |
563f0b8a | 183 | -c \fIcount\fR |
7de20a95 EH |
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. | |
186 | .TP | |
187 | -d | |
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. | |
190 | .TP | |
563f0b8a | 191 | -p \fIport\fR |
7de20a95 EH |
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. | |
563f0b8a FD |
194 | Incompatible with \fB-rp\fR. |
195 | .TP | |
196 | -rp \fIrelay-port\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 | |
201 | layer access. | |
7de20a95 EH |
202 | .TP |
203 | -q | |
204 | Quiet mode. Prevents dhcrelay6 from printing its network configuration | |
205 | on startup. | |
4a5bfeac SR |
206 | .TP |
207 | -pf pid-file | |
208 | Path to alternate pid file. | |
209 | .TP | |
210 | --no-pid | |
211 | Option to disable writing pid files. By default the program | |
212 | will write a pid file. | |
7de20a95 EH |
213 | .PP |
214 | \fIOptions available in DHCPv4 mode only:\fR | |
215 | .TP | |
216 | -a | |
217 | Append an agent option field to each request before forwarding it to | |
a0497ac5 | 218 | the server. Agent option fields in responses sent from servers to |
7de20a95 EH |
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. | |
225 | .TP | |
563f0b8a | 226 | -A \fIlength\fR |
7de20a95 EH |
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. | |
230 | .TP | |
231 | -D | |
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. | |
236 | .TP | |
237 | -i \fIifname\fR | |
f2e70402 | 238 | Listen for DHCPv4/BOOTP traffic on interface \fIifname\fR. Multiple |
7de20a95 EH |
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. | |
243 | .TP | |
f2e70402 | 244 | -iu \fIifname\fR |
edd6d888 TM |
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. | |
249 | .TP | |
250 | -id \fIifname\fR | |
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. | |
f2e70402 | 255 | .TP |
7de20a95 EH |
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. | |
6e7e6637 | 265 | .TP |
b12e0ca9 | 266 | -U \fIifname\fR |
6e7e6637 TM |
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. | |
273 | ||
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 | |
280 | \fIifname\fR. | |
281 | ||
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 | |
285 | completely. | |
286 | ||
287 | This option is off by default. Note that enabling this option automatically | |
288 | enables the \fB-a\fR option. | |
289 | ||
290 | Keep in mind that using options such as \fB-m replace\fR or \fB-m discard\fR | |
b12e0ca9 | 291 | on relays upstream from one using \fB-U\fR can pose problems. The upstream |
6e7e6637 TM |
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 | |
294 | astray. | |
aa099cba | 295 | |
7de20a95 EH |
296 | .PP |
297 | \fIOptions available in DHCPv6 mode only:\fR | |
298 | .TP | |
299 | -I | |
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 | |
304 | interface. | |
305 | .TP | |
619304cd SR |
306 | -s subscriber-id |
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. | |
310 | .TP | |
7de20a95 EH |
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 | |
319 | interface index. | |
320 | .TP | |
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. | |
329 | .PP | |
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. | |
0e7affc7 | 333 | .SH SEE ALSO |
7de20a95 | 334 | dhclient(8), dhcpd(8), RFC3315, RFC2132, RFC2131. |
866428dd | 335 | .SH BUGS |
866428dd | 336 | .PP |
7de20a95 EH |
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 | |
339 | to a low value. | |
340 | .PP | |
341 | The loopback interface is not (yet) recognized as a valid interface. | |
5a38e43f SR |
342 | .SH AUTHOR |
343 | .B dhcrelay(8) | |
344 | To learn more about Internet Systems Consortium, see | |
345 | .B https://www.isc.org |