home | help 
dhcrelay(8)		     System Manager's Manual		     dhcrelay(8)

NAME
     dhcrelay - Dynamic Host Configuration Protocol Relay Agent

SYNOPSIS
     dhcrelay  [  -p port ] [ -d ] [ -q ] [ -i if0 [ ...  -i ifN ] ] [ -a ] [ -c
     count ] [ -A length ] [ -D ] [ -m append | replace | forward  |  discard  ]
     server0 [ ...serverN ]

DESCRIPTION
     The  Internet  Systems  Consortium  DHCP  Relay Agent, dhcrelay, provides a
     means for relaying DHCP and BOOTP requests from a subnet to which	no  DHCP
     server is directly connected to one or more DHCP servers on other subnets.

OPERATION
     The  DHCP	Relay  Agent  listens  for DHCP and BOOTP queries and responses.
     When a query is received from a client, dhcrelay forwards it to the list of
     DHCP servers specified on the command line.  When a reply is received  from
     a	server, it is broadcast or unicast (according to the relay agent's abil-
     ity or the client's request) on the network from which the original request
     came.

COMMAND LINE
     The names of the network interfaces that dhcrelay should attempt to config-
     ure may be specified on the command line using the -i option.  If no inter-
     face names are specified on the command line  dhcrelay  will  identify  all
     network interfaces, elimininating non-broadcast interfaces if possible, and
     attempt to configure each interface.

     The  -i flag can be used to specify the network interfaces on which the re-
     lay agent should listen.	In general, it must listen  not  only  on  those
     network interfaces to which clients are attached, but also on those network
     interfaces  to  which the server (or the router that reaches the server) is
     attached.	 However, in some cases it may be necessary to exclude some net-
     works; in this case, you must list all those network interfaces that should
     not be excluded using the -i flag.

     In some cases it is helpful for the relay agent to  forward  requests  from
     networks  on  which  a DHCP server is running to other DHCP servers.   This
     would be the case if two DHCP servers on different networks were being used
     to provide backup service for each other's networks.

     If dhcrelay should listen and transmit on a port other  than  the	standard
     (port  67),  the  -p  flag may used.  It should be followed by the udp port
     number that dhcrelay should use.  This is mostly useful for debugging  pur-
     poses.

     Dhcrelay will normally run in the foreground until it has configured an in-
     terface,  and  then  will	revert	to  running in the background.	To force
     dhcrelay to always run as a foreground process, the -d flag should be spec-
     ified.  This is useful when running dhcrelay under a debugger, or when run-
     ning it out of inittab on System V systems.

     Dhcrelay will normally print its network configuration  on  startup.   This
     can  be  unhelpful  in a system startup script - to disable this behaviour,
     specify the -q flag.

RELAY AGENT INFORMATION OPTIONS
     If the -a flag is set the relay agent will append an agent option field  to
     each  request  before forwarding it to the server.   Agent option fields in
     responses sent from servers to clients will be stripped  before  forwarding
     such responses back to the client.

     The  agent option field will contain two agent options: the Circuit ID sub-
     option and the Agent ID suboption.  Currently, the Circuit ID will  be  the
     printable	name  of the interface on which the client request was received.
     The Agent ID will be the value that the relay  agent  stores  in  the  DHCP
     packet's  giaddr field.   The client supports inclusion of a Remote ID sub-
     option as well, but this is not used by default.

     Note: The Agent ID suboption is not defined in the current Relay Agent  In-
     formation	Option draft (draft-ietf-dhc-agent-options-03.txt), but has been
     proposed for inclusion in the next draft.

     When forwarding packets, dhcrelay discards packets which have reached a hop
     count of 10.  If a lower or higher threshold (up to 255)  is  desired,  de-
     pending on your environment, you can specify the max hop count threshold as
     a number following the -c option.

     Relay Agent options are added to a DHCP packet without the knowledge of the
     DHCP  client.    The  client  may have filled the DHCP packet option buffer
     completely, in which case there theoretically isn't any space to add  Agent
     options.	 However,  the	DHCP  server may be able to handle a much larger
     packet than most DHCP clients would send.	 The current Agent Options draft
     requires that the relay agent use a maximum packet size of 576 bytes.

     It is recommended that with the Internet Systems  Consortium  DHCP  server,
     the  maximum  packet  size  be  set to about 1400, allowing plenty of extra
     space in which the relay agent can put the agent option field, while  still
     fitting  into the Ethernet MTU size.  This can be done by specifying the -A
     flag, followed by the desired maximum packet size (e.g., 1400).

     Note that this is reasonably safe to do even if the MTU between the  server
     and  the client is less than 1500, as long as the hosts on which the server
     and client are running support IP fragmentation (and  they  should).   With
     some  knowledge as to how large the agent options might get in a particular
     configuration, this parameter can be tuned as finely as necessary.

     It is possible for a relay agent to receive a packet which already contains
     an agent option field.  If this packet does not  have  a  giaddr  set,  the
     standard requires that the packet be discarded.

     If  giaddr is set, the server may handle the situation in one of four ways:
     it may append its own set of relay options to the packet, leaving the  sup-
     plied  option  field  intact.    It  may  replace the existing agent option
     field.  It may forward the packet unchanged.   Or, it may discard it.

     Which of these behaviours is followed by the  Internet  Systems  Consortium
     DHCP Relay Agent may be configured with the -m flag, followed by one of the
     four keywords specified in italics above.

     When  the	relay agent receives a reply from a server that it's supposed to
     forward to a client, and Relay Agent Information option processing  is  en-
     abled, the relay agent scans the packet for Relay Agent Information options
     and removes them.	 As it's scanning, if it finds a Relay Agent Information
     option  field  containing	an Agent ID suboption that matches one of its IP
     addresses, that option is recognized as its own.	If  no	such  option  is
     found, the relay agent can either drop the packet, or relay it anyway.   If
     the  -D option is specified, all packets that don't contain a match will be
     dropped.

SPECIFYING DHCP SERVERS
     The name or IP address of at least one DHCP server to which DHCP and  BOOTP
     requests should be relayed must be specified on the command line.

SEE ALSO
     dhclient(8),    dhcpd(8),	  RFC2132,   RFC2131,	draft-ietf-dhc-agent-op-
     tions-03.txt.

BUGS
     It should be possible for the user to define the Circuit ID and  Remote  ID
     values on a per-interface basis.

     The  relay agent should not relay packets received on a physical network to
     DHCP servers on the same physical network - if they do, the server will re-
     ceive duplicate packets.	In order to fix this, however, the  relay  agent
     needs  to	be able to learn about the network topology, which requires that
     it have a configuration file.

AUTHOR
     dhcrelay(8) has been written for Internet Systems Consortium by  Ted  Lemon
     in  cooperation  with Vixie Enterprises.  To learn more about Internet Sys-
     tems Consortium, see http://www.isc.org/isc.  To learn more about Vixie En-
     terprises, see http://www.vix.com.

								     dhcrelay(8)
home | help