relay/dhcrelay.8

   1 .\"     dhcrelay.8
   2 .\"
   3 .\" Copyright (c) 2009-2013 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.20 2012/05/14 23:17:43 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 [
 107 .B -s
 108 .I subscriber-id
 109 ]
 110 .B -l
 111 .I lower0
 112 [
 113 .B ...
 114 .B -l
 115 .I lowerN
 116 ]
 117 .B -u
 118 .I upper0
 119 [
 120 .B ...
 121 .B -u
 122 .I upperN
 123 ]
 124 .SH DESCRIPTION
 125 The Internet Systems Consortium DHCP Relay Agent, dhcrelay, provides a
 126 means for relaying DHCP and BOOTP requests from a subnet to which
 127 no DHCP server is directly connected to one or more DHCP servers on
 128 other subnets.  It supports both DHCPv4/BOOTP and DHCPv6 protocols.
 129 .SH OPERATION
 130 .PP
 131 The DHCP Relay Agent listens for DHCPv4 or DHCPv6 queries from clients or
 132 other relay agents on one or more interfaces, passing them along to
 133 ``upstream'' servers or relay agents as specified on the command line.
 134 When a reply is received from upstream, it is multicast or unicast back
 135 downstream to the source of the original request.
 136 .SH COMMAND LINE
 137 .PP
 138 \fIProtocol selection options:\fR
 139 .TP
 140 -6
 141 Run dhcrelay as a DHCPv6 relay agent.  Incompatible with the \fB-4\fR
 142 option.
 143 .TP
 144 -4
 145 Run dhcrelay as a DHCPv4/BOOTP relay agent.  This is the default mode of
 146 operation, so the argument is not necessary, but may be specified for
 147 clarity.  Incompatible with \fB-6\fR.
 148 .PP
 149 \fISpecifying DHCPv4/BOOTP servers\fR
 150 .PP
 151 In DHCPv4 mode, a list of one or more server addresses must be specified on
 152 the command line, to which DHCP/BOOTP queries should be relayed.
 153 .PP
 154 \fIOptions available for both DHCPv4 and DHCPv6:\fR
 155 .TP
 156 -c COUNT
 157 Maximum hop count.  When forwarding packets, dhcrelay discards packets
 158 which have reached a hop count of COUNT.  Default is 10.  Maximum is 255.
 159 .TP
 160 -d
 161 Force dhcrelay to run as a foreground process.  Useful when running
 162 dhcrelay under a debugger, or running out of inittab on System V systems.
 163 .TP
 164 -p PORT
 165 Listen and transmit on port PORT.  This is mostly useful for debugging
 166 purposes.  Default is port 67 for DHCPv4/BOOTP, or port 547 for DHCPv6.
 167 .TP
 168 -q
 169 Quiet mode.  Prevents dhcrelay6 from printing its network configuration
 170 on startup.
 171 .TP
 172 -pf pid-file
 173 Path to alternate pid file.
 174 .TP
 175 --no-pid
 176 Option to disable writing pid files.  By default the program
 177 will write a pid file.
 178 .PP
 179 \fIOptions available in DHCPv4 mode only:\fR
 180 .TP
 181 -a
 182 Append an agent option field to each request before forwarding it to
 183 the server.  Agent option fields in responses sent from servers to
 184 clients will be stripped before forwarding such responses back to the
 185 client.  The agent option field will contain two agent options: the Circuit
 186 ID suboption and the Remote ID suboption.  Currently, the Circuit ID will
 187 be the printable name of the interface on which the client request was
 188 received.  The client supports inclusion of a Remote ID suboption as well,
 189 but this is not used by default.
 190 .TP
 191 -A LENGTH
 192 Specify the maximum packet size to send to a DHCPv4/BOOTP server.  This
 193 might be done to allow sufficient space for addition of relay agent
 194 options while still fitting into the Ethernet MTU size.
 195 .TP
 196 -D
 197 Drop packets from upstream servers if they contain Relay Agent
 198 Information options that indicate they were generated in response to
 199 a query that came via a different relay agent.  If this option is not
 200 specified, such packets will be relayed anyway.
 201 .TP
 202 -i \fIifname\fR
 203 Listen for DHCPv4/BOOTP queries on interface \fIifname\fR.  Multiple
 204 interfaces may be specified by using more than one \fB-i\fR option.  If
 205 no interfaces are specified on the command line, dhcrelay will identify
 206 all network interfaces, eliminating non-broadcast interfaces if possible,
 207 and attempt to listen on all of them.
 208 .TP
 209 -m \fIappend\fR|\fIreplace\fR|\fIforward\fR|\fIdiscard\fR
 210 Control the handling of incoming DHCPv4 packets which already contain
 211 relay agent options.  If such a packet does not have \fIgiaddr\fR set in
 212 its header, the DHCP standard requires that the packet be discarded.
 213 However, if \fIgiaddr\fR is set, the relay agent may handle the situation
 214 in four ways:  It may \fIappend\fR its own set of relay options to the
 215 packet, leaving the supplied option field intact; it may \fIreplace\fR the
 216 existing agent option field; it may \fIforward\fR the packet unchanged; or,
 217 it may \fIdiscard\fR it.
 218
 219 To use this option you must also enable the \fB-a\fR option.
 220 .PP
 221 \fIOptions available in DHCPv6 mode only:\fR
 222 .TP
 223 -I
 224 Force use of the DHCPv6 Interface-ID option.  This option is
 225 automatically sent when there are two or more downstream interfaces
 226 in use, to disambiguate between them.  The \fB-I\fR option causes
 227 dhcrelay to send the option even if there is only one downstream
 228 interface.
 229 .TP
 230 -s subscriber-id
 231 Add an option with the specified subscriber-id into the packet.  This
 232 feature is for testing rather than production as it will put the same
 233 subscriber-id into the packet for all clients.
 234 .TP
 235 -l [\fIaddress%\fR]\fIifname\fR[\fI#index\fR]
 236 Specifies the ``lower'' network interface for DHCPv6 relay mode: the
 237 interface on which queries will be received from clients or from other
 238 relay agents.  At least one \fB-l\fR option must be included in the command
 239 line when running in DHCPv6 mode.  The interface name \fIifname\fR is a
 240 mandatory parameter.  The link address can be specified by \fIaddress%\fR;
 241 if it isn't, dhcrelay will use the first non-link-local address configured
 242 on the interface.  The optional \fI#index\fR parameter specifies the
 243 interface index.
 244 .TP
 245 -u [\fIaddress%\fR]\fIifname\fR
 246 Specifies the ``upper'' network interface for DHCPv6 relay mode: the
 247 interface to which queries from clients and other relay agents should be
 248 forwarded.  At least one \fB-u\fR option must be included in the command
 249 line when running in DHCPv6 mode.  The interface name \fIifname\fR is a
 250 mandatory parameter. The destination unicast or multicast address can be
 251 specified by \fIaddress%\fR; if not specified, the relay agent will forward
 252 to the DHCPv6 \fIAll_DHCP_Relay_Agents_and_Servers\fR multicast address.
 253 .PP
 254 It is possible to specify the same interface with different addresses
 255 more than once, and even, when the system supports it, to use the same
 256 interface as both upper and lower interfaces.
 257 .SH SEE ALSO
 258 dhclient(8), dhcpd(8), RFC3315, RFC2132, RFC2131.
 259 .SH BUGS
 260 .PP
 261 Using the same interface on both upper and lower sides may cause
 262 loops, so when running this way, the maximum hop count should be set
 263 to a low value.
 264 .PP
 265 The loopback interface is not (yet) recognized as a valid interface.
 266 .SH AUTHOR
 267 .B dhcrelay(8)
 268 To learn more about Internet Systems Consortium, see
 269 .B https://www.isc.org