WeOS
5.29.0

# DHCP Server

## Introduction

Dynamic Host Control Protocol (DHCP) is a mechanism for clients in a network to receive a unique IP address, within its local network area, dynamically upon requesting it. Utilisation of this protocol can make configuration of network topologies a less daunting task, since it is not necessary to manually configure a static IP address for each individual device.

DHCP is capable of providing additional information in conjunction with IP addresses. For a device to properly function in a network, additional parameters might be necessary. Some of the more common parameters that DHCP can provide to its clients include default gateway, domain name, name servers, time servers.

If configuring a network containing multiple LANs, that should use DHCP, it may be inconvenient to configure several DHCP servers to handle each LAN separately. In that case a DHCP Relay can be utilised, see DHCP Relay. This allows for configuration of a single central DHCP Server that can serve multiple LANs. Subsequently, DHCP Relays can be configured to relay DHCP messages to the central DHCP Server from each LAN.

For example DHCP use-cases, see the DHCP HowTos:

- DHCP Server
- DHCP Client Relay Server
- DHCP IP Per Port
- DHCP Relay Server Ring.

## Overview

DHCP is a protocol that uses a client/server model, by default operating on port 67 and 68. DHCP is based on the BOOTP protocol as specified in RFC 951. Any client can ask for a IP address from any potential DHCP server on the network. The following image shows the basic steps that occur between a host and a DHCP server when an address is negotiated.

      Host-1                                        DHCP server
     .-------. DHCP Discover (Broadcast)             .-------.
     |       | ------------------------------------> |       |
     |       |                  DHCP Offer (Unicast) |       |
     |       | <------------------------------------ |       |
     |       | DHCP Request (Broadcast)              |       |
     |       | ------------------------------------> |       |
     |       |                    DHCP ACK (Unicast) |       |
     |       | <------------------------------------ |       |
     '---+---'                                       '---+---'
         |                                               |
    -----+-----------------------------------------------+-----

Figure 1: Communication between host client and server.

- DHCP Discover: Is sent from the host as a broadcast, so it may reach any potential DHCP server present on the network. The message indicates that the host is interested in acquiring an address configuration from a DHCP server.

- DHCP Offer: Is sent as unicast to the host where the Discover originated. Present in the offer is the DHCP configuration that the server wants to provide for the host. If multiple DHCP servers are present on the network they may all send an individual Offer.

- DHCP Request: Is sent as broadcast to the server from the host to indicate that it wants to utilise the configuration that was offered by that particular server. The client can only send a request for one offer, in case it received multiple offers from different servers.

- DHCP ACK: Is sent from the server to the host as unicast. It servers as a final confirmation that the settings offered have been allocated for the client.

Each DHCP server have a pool of addresses that it oversees and allocates from when potential clients asks for a network configuration. This pool can vary in size and range depending on the configuration. Further, DHCP servers can also be instructed to hand out a specific configuration based on certain identifiers that can be extracted from the clients, e.g. client id, MAC, option 82.

The addresses that are handed out from the server can be specified to last for a given amount of time. One reason that this can be useful is that addresses can be reused if a client no longer needs it. Each time a lease expires, the concerned client needs to renew the address if it wants to continue to use it. In this case the client can request from the server the same address that it recently resided over, in most cases it will receive the same address. Nevertheless, it is possible to configure DHCP servers to hand out configurations with an infinite lease attached to it.

Additional configuration that can be passed by DHCP is known as DHCP options. A multitude of different DHCP options exist, several of which can be configured. To read more about DHCP options refer to RFC 2132 (DHCP Options and BOOTP Vendor Extensions). The following options can be configured:

- DHCP Option 1: Netmask.
- DHCP Option 3: Router IP address.
- DHCP Option 6: DNS Server.
- DHCP Option 7: Log Server.
- DHCP Option 12: Hostname.
- DHCP Option 15: Domain Search path.
- DHCP Option 42: NTP Server.
- DHCP Option 51: Lease time.
- DHCP Option 66: TFTP server name.
- DHCP Option 67: TFTP file.
- DHCP Option 121/249: Classless Static Route

More detailed information is available in RFC 2131.

## Configuration

Configuration of DHCP server settings can be done at three levels of scope:

- Global level: Settings in the global scope can be seen as default values. They are valid for communication with all DHCP clients, unless overridden by a corresponding setting at subnet or host level.

