]>
Commit | Line | Data |
---|---|---|
0e7affc7 TL |
1 | .\" dhcrelay.8 |
2 | .\" | |
9deef2e7 | 3 | .\" Copyright (c) 2004-2016 by Internet Systems Consortium, Inc. ("ISC") |
98311e4b | 4 | .\" Copyright (c) 1997-2003 by Internet Software Consortium |
0e7affc7 | 5 | .\" |
98311e4b DH |
6 | .\" Permission to use, copy, modify, and distribute this software for any |
7 | .\" purpose with or without fee is hereby granted, provided that the above | |
8 | .\" copyright notice and this permission notice appear in all copies. | |
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 DH |
18 | .\" Internet Systems Consortium, Inc. |
19 | .\" 950 Charter Street | |
20 | .\" Redwood City, CA 94063 | |
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 | |
866428dd TL |
46 | ] |
47 | [ | |
98311e4b DH |
48 | .B -c |
49 | .I count | |
50 | ] | |
51 | [ | |
866428dd TL |
52 | .B -A |
53 | .I length | |
54 | ] | |
55 | [ | |
4a5bfeac SR |
56 | .B -pf |
57 | .I pid-file | |
58 | ] | |
59 | [ | |
60 | .B --no-pid | |
61 | ] | |
62 | [ | |
866428dd TL |
63 | .B -m |
64 | .I append | |
65 | | | |
66 | .I replace | |
67 | | | |
68 | .I forward | |
69 | | | |
70 | .I discard | |
71 | ] | |
7de20a95 EH |
72 | [ |
73 | .B -i | |
74 | .I interface0 | |
75 | [ | |
76 | .B ... | |
77 | .B -i | |
78 | .I interfaceN | |
79 | ] | |
edd6d888 | 80 | ] |
f2e70402 TM |
81 | [ |
82 | .B -iu | |
83 | .I interface0 | |
84 | [ | |
85 | .B ... | |
86 | .B -iu | |
87 | .I interfaceN | |
88 | ] | |
7de20a95 | 89 | ] |
edd6d888 TM |
90 | [ |
91 | .B -id | |
92 | .I interface0 | |
93 | [ | |
94 | .B ... | |
95 | .B -id | |
96 | .I interfaceN | |
97 | ] | |
98 | ] | |
99 | [ | |
b12e0ca9 TM |
100 | .B -U |
101 | .I interface | |
102 | ] | |
0e7affc7 TL |
103 | .I server0 |
104 | [ | |
105 | .I ...serverN | |
106 | ] | |
7de20a95 EH |
107 | .PP |
108 | .B dhcrelay -6 | |
109 | [ | |
110 | .B -dqI | |
111 | ] | |
112 | [ | |
113 | .B -p | |
114 | .I port | |
115 | ] | |
116 | [ | |
117 | .B -c | |
118 | .I count | |
119 | ] | |
4a5bfeac SR |
120 | [ |
121 | .B -pf | |
122 | .I pid-file | |
123 | ] | |
124 | [ | |
125 | .B --no-pid | |
126 | ] | |
619304cd SR |
127 | [ |
128 | .B -s | |
129 | .I subscriber-id | |
130 | ] | |
7de20a95 EH |
131 | .B -l |
132 | .I lower0 | |
133 | [ | |
134 | .B ... | |
135 | .B -l | |
136 | .I lowerN | |
137 | ] | |
138 | .B -u | |
139 | .I upper0 | |
140 | [ | |
141 | .B ... | |
142 | .B -u | |
143 | .I upperN | |
144 | ] | |
0e7affc7 | 145 | .SH DESCRIPTION |
98311e4b | 146 | The Internet Systems Consortium DHCP Relay Agent, dhcrelay, provides a |
0e7affc7 | 147 | means for relaying DHCP and BOOTP requests from a subnet to which |
7de20a95 EH |
148 | no DHCP server is directly connected to one or more DHCP servers on |
149 | other subnets. It supports both DHCPv4/BOOTP and DHCPv6 protocols. | |
0e7affc7 TL |
150 | .SH OPERATION |
151 | .PP | |
7de20a95 EH |
152 | The DHCP Relay Agent listens for DHCPv4 or DHCPv6 queries from clients or |
153 | other relay agents on one or more interfaces, passing them along to | |
154 | ``upstream'' servers or relay agents as specified on the command line. | |
155 | When a reply is received from upstream, it is multicast or unicast back | |
156 | downstream to the source of the original request. | |
0e7affc7 TL |
157 | .SH COMMAND LINE |
158 | .PP | |
7de20a95 EH |
159 | \fIProtocol selection options:\fR |
160 | .TP | |
161 | -6 | |
162 | Run dhcrelay as a DHCPv6 relay agent. Incompatible with the \fB-4\fR | |
98311e4b | 163 | option. |
7de20a95 EH |
164 | .TP |
165 | -4 | |
166 | Run dhcrelay as a DHCPv4/BOOTP relay agent. This is the default mode of | |
167 | operation, so the argument is not necessary, but may be specified for | |
168 | clarity. Incompatible with \fB-6\fR. | |
169 | .PP | |
170 | \fISpecifying DHCPv4/BOOTP servers\fR | |
171 | .PP | |
172 | In DHCPv4 mode, a list of one or more server addresses must be specified on | |
173 | the command line, to which DHCP/BOOTP queries should be relayed. | |
174 | .PP | |
175 | \fIOptions available for both DHCPv4 and DHCPv6:\fR | |
176 | .TP | |
177 | -c COUNT | |
178 | Maximum hop count. When forwarding packets, dhcrelay discards packets | |
179 | which have reached a hop count of COUNT. Default is 10. Maximum is 255. | |
180 | .TP | |
181 | -d | |
182 | Force dhcrelay to run as a foreground process. Useful when running | |
183 | dhcrelay under a debugger, or running out of inittab on System V systems. | |
184 | .TP | |
185 | -p PORT | |
186 | Listen and transmit on port PORT. This is mostly useful for debugging | |
187 | purposes. Default is port 67 for DHCPv4/BOOTP, or port 547 for DHCPv6. | |
188 | .TP | |
189 | -q | |
190 | Quiet mode. Prevents dhcrelay6 from printing its network configuration | |
191 | on startup. | |
4a5bfeac SR |
192 | .TP |
193 | -pf pid-file | |
194 | Path to alternate pid file. | |
195 | .TP | |
196 | --no-pid | |
197 | Option to disable writing pid files. By default the program | |
198 | will write a pid file. | |
7de20a95 EH |
199 | .PP |
200 | \fIOptions available in DHCPv4 mode only:\fR | |
201 | .TP | |
202 | -a | |
203 | Append an agent option field to each request before forwarding it to | |
a0497ac5 | 204 | the server. Agent option fields in responses sent from servers to |
7de20a95 EH |
205 | clients will be stripped before forwarding such responses back to the |
206 | client. The agent option field will contain two agent options: the Circuit | |
207 | ID suboption and the Remote ID suboption. Currently, the Circuit ID will | |
208 | be the printable name of the interface on which the client request was | |
209 | received. The client supports inclusion of a Remote ID suboption as well, | |
210 | but this is not used by default. | |
211 | .TP | |
212 | -A LENGTH | |
213 | Specify the maximum packet size to send to a DHCPv4/BOOTP server. This | |
214 | might be done to allow sufficient space for addition of relay agent | |
215 | options while still fitting into the Ethernet MTU size. | |
216 | .TP | |
217 | -D | |
218 | Drop packets from upstream servers if they contain Relay Agent | |
219 | Information options that indicate they were generated in response to | |
220 | a query that came via a different relay agent. If this option is not | |
221 | specified, such packets will be relayed anyway. | |
222 | .TP | |
223 | -i \fIifname\fR | |
f2e70402 | 224 | Listen for DHCPv4/BOOTP traffic on interface \fIifname\fR. Multiple |
7de20a95 EH |
225 | interfaces may be specified by using more than one \fB-i\fR option. If |
226 | no interfaces are specified on the command line, dhcrelay will identify | |
227 | all network interfaces, eliminating non-broadcast interfaces if possible, | |
228 | and attempt to listen on all of them. | |
229 | .TP | |
f2e70402 | 230 | -iu \fIifname\fR |
edd6d888 TM |
231 | Specifies an upstream network interface: an interface from which replies |
232 | from servers and other relay agents will be accepted. Multiple interfaces | |
233 | may be specified by using more than one \fB-iu\fR option. This argument is | |
234 | intended to be used in conjunction with one or more -i or -id arguments. | |
235 | .TP | |
236 | -id \fIifname\fR | |
237 | Specifies a downstream network interface: an interface from which requests | |
238 | from clients and other relay agents will be accepted. Multiple interfaces | |
239 | may be specified by using more than one \fB-id\fR option. This argument is | |
240 | intended to be used in conjunction with one or more -i or -iu arguments. | |
f2e70402 | 241 | .TP |
7de20a95 EH |
242 | -m \fIappend\fR|\fIreplace\fR|\fIforward\fR|\fIdiscard\fR |
243 | Control the handling of incoming DHCPv4 packets which already contain | |
244 | relay agent options. If such a packet does not have \fIgiaddr\fR set in | |
245 | its header, the DHCP standard requires that the packet be discarded. | |
246 | However, if \fIgiaddr\fR is set, the relay agent may handle the situation | |
247 | in four ways: It may \fIappend\fR its own set of relay options to the | |
248 | packet, leaving the supplied option field intact; it may \fIreplace\fR the | |
249 | existing agent option field; it may \fIforward\fR the packet unchanged; or, | |
250 | it may \fIdiscard\fR it. | |
6e7e6637 | 251 | .TP |
b12e0ca9 | 252 | -U \fIifname\fR |
6e7e6637 TM |
253 | Enables the addition of a RFC 3527 compliant link selection suboption for |
254 | clients directly connected to the relay. This RFC allows a relay to | |
255 | specify two different IP addresses: one for the server to use when | |
256 | communicating with the relay (giaddr) the other for choosing the subnet | |
257 | for the client (the suboption). This can be useful if the server is | |
258 | unable to send packets to the relay via the address used for the subnet. | |
259 | ||
260 | When enabled, dhcrelay will add an agent option (as per \fB-a\fR above) that | |
261 | includes the link selection suboption to the forwarded packet. This will only | |
262 | be done to packets received from clients that are directly connected to the | |
263 | relay (i.e. giaddr is zero). The address used in the suboption will be that | |
264 | of the link upon which the inbound packet was received (which would otherwise | |
265 | be used for giaddr). The value of giaddr will be set to that of interface | |
266 | \fIifname\fR. | |
267 | ||
268 | Only one interface should be marked in this fashion. Currently enabling | |
269 | this option on an interface causes the relay to process all DHCP traffic | |
270 | similar to the \fI-i\fR option, in the future we may split the two more | |
271 | completely. | |
272 | ||
273 | This option is off by default. Note that enabling this option automatically | |
274 | enables the \fB-a\fR option. | |
275 | ||
276 | Keep in mind that using options such as \fB-m replace\fR or \fB-m discard\fR | |
b12e0ca9 | 277 | on relays upstream from one using \fB-U\fR can pose problems. The upstream |
6e7e6637 TM |
278 | relay will wipe out the initial agent option containing the link selection |
279 | while leaving the re-purposed giaddr value in place, causing packets to go | |
280 | astray. | |
aa099cba | 281 | |
7de20a95 EH |
282 | .PP |
283 | \fIOptions available in DHCPv6 mode only:\fR | |
284 | .TP | |
285 | -I | |
286 | Force use of the DHCPv6 Interface-ID option. This option is | |
287 | automatically sent when there are two or more downstream interfaces | |
288 | in use, to disambiguate between them. The \fB-I\fR option causes | |
289 | dhcrelay to send the option even if there is only one downstream | |
290 | interface. | |
291 | .TP | |
619304cd SR |
292 | -s subscriber-id |
293 | Add an option with the specified subscriber-id into the packet. This | |
294 | feature is for testing rather than production as it will put the same | |
295 | subscriber-id into the packet for all clients. | |
296 | .TP | |
7de20a95 EH |
297 | -l [\fIaddress%\fR]\fIifname\fR[\fI#index\fR] |
298 | Specifies the ``lower'' network interface for DHCPv6 relay mode: the | |
299 | interface on which queries will be received from clients or from other | |
300 | relay agents. At least one \fB-l\fR option must be included in the command | |
301 | line when running in DHCPv6 mode. The interface name \fIifname\fR is a | |
302 | mandatory parameter. The link address can be specified by \fIaddress%\fR; | |
303 | if it isn't, dhcrelay will use the first non-link-local address configured | |
304 | on the interface. The optional \fI#index\fR parameter specifies the | |
305 | interface index. | |
306 | .TP | |
307 | -u [\fIaddress%\fR]\fIifname\fR | |
308 | Specifies the ``upper'' network interface for DHCPv6 relay mode: the | |
309 | interface to which queries from clients and other relay agents should be | |
310 | forwarded. At least one \fB-u\fR option must be included in the command | |
311 | line when running in DHCPv6 mode. The interface name \fIifname\fR is a | |
312 | mandatory parameter. The destination unicast or multicast address can be | |
313 | specified by \fIaddress%\fR; if not specified, the relay agent will forward | |
314 | to the DHCPv6 \fIAll_DHCP_Relay_Agents_and_Servers\fR multicast address. | |
315 | .PP | |
316 | It is possible to specify the same interface with different addresses | |
317 | more than once, and even, when the system supports it, to use the same | |
318 | interface as both upper and lower interfaces. | |
0e7affc7 | 319 | .SH SEE ALSO |
7de20a95 | 320 | dhclient(8), dhcpd(8), RFC3315, RFC2132, RFC2131. |
866428dd | 321 | .SH BUGS |
866428dd | 322 | .PP |
7de20a95 EH |
323 | Using the same interface on both upper and lower sides may cause |
324 | loops, so when running this way, the maximum hop count should be set | |
325 | to a low value. | |
326 | .PP | |
327 | The loopback interface is not (yet) recognized as a valid interface. | |
5a38e43f SR |
328 | .SH AUTHOR |
329 | .B dhcrelay(8) | |
330 | To learn more about Internet Systems Consortium, see | |
331 | .B https://www.isc.org |