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