- Subnet level: Settings at the subnet level apply to a specific IP subnet. They override corresponding settings done at global level, but may them- selves be overridden by settings at host level. Some settings only apply to the subnet level, e.g., specifying the IP range for the address pool.

- Host level: Settings at host level applies to individual DHCP clients. They override corresponding settings at global or subnet level. Some settings only apply to the host level, e.g., specifying the IP address to hand out to a specific host. Assigning IP settings per host is referred to as ”static lease”, as opposed ”dynamic” assignment from a pool.

Note

An exception is classless routes (option 121/249); routes defined at subnet level complements routes defined at global level, and routes defined at host level complements routes defined at subnet and global levels.

### Global Settings

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

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

#### Syntax

`[no] enable`

  Enable/disable the DHCP server. Useful to disable a fully setup DHCP server before deployment, the configuration will remain dormant while disabled.

  no
    Disable dhcp-server
`[no] gateway [auto]`

  This setting controls the default value of the gateway setting per individual host/subnet configuration.

  The value declared in this setting is overridden if it is configured in the host/subnet context.

  no
    Disable gateway
  auto
    Default to this device IP
`[no] name-server auto|IPADDR[,IPADDR]`

  This setting controls the default value of the name-server setting per individual host/subnet configuration.

  The value declared in this setting is overridden if it is configured in the host/subnet context.

  no
    Disable name-server
  auto
    Default to this device IP
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1
`[no] log-server IPADDR[,IPADDR]`

  Specify optional log servers (DHCP option 7) to include in the DHCP offer. Up to two log servers can be specified.

  no
    Disable the log server option or remove a specific server address.
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] route <NETWORK/LEN GATEWAY>`

  Specify optional classless route(s) assigned to any DHCP client served by this DHCP server. Routes defined here will be sent as DHCP options 121 and 249.

  no
    Remove a specific route or all routes.
  NETWORK
    Network IP address in standard quad-dotted notation, e.g. 192.168.1.0.
  LEN
    Prefix length in CIDR notation (/24).
  GATEWAY
    Gateway IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] ping-check`

  Enable or disable ICMP ping check. By default, the DHCP server will check that an address is not in use before offering it to a client. In some rare cases it may be useful to disable this.

  Parameters

  no
    Disable ping-check.
`[no] server-port PORT`

  Configure the DHCP server listening (UDP) port within the range 1..65535. The default configuration for a DHCP server listening port is 67.

  no
    Reset to the default value (port 67).
  PORT
    Port number in range 1-65535.
`[no] client-port PORT`

  Set DHCP Server source (UDP) port in range 1..65535. By default, the server sends DHCP messages with source UDP port 68.

  no
    Reset to the default value (port 68).
  PORT
    Port number in range 1-65535.
`[no] bootfile FILENAME`

  Configure the boot filename (as stored on the TFTP server).

  The bootfile name is typically passed within the file field of a BOOTP/DHCP message, but is instead sent as DHCP option 67 if option overloading applies or if the client has requested DHCP option 67.

  The value declared in this setting is overridden if it is configured in the host context.

  no
    Disable bootfile.
  FILENAME
    String definition of the file name.
`[no] tftp-server [IPADDR|SERVERNAME]`

  Set the domain name or IP address of the boot server.

  The TFTP server address to be handed out on DHCP requests from static host leases. Each static lease can also have its own unique server and bootfile setting.

  Note

  The value declared in this setting is overridden if it is configured in the host context.

  no
    Remove any configured tftp-server.
  IPADDR

    IP address in standard quad-dotted notation, e.g. 192.168.1.1.

    Set the IP address of the server in both the option 66 field and next server address siaddr.

  SERVERNAME

    String definition of the tftp server FQDN.

    Set the domain name of the server. This is typically passed within the sname field of a BOOTP/DHCP message, but is instead sent as DHCP option 66 if option overloading applies or if the client has requested DHCP option 66.

`[no] host [INDEX]`

  Create and manage host specific DHCP server settings, i.e., static lease settings. This is typically used to configure a static lease based on MAC, Client-ID or port ID (i.e., DHCP Option 82).

  Up to 1024 can be configured. Each entry is given an index in the range 1..1024.

  no
    Remove host.
  INDEX
    Integer value in the range 1..1024.
`[no] subnet IPADDR/LEN | IPADDR[ NETMASK]`

  Create and manage DHCP server IP address pools.

  When creating a subnet an IP address is provided. In addition, the subnet netmask can be specified as a prefix length or a netmask, with /24 and 255.255.255.0 respectively being the default values.

  Up to 64 subnets for a single device can be configured.

  no
    Remove a specific subnet or all of them.
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1.
  LEN
    Size of the net in CIDR notation (/24).
  NETMASK
    Size of the net in quad-dotted format, e.g. 255.255.255.0.

