- »
- Services »
- DHCP
DHCP is used to automatically provide clients with an IP address (instead of clients having to set one themselves).DHCP is available for both IPv4 and IPv6 clients, referred to as DHCPv4 and DHCPv6, respectively.
Context and future¶
By default OPNsense implements the widely used ISC DHCP server, but as this product hasreached its end of life we choose to add an alternative (KEA) as of version 24.1as a first step in deprecating this piece of software.
Since the code in our system is rather old (originates from M0n0wall) and the data behind it is not structured in a way thatwould be easily migratable to something more modern, we choose to add KEA as a second option and will not try to build a drop-in replacement.Long term ISC will be removed from OPNsense, but no official date has been set yet.
If you want to tryout KEA in OPNsense, just disable the legacy dhcp server on the specific interface andgo to the KEA DHCP menu available under Services ‣ Kea DHCP.
Reservations¶
Both ISC DHCP and KEA DHCP offer the possibility to reserve an IP address for a specific client. This is useful when a clientneeds to have the same IP address every time it connects to the network. Both services also offer the ability to define reservationsinside and outside of the assigned pool of dynamic IP addresses. However, you should only define reservations outside of the pool.Unless you can guarantee that this client is online at all times when the reservation is in the dynamic range, the DHCP server isfree to offer this IP address to a different client when the first client goes offline.
ISC DHCP¶
Settings overview¶
DHCPv4 settings can be found at Services ‣ ISC DHCPv4. DHCPv6 settings can be found at Services ‣ ISC DHCPv6.
The DHCPv4 submenu further consists of:
An entry per interface of general settings, like a toggle to enable/disable DHCPv4 for this interface, DHCP range, DNS servers…
Leases: Shows all IP addresses that are handed out to clients.
Log File: Shows the log file of the DHCPv4 server.
The DHCPv6 submenu further consists of:
Leases: Shows all IP addresses that are handed out to clients.
Using DHCPv4¶
A typical DHCPv4 usage scenario is using it on your LAN with an IP range of 192.168.1.x, where x can be a number from 1through 254. This means a subnet mask of 255.255.255.0. The range can also be written as 192.168.1.0/24. (The “1” inthe third group can also be another number, and there are also other ranges available for private use. These aredescribed in RFC 1918.)
The LAN IP of the OPNsense device that serves DHCP to the LAN should fall in the same DHCP IP range. Typically, it getsthe address ending in .1 (so 192.168.1.1 in this example).
To set the LAN IP, go to Interfaces ‣ [LAN], set “IPv4 Configuration Type” to “Static”, and under“Static IPv4 configuration”, set “IPv4 address” to 192.168.1.1 and the subnet dropdown to “24”. Then click Save.
To set the DHCP settings, go to Services ‣ ISC DHCPv4 ‣ [LAN]. Under “Gateway”, put 192.168.1.1. Under range,put 192.168.1.100 as the start address and 192.168.1.200 as the end address. Then click Save. After saving,click the “Apply Settings” button.
Using DHCPv6¶
When IPv6 addresses should be provisioned over DHCPv6 the Services‣ ISC DHCPv6 ‣[Interface] is the placeto look at. Like in the IPv4 scenario, you can provide a range here, offer settings like default DNS servers andcreate static assignments based on the clients unique DHCP identifier (DUID).
Always make sure Router advertisem*nts are properly configured before debugging DHCPv6 issues, these twodaemons depend on eachother.
If a Prefix Delegation Range is specified, downstream routers may request prefixes (IA_PD). Routing a delegated prefix to a downstreamrouter requires OPNsense to be aware of the router’s IPv6 WAN address. This can be achieved in two ways:
Dynamic DHCPv6 address lease: If an address range is specified in the DHCPv6 service settings and the downstream router requests both an address (IA_NA) and prefix (IA_PD), the prefix will be routed to the leased address.
Static mapping: If the DUID of an active prefix lease matches the DUID of a DHCPv6 static mapping, the delegated prefix will be unconditionally routed to the static mapping’s IPv6 address. The DHCPv6 service doesn’t have to be configured with an address range and the downstream router doesn’t have to request an address. The address in the static mapping may be a GUA, ULA or link-local address. This allows downstream prefix delegation to routers which only request a prefix, not an address.
Advanced settings¶
To configure options that are not available in the GUI one can add custom configuration files on the firewall itself.Files can be added in /usr/local/etc/dhcpd.opnsense.d/ for IPv4 and /usr/local/etc/dhcpd6.opnsense.d/for IPv6, these should use as extension .conf (e.g. custom-options.conf). When more files are placed inside the directory,all will be included in alphabetical order.
Warning
It is the sole responsibility of the administrator which places a file in the extension directory to ensure that the configuration isvalid.
Diagnostics¶
As mentioned in the settings overview, the current leased IP addresses can be seen in the Leases page for diagnosticpurposes. Both IPv4 and IPv6 have their own leases page. This page reflects the current facts as reported by DHCPd in the/var/dhcpd/var/db/dhcpd(6).leases database. By default this page only shows the current active leases. To showall configured leases, check the “inactive” box. You are also able to filter on interfaces by using the dropdownshowing “All Interfaces”.
All times are reported in local time as specified in Administration
Clients are considered online if they exist the ARP table for IPv4 or NDP table for IPv6.
The different possible states a lease can be in is documented in thedhcpd.leases page. If failover is enabled, checking theinactive box will reveal all IP addresses currently reserved by DHCPd with a backup state. These are leases that areavailable for allocation by the failover secondary. The amount shown will vary depending on the configured failoversplit value or range.
The lease type can either by dynamic or static. This is provided for ease of sorting.
A static mapping for a dynamic lease can be configured by clicking on the plus sign of a row.
A lease can also be directly deleted from the leases database.
for DHCPv4, a hostname for a client will be shown if the client specifies their hostname as part of the protocol.
For DHCPv6, a MAC address will be shown if it exists in the NDP table or if the MAC address exists in the DUID, but onlyif this MAC address maps to a known vendor. This is because a MAC address cannot reliably be fetched from a DUID.
The DHCPv6 leases page also shows the delegated prefixes in a separate tab.
DHCRelay¶
DHCP relaying is the forwarding of DHCP requests received on one interface to the DHCP server of another. DHCPrelaying is available for both DHCPv4 and DHCPv6. The settings can be found at Services ‣ DHCRelay.
Destinations¶
Setting | Explanation |
|---|---|
Name | A descriptive name of the reusable relay destination |
Server | A comma separated list of IPs to which the requests should be forwarded. Can be IPv4 or IPv6 exclusively. |
Relays¶
Setting | Explanation |
|---|---|
Enable | Check to enable this entry |
Interface | Which interface to apply relaying to. Only interfaces with an Ethernet address can be selected.Only one interface per destination per address family is allowed. |
Destination | The target destination of the relay from the pool of previously set up destinations. |
Agent Information | If this is checked, the DHCP relay will append the circuit ID (interface number) and theagent ID to the DHCP request. |
KEA DHCP¶
Kea is the next generation of DHCP software, developed by Internet Systems Consortium (ISC).
Control Agent¶
The Kea Control Agent (CA) is a daemon which exposes a RESTful control interface for managing Kea servers.When building a high available dhcp setup, the control agent is a requirement for these kind of setups.
Enabled | Enable control agent |
Bind address | Address on which the RESTful interface should be available, usually this is localhost (127.0.0.1) |
Bind port | Choose an unused port for communication here. |
Note
Although the control agent is required to use high availability peers, it does not have to listen ona non loopback address. The peer configuration by default uses the so called “Multi-Threaded Configuration (HA+MT)”,in which case it starts a separate listener for the HA communication.
Kea DHCPv4¶
This is the DHCPv4 service available in KEA, which offers the following tab sheets with their corresponding settings:
Settings
Generic settings for this service
Subnets
Subnets and associated pools
Reservations
Machine static reservations
HA Peers
Define HA peers for this cluster. All nodes should contain the exact same definitions (usually two hosts, a
primaryand astandbyhost)
Settings | |
General\Enabled | Enable DHCPv4 service |
General\Interfaces | Interfaces to listen on for dhcp[v4] requests |
General\Valid lifetime | Defines how long the addresses (leases) given out by the server are valid (in seconds) |
High Availability\Enabled | Enable high availability setup, requires an active control agent. |
High Availability\This server name | This servername, when unspecified the hostname for this firewall is used. |
Subnets | |
Subnet | Subnet in cidr presentation (e.g. 192.168.1.0/24) |
Pools | List of pools (available addresses) for this service |
Auto collect option data | When set, collect primary address to be used as gateway and dns for the connected clients. |
Routers (gateway) | Default gateway to offer |
DNS servers | Default DNS servers to offer to the client |
NTP servers | Default NTP (time) servers to offer to the client |
TFTP server | TFTP (etherboot) location to offer the client |
TFTP bootfile name | TFTP boot filename to use |
Reservations | |
Subnet | Select a subnet to which this reservation belongs |
IP address | Address to offer the client |
MAC address | Hardware address which identifies this client |
Hostname | Hostname to offer the client |
Description | User friendly description for this reservation |
HA Peers | |
Role | Choose if the selected host is a primary or a standby machine |
Url | This specifies the URL of our server instance, which should use a different port than the control agent.For example http://192.0.2.1:8001/ |
Tip
When using a CARP / HA setup, you usually should specify gateways and dns entries manually. Make sure to disable “Auto collect option data”in that case.
To configure a server with a minimal setup on LAN (like offered on a default OPNsense using ISC-DHCP) using the 192.168.1.0/24 networkoffering addresses in the range 192.168.1.100 - 192.168.1.199. Follow the following steps:
Enable the service (General\Enabled)
Choose LAN as listen interface (General\Interfaces)
Add a new subnet containing the following settings
Subnet :
192.168.1.0/24Pools :
192.168.1.100 - 192.168.1.199Auto collect option data:
[x]
Click on the Apply button.
Leases DHCPv4¶
This page offers an overview of the (non static) leases being offered by KEA DHCPv4.
