WeOS
5.29.0

# DHCP Relay Agent

## Introduction

A DHCP relay agent acts as a proxy for all DHCP traffic between DHCP clients on a LAN and a DHCP Server, usually located on a remote network. The most common use-cases for a DHCP relay agents are:

- Centralised management: Deploying and managing a DHCP server on every LAN in your network is cumbersome. By use of relay agents, a central DHCP server can be used, and the management effort is substantially reduced. Furthermore, if the relay agent is located in a router or switch on the local LAN, there is no additional equipment cost.

- IP address per port: In certain setups IP addresses should be assigned based on the switch port a DHCP client connects to. A DHCP relay agent on that switch can can include port information (DHCP Option 82) when forwarding the DHCP message to the server.

There are three dedicated HowTos that can be used as quick-start guides:

- DHCP IP per-port
- DHCP Relay/Server in a Ring
- DHCP Client/Relay/Server

## Overview

One of the main reasons for using DHCP relay agents is to simplify DHCP management in larger infrastructures. Instead of deploying and managing a DHCP server on every LAN, a DHCP relay agent can forward DHCP messages between local DHCP clients and a central DHCP server.

      DHCP pools:
      A: 192.168.0.100−150/24, gw 192.168.0.1
      B: 192.168.1.100−150/24, gw 192.168.1.1
      C: 192.168.2.100−150/24, gw 192.168.2.1
      D: 192.168.3.100−150/24, gw 192.168.3.1

      .--------.      .--.-.
      | DHCP   |     ( (    )__  Internet/Intranet
      | Server +----(_,  \ ) ,_)------------------.
      |        |      '-'--`--'                   |
      '--------'        |   `---------.           |             .-------.
      192.168.100.1     |             |           |         |   | DHCP  |
                    .---+---.     .---+---.  .----+----.    +---+ Relay |
                    | DHCP  |     | DHCP  |  |         |.1  | .2| Agent |
                    | Relay |     | Relay |  |  Router +----+   | (RA3) |
                    | Agent |     | Agent |  |         |    |   '-------'
                    | (RA1) |     | (RA2) |  '---------'    |
                    '---+---'     '-+---+-'                 |   .-----.
          192.168.0.0   |.1       .1|   |.1                 +---+ PC6 |
          ---+-------+--'      --+--'   '--+---             |   '-----'
             |       |           |         |                |
          .--+--. .--+--.     .--+--.   .--+--.             |   .-----.
          | PC1 | | PC2 |     | PC3 |   | PC4 |             +---+ PC6 |
          '-----' '-----'     '-----'   '-----'             |   '-----'

- (V)LAN interfaces: The DHCP relay agents (here RA1-RA3) serve DHCP clients (here PC1-PC6) on the local LANs. A DHCP relay can serve a single LAN (RA1 and RA3) or multiple LANs (RA2).

A relay agent serving multiple LANs (RA2) can be configured to forward the DHCP requests from different LANs to different sets of DHCP servers.

- DHCP Servers: The relay agent must also know where to forward the DHCP requests from the local PCs, i.e., the relay agent must be configured with IP address of the DHCP server (here 192.168.100.1). For redundancy purposes, the DHCP relay agent allows specifying up to two DHCP servers, to which the relay agent forwards incoming DHCP requests.

DHCP servers listen to UDP port 67 by default. The relay agent can forward packets to a different port on the server, this is neccessary in case you wish to hand out IP addresses per port (DHCP Option 82) on a local DHCP server.

- Address pools: The DHCP server will in turn be configured with appropriate address pools (here denoted A-D), from which it can hand out addresses to the local PCs. When a DHCP relay agent receives a DHCP request from a PC, it will add its local IP address into the giaddr field of the DHCP message when forwarding it to the server (e.g., RA1 will set giaddr to 192.168.0.1) when forwarding requests from PC1 to the DHCP server). Based on the giaddr, the DHCP server can distinguish which pool to hand out address from (here “A”).

- Running relay agents on routers or switches: Relay agents can be run as dedicated servers (RA3), but are typically located inside the local routers (RA1 and RA2). By running the relay agents inside the routers, deployment and management costs are reduced, since no additional equipment is needed.