### Host (Static Lease) Settings

Host is a sub-context in the DHCP server configuration:

    example:/#> configure
    example:/config/#> dhcp-server
    example:/config/dhcp-server/#> host 1
    example:/config/dhcp-server/host-1/#>

`[no] lease-time infinite|TIME`

  Specify the lease time in seconds, to be used for addresses handed out to DHCP clients. If this value is not configured the lease time will be defaulted to the one configured for the associated subnet.

  no
    Disable host specific lease time, default to use the subnet lease time.
  infinite
    Specify the lease to be handed out with an infinite lease time.
  TIME
    An integer time value in the range: 120-5256000.
`[no] address deny|IPADDR`

  Specify the IP address that will be associated with this specific host configuration.

  In addition, it is also possible to prohibit the specific host to not be served by this DHCP server.

  no
    In this case it is equivalent do the deny parameter.
  deny
    Configure the host entry to deny the client to receive an address from this DHCP server.
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] bootfile FILENAME`

  Configure the boot filename (as stored on the TFTP server).

  The bootfile name is typically passed within the file field of a BOOTP/DHCP message, but is instead sent as DHCP option 67 if option overloading applies or if the client has requested DHCP option 67.

  If this value is configured it will override any globally configured value.

  no
    Disable bootfile on host level.
  FILENAME
    String definition of the file name.
`[no] tftp-server [IPADDR|SERVERNAME]`

  Set the domain name or IP address of the boot server.

  The TFTP server address to be handed out on DHCP requests. Configuring this setting overrides the configuration made on the top-level for dhcp-server.

  Note

  If this value is configured it will override any globally configured value.

  no
    Remove any configured tftp-server.
  IPADDR

    IP address in standard quad-dotted notation, e.g. 192.168.1.1.

    Set the IP address of the server in both the option 66 field and next server address siaddr.

  SERVERNAME

    String definition of the tftp server FQDN.

    Set the domain name of the server. This is typically passed within the sname field of a BOOTP/DHCP message, but is instead sent as DHCP option 66 if option overloading applies or if the client has requested DHCP option 66.

`[no] hostname HOSTNAME`

  Specify the hostname to be included in the DHCP offer, DHCP option 12.

  no
    Remove any configured hostname and disable this option.
  HOSTNAME
    String representation of the host name to be passed in the offer, e.g. “doorcamera”.
`[no] preempt`

  Enable or disable lease preemption. If enabled, it allows for the lease to be handed out to a new client if they both share the same client-id (option 61). Before the lease is handed out, a ping-check will be performed, to verify if the address is in use.

  no
    Disable lease preemption for the current host entry.
`[no] gateway IPADDR`

  Define a gateway IP address to be included in the DHCP offer, DHCP option 3. It is possible to define one IP address to be used in the DHCP offer.

  If no gateway IP address have been specified, the subnet or globally configured gateway IP address will be used in its place.

  no
    Remove any configured gateway IP address.
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] name-server IPADDR[,IPADDR]`

  Specify system domain name servers (DNS) to be used in DHCP offers to clients, DHCP option 6. It is possible to configure two different IP addresses to be used in the offer.

  If no name servers have been specified, the subnet or globally configured name servers will be used in its place.

  no
    Remove all specified name server DHCP options.
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] ntp-server IPADDR[,IPADDR]`

  Specify optional NTP servers (DHCP option 42) to include in the DHCP offer. Up to two NTP servers can be specified.

  no
    Disable the NTP server option or remove a specific server address.
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] log-server IPADDR[,IPADDR]`

  Specify optional log servers (DHCP option 7) to include in the DHCP offer. Up to two log servers can be specified.

  no
    Disable the log server option or remove a specific server address.
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] route <NETWORK/LEN GATEWAY>`

  Specify optional classless route(s) assigned to this specific host. Routes defined here will be sent as DHCP options 121 and 249.

  no
    Remove a specific route or all routes.
  NETWORK
    Network IP address in standard quad-dotted notation, e.g. 192.168.1.0.
  LEN
    Prefix length in CIDR notation (/24).
  GATEWAY
    Gateway IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] domain ADDR`

  Specify a domain name to be used in the DHCP offer. A single domain name option can be specified.

  no
    Disable the domain option.
  ADDR
    Name of the domain (some.domain.tld).
