| blob | dec4970fa842e91e5ba2e8c36e48872f08f8218a |
1 .\" dhcrelay.8
2 .\"
3 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
4 .\" Copyright (c) 1997-2003 by Internet Software Consortium
5 .\"
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.
9 .\"
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.
17 .\"
18 .\" Internet Systems Consortium, Inc.
19 .\" 950 Charter Street
20 .\" Redwood City, CA 94063
21 .\" <info@isc.org>
22 .\" http://www.isc.org/
23 .\"
24 .\" This software has been written for Internet Systems Consortium
25 .\" by Ted Lemon in cooperation with Vixie
26 .\" Enterprises. To learn more about Internet Systems Consortium,
27 .\" see ``http://www.isc.org/isc''. To learn more about Vixie
28 .\" Enterprises, see ``http://www.vix.com''.
29 .\"
30 .\" $Id: dhcrelay.8,v 1.1.1.1 2005/12/07 10:50:33 sonic_amiga Exp $
31 .\"
32 .TH dhcrelay 8
33 .SH NAME
34 dhcrelay - Dynamic Host Configuration Protocol Relay Agent
35 .SH SYNOPSIS
36 .B dhcrelay
37 [
38 .B -p
39 .I port
40 ]
41 [
42 .B -d
43 ]
44 [
45 .B -q
46 ]
47 [
48 .B -i
49 .I if0
50 [
51 .B ...
52 .B -i
53 .I ifN
54 ]
55 ]
56 [
57 .B -a
58 ]
59 [
60 .B -c
61 .I count
62 ]
63 [
64 .B -A
65 .I length
66 ]
67 [
68 .B -D
69 ]
70 [
71 .B -m
72 .I append
73 |
74 .I replace
75 |
76 .I forward
77 |
78 .I discard
79 ]
80 .I server0
81 [
82 .I ...serverN
83 ]
84 .SH DESCRIPTION
85 The Internet Systems Consortium DHCP Relay Agent, dhcrelay, provides a
86 means for relaying DHCP and BOOTP requests from a subnet to which
87 no DHCP server is directly connected to one or more DHCP servers on other
88 subnets.
89 .SH OPERATION
90 .PP
91 The DHCP Relay Agent listens for DHCP and BOOTP queries and responses.
92 When a query is received from a client, dhcrelay forwards it to the
93 list of DHCP servers specified on the command line. When a reply is
94 received from a server, it is broadcast or unicast (according to the
95 relay agent's ability or the client's request) on the network from
96 which the original request came.
97 .SH COMMAND LINE
98 .PP
99 The names of the network interfaces that dhcrelay should attempt to
100 configure may be specified on the command line using the
101 .B -i
102 option. If no interface names
103 are specified on the command line dhcrelay will identify all network
104 interfaces, elimininating non-broadcast interfaces if possible, and
105 attempt to configure each interface.
106 .PP
107 The
108 .B -i
109 flag can be used to specify the network interfaces on which the relay
110 agent should listen. In general, it must listen not only on those
111 network interfaces to which clients are attached, but also on those
112 network interfaces to which the server (or the router that reaches the
113 server) is attached. However, in some cases it may be necessary to
114 exclude some networks; in this case, you must list all those network
115 interfaces that should \fInot\fR be excluded using the \fB-i\fR flag.
116 .PP
117 In some cases it
118 .I is
119 helpful for the relay agent to forward requests from networks on which
120 a DHCP server is running to other DHCP servers. This would be the
121 case if two DHCP servers on different networks were being used to
122 provide backup service for each other's networks.
123 .PP
124 If dhcrelay should listen and transmit on a port other than the
125 standard (port 67), the
126 .B -p
127 flag may used. It should be followed by the udp port number that
128 dhcrelay should use. This is mostly useful for debugging purposes.
129 .PP
130 Dhcrelay will normally run in the foreground until it has configured
131 an interface, and then will revert to running in the background.
132 To force dhcrelay to always run as a foreground process, the
133 .B -d
134 flag should be specified. This is useful when running dhcrelay under
135 a debugger, or when running it out of inittab on System V systems.
136 .PP
137 Dhcrelay will normally print its network configuration on startup.
138 This can be unhelpful in a system startup script - to disable this
139 behaviour, specify the
140 .B -q
141 flag.
142 .SH RELAY AGENT INFORMATION OPTIONS
143 If the
144 .B -a
145 flag is set the relay agent will append an agent option field to each
146 request before forwarding it to the server. Agent option fields in
147 responses sent from servers to clients will be stripped before
148 forwarding such responses back to the client.
149 .PP
150 The agent option field will contain two agent options: the Circuit ID
151 suboption and the Remote ID suboption. Currently, the Circuit ID will
152 be the printable name of the interface on which the client request was
153 received. The client supports inclusion of a Remote ID suboption as
154 well, but this is not used by default.
155 .PP
156 When forwarding packets, dhcrelay discards packets which have reached a hop
157 count of 10. If a lower or higher threshold (up to 255) is desired, depending
158 on your environment, you can specify the max hop count threshold as a number
159 following the
160 .B -c
161 option.
162 .PP
163 Relay Agent options are added to a DHCP packet without the knowledge
164 of the DHCP client. The client may have filled the DHCP packet
165 option buffer completely, in which case there theoretically isn't any
166 space to add Agent options. However, the DHCP server may be able to
167 handle a much larger packet than most DHCP clients would send. The
168 current Agent Options draft requires that the relay agent use a
169 maximum packet size of 576 bytes.
170 .PP
171 It is recommended that with the Internet Systems Consortium DHCP
172 server, the maximum packet size be set to about 1400, allowing plenty
173 of extra space in which the relay agent can put the agent option
174 field, while still fitting into the Ethernet MTU size. This can be
175 done by specifying the
176 .B -A
177 flag, followed by the desired maximum packet size (e.g., 1400).
178 .PP
179 Note that this is reasonably safe to do even if the MTU between the
180 server and the client is less than 1500, as long as the hosts on which
181 the server and client are running support IP fragmentation (and they
182 should). With some knowledge as to how large the agent options might
183 get in a particular configuration, this parameter can be tuned as
184 finely as necessary.
185 .PP
186 It is possible for a relay agent to receive a packet which already
187 contains an agent option field. If this packet does not have a giaddr
188 set, the standard requires that the packet be discarded.
189 .PP
190 If giaddr is set, the server may handle the situation in one of four
191 ways: it may
192 .I append
193 its own set of relay options to the packet, leaving the
194 supplied option field intact. It may
195 .I replace
196 the existing agent option field.
197 It may
198 .I forward
199 the packet unchanged. Or, it may
200 .I discard
201 it.
202 .PP
203 Which of these behaviours is followed by the Internet Systems
204 Consortium DHCP Relay Agent may be configured with the
205 .B -m
206 flag, followed by one of the four keywords specified in
207 .I italics
208 above.
209 .PP
210 When the relay agent receives a reply from a server that it's supposed
211 to forward to a client, and Relay Agent Information option processing
212 is enabled, the relay agent scans the packet for Relay Agent
213 Information options and removes them. As it's scanning, if it finds
214 a Relay Agent Information option field containing an Agent ID
215 suboption that matches one of its IP addresses, that option is
216 recognized as its own. If no such option is found, the relay agent
217 can either drop the packet, or relay it anyway. If the
218 .B -D
219 option is specified, all packets that don't contain a match will be
220 dropped.
221 .SH SPECIFYING DHCP SERVERS
222 The name or IP address of at least one DHCP server to which DHCP and
223 BOOTP requests should be relayed must be specified on the command
224 line.
225 .SH SEE ALSO
226 dhclient(8), dhcpd(8), RFC2132, RFC2131, draft-ietf-dhc-agent-options-03.txt.
227 .SH BUGS
228 It should be possible for the user to define the Circuit ID and Remote
229 ID values on a per-interface basis.
230 .PP
231 The relay agent should not relay packets received on a physical
232 network to DHCP servers on the same physical network - if they do, the
233 server will receive duplicate packets. In order to fix this,
234 however, the relay agent needs to be able to learn about the network
235 topology, which requires that it have a configuration file.
236 .SH AUTHOR
237 .B dhcrelay(8)
238 has been written for Internet Systems Consortium
239 by Ted Lemon in cooperation with Vixie
240 Enterprises. To learn more about Internet Systems Consortium,
241 see
242 .B http://www.isc.org/isc.
243 To learn more about Vixie
244 Enterprises, see
245 .B http://www.vix.com.