dist/dhcp/relay/dhcrelay.8

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