Although, not shown in the figure above, it is also possible to run relay agents on (layer-2) switches. This is useful when you wish to assign IP addresses based on the physical port the PC connects to. (See section about DHCP Option 82 below).

### DHCP Option 82

In some topologies, you may wish to assign IP addresses based on the switch port a DHCP client connects to. By running a DHCP Relay Agent in the local switch/router, it can include port information when forwarding the DHCP messages (DHCP Option 82). If the packet already contain a Option 82, it will be forwarded unmodified, if not a Option82 will be added.

Circuit ID is set from the portname, or can be overrided per port where you can set it manual (as string or hex).

Remote ID tells how the remote id field of option 82 will be set. It can have several modes:

- MAC uses the base MAC address of the unit. (Default)
- IP sets it to the giaddr.
- System name uses the hostname of the system.
- Manual specify Remote ID either as string or hex values.

### Server Identity Override

By enabling the force DHCP server override setting, the DHCP relay agent can work-around older DHCP servers that do not support RFC5107, which is a hint/extension to Option 82, by overriding Option 54 in the server response to the client with the relay agent’s IP address.

It is recommended to leave this setting disabled and instead either use the local DHCP server, which does not have this issue, or upgrade the main DHCP server to be RFC compliant.

## Configuration

The DHCP relay is a top-level configuration context in the CLI:

    example:/#> configure
    example:/config/#> dhcp-relay
    example:/config/dhcp-relay/#>

`[no] enable`

  Enable, or disable DHCP relay agent. This option can be used to temporarily disable the relay agent, the configuration remains in `startup-config.cfg`.

  To completely deactivate the relay agent, use `no dhcp-relay` from the top-level configuration context in the CLI.

  no
    Disable relay agent
`[no] server [IPADDR[:PORT]|IPADDR[:PORT],IPADDR[:PORT]]`

  Set address and port of DHCP server(s).

  For redundancy purposes, the DHCP Relay Agent enables you to specify up to two DHCP servers, to which the Relay Agent forwards all incoming DHCP requests. The listening port for the DHCP server (default 67), can also be set per server.

  The optional port setting changes the Internet IP protocol port the relay agent uses to forward requests to the DHCP server(s). This is sometimes desirable to protect DHCP server(s) from receiving client requests directly. I.e., when all requests must go through a relay agent which does not support DHCP snooping or has snooping disabled.

  no
    Remove all servers
  no IPADDR
    Remove server matching `IPADDR`
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1
  PORT
    Port number in range 1-65535.
`[no] udp-listen-port [PORT]`

  Set the udp port the relay agent is listening on.

  This setting allows changing the relay source port that the relay agent listen on for responses from the upstream DHCP server.

  Generally a DHCP server will respond on port 67 when it has received a DHCP request forwarded from a DHCP relay agent. In situations when this is not the case, this setting allows for reconfiguration of the relay agent so it can receive responses from the DHCP server on the wanted udp port.

  Default: 67.

  no
    Reset to the default port 67.
  PORT
    Port number in range 1-65535.
`[no] force-server-identity`

  Force Server Identity (Option 54), default disabled.

  This is a compatibility option for some DHCP servers that do not support RFC5107, sub-option 11 to Option 82.

  When enabled the relay agent always sets Option 54 to point back to itself so that the client uses the relay as a full DHCP proxy.

  Should only be needed with older DHCP servers.

  no
    Disable Option 54, this is the default
`[no] iface [IFACE]`

  Set interface to service. DHCP messages from all ports in this VLAN are forwarded to the configured server(s).

  Note

  Enters a sub-configuration context.

  no
    Clear the setting
  IFACE
    Enable DHCP Relay to service a given interface, e.g. `vlan1`.
`[no] option82`

  Enable DHCP option 82.

  Option 82, also called relay agent information, adds a standard field to all incoming DHCP requests before they are forwarded to the server. This field contains the circuit-id and the remote-id. By default, the relay agent will add the access port name as circuit-id and the MAC address of the `iface` as remote-id, respectively.

  no
    Disable Option 82, default

  Activating this setting enters the next level of the configuration where the following settings are possible:

  `[no] remoteid-type <mac | ip | system-name | manual <string|hex> <VALUE>>`

    Set Option 82 Remote ID type.

    Set the Remote ID type, used only when Option 82 is enabled, to either use the MAC, IP, system name of the switch or a manual value (string or hex). Default is to use the MAC address.

    no
      Reset `remoteid-type` to its default value, MAC
    mac
      Use the MAC address of `iface` as the Option 82 remote-id
    system-name
      Use the hostname as the Option 82 remote-id
    manual
      Manually specify Option 82 remote-id, using hex or string

