opensense-docs/source/manual/dhcp.rst

========================
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 <https://www.isc.org/dhcp/>`__ server, but as this product has
reached its `end of life <https://www.isc.org/blogs/isc-dhcp-eol/>`__ we choose to add an alternative (`KEA <https://www.isc.org/kea/>`__) as of version 24.1
as 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 that
would 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 and
go to the KEA DHCP menu available under :menuselection:`Services --> Kea DHCP`.

-----------------
ISC DHCP
-----------------

...............................
Settings overview
...............................

DHCPv4 settings can be found at :menuselection:`Services --> ISC DHCPv4`. DHCPv6 settings can be found at :menuselection:`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…
* **Relay**: DHCP requests can be “forwarded” to a DHCP server on another interface. This is called relaying.
* **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:

* **Relay**: DHCP requests can be “forwarded” to a DHCP server on another interface. This is called relaying.
* **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 1
through 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” in
the third group can also be another number, and there are also other ranges available for private use. These are
described in `RFC 1918 <https://tools.ietf.org/html/rfc1918#section-3>`_.)

The LAN IP of the OPNsense device that serves DHCP to the LAN should fall in the same DHCP IP range. Typically, it gets
the address ending in .1 (so 192.168.1.1 in this example).

To set the LAN IP, go to :menuselection:`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 :menuselection:`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
...............................
.. _Using DHCPv6:

When IPv6 addresses should be provisioned over DHCPv6 the :menuselection:`Services--> ISC DHCPv6 -->[Interface]` is the place
to look at. Like in the IPv4 scenario, you can provide a range here, offer settings like default DNS servers and
create static assignments based on the clients unique DHCP identifier (`DUID <https://en.wikipedia.org/wiki/DHCPv6>`__).

Always make sure  :doc:`Router advertisements </manual/radvd>` are properly configured before debugging DHCPv6 issues, these two
daemons depend on eachother.

If a Prefix Delegation Range is specified, downstream routers may request prefixes (IA_PD). Routing a delegated prefix to a downstream
router 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 :code:`/usr/local/etc/dhcpd.opnsense.d/` for IPv4 and :code:`/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 is
    valid.

.. _dhcp-relaying:

...............................
DHCP relaying
...............................

DHCP relaying is the forwarding of DHCP requests received on one interface to the DHCP server on another. DHCP
relaying is available for both DHCPv4 and DHCPv6. The DHCPv4 settings can be found at
:menuselection:`Services --> ISC DHCPv4 --> Relay`. The DHCPv6 settings can be found at
:menuselection:`Services --> ISC DHCPv6 --> Relay`.

When setting up DHCP relaying (both DHCPv4 and DHCPv6 relaying have the same settings), the following options are
available:

+-----------------------+----------------------------------------------------------------------------------------------+
| Setting               | Explanation                                                                                  |
+=======================+==============================================================================================+
| Enable                |                                                                                              |
+-----------------------+----------------------------------------------------------------------------------------------+
| Interface(s)          | Which interfaces to apply relaying to. Only interfaces with an IP can be selected.           |
+-----------------------+----------------------------------------------------------------------------------------------+
| Append circuit ID and | If this is checked, the DHCP relay will append the circuit ID (interface number) and the     |
| agent ID to requests  | agent ID to the DHCP request.                                                                |
+-----------------------+----------------------------------------------------------------------------------------------+
| Destination servers   | A comma separated list of IPs to which the requests should be forwarded.                     |
+-----------------------+----------------------------------------------------------------------------------------------+

...............................
Diagnostics
...............................

As mentioned in the settings overview, the current leased IP addresses can be seen in the **Leases** page for diagnostic
purposes. 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 show
all configured leases, check the "inactive" box. You are also able to filter on interfaces by using the dropdown
showing "All Interfaces".

- All times are reported in local time as specified in `Administration <settingsmenu.html#general>`__
- 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 the
  `dhcpd.leases <https://www.freebsd.org/cgi/man.cgi?query=dhcpd.leases>`__ page. If failover is enabled, checking the
  **inactive** box will reveal all IP addresses currently reserved by DHCPd with a **backup** state. These are leases that are
  available for allocation by the failover secondary. The amount shown will vary depending on the configured failover
  split 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 only
  if 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.


-----------------
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 on
  a 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 :code:`primary` and a :code:`standby` host)

========================================================================================================================================================

====================================  ==================================================================================================================
**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 :code:`192.168.1.0/24` network
offering addresses in the range :code:`192.168.1.100 - 192.168.1.199`. Follow the following steps:

1.  Enable the service (General\\Enabled)
2.  Choose LAN as listen interface (General\\Interfaces)
3.  Add a new subnet containing the following settings

  - Subnet : :code:`192.168.1.0/24`
  - Pools : :code:`192.168.1.100 - 192.168.1.199`
  - Auto collect option data: :code:`[x]`

4. Click on the **Apply** button.



...............................
Leases DHCPv4
...............................

This page offers an overview of the (non static) leases being offered by KEA DHCPv4.