Annotation of embedaddon/dhcp/relay/dhcrelay.8, revision 1.1
1.1 ! misho 1: .\" dhcrelay.8
! 2: .\"
! 3: .\" Copyright (c) 2009-2011 by Internet Systems Consortium, Inc. ("ISC")
! 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: .\"
! 31: .\" $Id: dhcrelay.8,v 1.15.38.3.6.1 2011-04-15 22:26:21 sar Exp $
! 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
! 179: the server. Agent option fields in responses sent from servers to
! 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.
! 214: .PP
! 215: \fIOptions available in DHCPv6 mode only:\fR
! 216: .TP
! 217: -I
! 218: Force use of the DHCPv6 Interface-ID option. This option is
! 219: automatically sent when there are two or more downstream interfaces
! 220: in use, to disambiguate between them. The \fB-I\fR option causes
! 221: dhcrelay to send the option even if there is only one downstream
! 222: interface.
! 223: .TP
! 224: -l [\fIaddress%\fR]\fIifname\fR[\fI#index\fR]
! 225: Specifies the ``lower'' network interface for DHCPv6 relay mode: the
! 226: interface on which queries will be received from clients or from other
! 227: relay agents. At least one \fB-l\fR option must be included in the command
! 228: line when running in DHCPv6 mode. The interface name \fIifname\fR is a
! 229: mandatory parameter. The link address can be specified by \fIaddress%\fR;
! 230: if it isn't, dhcrelay will use the first non-link-local address configured
! 231: on the interface. The optional \fI#index\fR parameter specifies the
! 232: interface index.
! 233: .TP
! 234: -u [\fIaddress%\fR]\fIifname\fR
! 235: Specifies the ``upper'' network interface for DHCPv6 relay mode: the
! 236: interface to which queries from clients and other relay agents should be
! 237: forwarded. At least one \fB-u\fR option must be included in the command
! 238: line when running in DHCPv6 mode. The interface name \fIifname\fR is a
! 239: mandatory parameter. The destination unicast or multicast address can be
! 240: specified by \fIaddress%\fR; if not specified, the relay agent will forward
! 241: to the DHCPv6 \fIAll_DHCP_Relay_Agents_and_Servers\fR multicast address.
! 242: .PP
! 243: It is possible to specify the same interface with different addresses
! 244: more than once, and even, when the system supports it, to use the same
! 245: interface as both upper and lower interfaces.
! 246: .SH SEE ALSO
! 247: dhclient(8), dhcpd(8), RFC3315, RFC2132, RFC2131.
! 248: .SH BUGS
! 249: .PP
! 250: Using the same interface on both upper and lower sides may cause
! 251: loops, so when running this way, the maximum hop count should be set
! 252: to a low value.
! 253: .PP
! 254: The loopback interface is not (yet) recognized as a valid interface.
! 255: .SH AUTHOR
! 256: .B dhcrelay(8)
! 257: To learn more about Internet Systems Consortium, see
! 258: .B https://www.isc.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>