#### Iface Settings

When providing an iface for the DHCP relay to serve, a new sub-context will be opened:

    example:/config/dhcp-relay/#> iface vlan1
    example:/config/dhcp-relay/iface-vlan1/#>

`[no] server [IPADDR[:PORT]|IPADDR[:PORT],IPADDR[:PORT]]`

  Same as the global dhcp-relay setting.

  If this option is not configured it will inherit the global DHCP relay server configuration, if set it will override it.

  no
    Remove any iface specific server that has been configured and simply inherit the global server configuration.
  no IPADDR
    Remove server matching `IPADDR`
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1
  PORT
    Port number in range 1-65535.
`[no] giaddr [IPADDR]`

  Set the GIADDR to use in relayed DHCP requests.

  The GIADDR (Gateway IP Address) is inserted by the relay agent to identify the subnet on which the DHCP client resides. This field contains an IP address of the relay agent’s interface that is on the same network as the client. This allows the DHCP server to see that the request came from a relay agent and to determine which IP address pool to use for the client. The DHCP server will send its reply (unicast) to the DHCP server port (UDP 67) at this GIADDR.

  This option can be either auto (set by `no giaddr`) or a specific IP address. If a specific IP is set, it will be used as GIADDR regardless of the actual address on the interface. If auto the GIADDR will be obtained from the interface itself, in two different ways depending on the configuration of the iface:

  - If the iface is configured with `inet static` the GIADDR will be set to the statically configured IP address on the interface.

  - If the iface is configured with `inet dhcp` the GIADDR will be set to the IP address that is assigned to the interface by the DHCP client. Before an IP address is assigned to the iface by the DHCP client the relay agent will have no GIADDR to use. In this case any DHCP requests received on the iface will be discarded until the iface is assigned an IP address. At this point the GIADDR will be updated and the relay agent will start to relay.

    If the DHCP lease on the iface is released or expires, the relay will have no GIADDR to use and it will stop relaying any DHCP requests received on the iface.

  Implicit priority of static IP over DHCP address for Auto

  When giaddr is set to auto, and the selected interface is configured with both `inet static` and `inet dhcp`, the static IP address has a higher priority and will be used as GIADDR. This means that a DHCP obtained address for the selected iface will only be used as GIADDR if no static IP address is configured on the iface.

  Default: Auto (i.e. `no giaddr`)

  no
    Automatically select address.
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1
`[no] port [PORT | PORT..PORT | PORT,PORT | all]`

  Port specific settings. E.g. exclude from relaying and any Option 82-specific information (circuit-id).

  Note

  Enters a sub-configuration context.

  no
    Disable DHCP relay on the provided `PORT` or disable it on all.
  PORT
    Name of a port, example: eth1.

#### Port Settings

The port specific settings are located in a sub-context of the iface settings for the DHCP relay:

    example:/config/dhcp-relay/#> iface vlan1
    example:/config/dhcp-relay/iface-vlan1/#> port eth1
    example:/config/dhcp-relay/iface-vlan1/port-eth1/#>

`[no] enable`

  Control relaying for port(s).

  This setting controls if relaying should be enabled or disabled for the given port(s). Useful to disable relaying on intra-switch ports.

  Default: enabled

  no
    Disable relaying on the port.
`[no] circuitid-type [portname | manual]`

  Circuit-ID type for port(s).

  Default: portname

  no
    Reset to default, `portname`.
  portname
    Use the name of the port, e.g. “eth1” for port eth1.
  manual

    Use custom hexadecimal value or string:

    - `manual hex VALUE`

    - `manual string VALUE`

    Note

    Hexadecimal values can entered as: 0xXXXXXX, XXXXXX or XX:XX:XX.

« Previous Next »