`[no] match mac|clientid|option82`

  Specify what the configured host entry will match against. This setting is mandatory for static host entries, since it must have something to match against.

  A match type can be specified as mac, clientid or option82:

  MAC:

      [no] match mac MACADDR

  Client ID:

      [no] match clientid hex|string CLIENTID

  Option-82:

      [no] match option82 remote-id hex|string REMOTEID | circuit-id hex|string CIRCUITID

  Multiple match rules for a single host entry are supported, but `clientid` and `mac` cannot be used at the same time.

  no
    Remove all or a specific match entry.
  MACADDR
    MAC address specified in colon notation `00:07:7c:c0:ff:ee`. Wildcard matching is allowed, e.g. `00:07:7c:*` to match the OUI `00:07:7c`.
  hex
    Indicates that the subsequent value is provided in hexadecimal form. The following syntax forms are valid: `0x1a2b`, `1a:2b`, `1a2b`.
  string
    Indicates that the subsequent value is provided in string format.

### Subnet Settings

Subnet is a sub-context in the DHCP server configuration:

    example:/#> configure
    example:/config/#> dhcp-server
    example:/config/dhcp-server/#> subnet 192.168.1.0/24
    Created new DHCP server for subnet 192.168.1.0.
    example:/config/dhcp-server/subnet-192.168.1.0/#>

`[no] gateway IPADDR`

  Define a gateway IP address to be included in the DHCP offer, DHCP option 3. It is possible to define one IP address to be used in the DHCP offer.

  If no gateway IP address have been specified the globally configured gateway IP address will be used in its place.

  no
    Remove any configured gateway IP address.
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] name-server IPADDR[,IPADDR]`

  Specify system domain name servers (DNS) to be used in DHCP offers to clients, DHCP option 6. It is possible to configure two different IP addresses to be used in the offer.

  If no name servers have been specified the globally configured name servers will be used in its place.

  no
    Remove all specified name server DHCP options.
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] ntp-server IPADDR[,IPADDR]`

  Specify optional NTP servers (DHCP option 42) to include in the DHCP offer. Up to two NTP servers can be specified.

  no
    Disable the NTP server option or remove a specific server address.
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] log-server IPADDR[,IPADDR]`

  Specify optional log servers (DHCP option 7) to include in the DHCP offer. Up to two log servers can be specified.

  no
    Disable the log server option or remove a specific server address.
  IPADDR
    IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] route <NETWORK/LEN GATEWAY>`

  Specify optional classless route(s) assigned to DHCP clients in this subnet. Routes defined here will be sent as DHCP options 121 and 249.

  no
    Remove a specific route or all routes.
  NETWORK
    Network IP address in standard quad-dotted notation, e.g. 192.168.1.0.
  LEN
    Prefix length in CIDR notation (/24).
  GATEWAY
    Gateway IP address in standard quad-dotted notation, e.g. 192.168.1.1.
`[no] domain ADDR`

  Specify a domain name to be used in the DHCP offer. A single domain name option can be specified.

  no
    Disable the domain option.
  ADDR
    Name of the domain (some.domain.tld).
`[no] lease-time infinite|TIME`

  Specify the lease time in seconds, to be used for addresses handed out to DHCP clients.

  no
    Disable host specific lease time, default to use the subnet lease time.
  infinite
    Specify the lease to be handed out with an infinite lease time.
  TIME
    An integer time value in the range: 120-5256000.
`[no] netmask NETMASK`

  Specify the netmask for the subnet to serve.

  no
    Reset the netmask to its default value.
  NETMASK
    Size of the net in quad-dotted format, e.g. 255.255.255.0.
`[no] pool IPADDR_START NUM|IPADDR_END`

  Specify the IP address pool from which the DHCP server will handle out leases from.

  The range can be defined between two IP addresses: `pool 192.168.1.50 192.168.1.99`. In addition, the range can be specified with an IP address and a number of addresses based on the address: `pool 192.168.1.50 50`.

  no
    Disable to pool configuration, only use static host entries.
  IPADDR_START
    IP address in standard quad-dotted notation, e.g. 192.168.1.1, defines the first address available in the pool.
  NUM
    Integer value for how many dynamic addresses to be available in the pool starting from IPADDR_START specified.
  IPADDR_END
    IP address in standard quad-dotted notation, e.g. 192.168.1.1, defines the last address available in the pool.

« Previous Next »