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