====
DHCP
====

If the bond was previously serving DHCP using the legacy DHCP server
(prior to 2016.2), please read the `documentation on removing existing
DHCP servers <../../extending-bonded-internet/legacy-dhcp-server.html#removal>`__
prior to enabling any DHCP services.

As of 6.4, connected IPs can no longer be configured to perform DHCP natively.
Instead, a bond can be configured with a DHCP service, which can then be bound to connected IPs.


Configuring a DHCP Service
--------------------------

DHCP
^^^^^

There are three modes for DHCP:

-  Disabled (default): No DHCP server enabled for this connected IP.
-  Local: a DHCP server will run on the bonder and clients behind the
   connected IP will receive a DHCP lease in the specified range.
-  Relay: DHCP requests will be relayed to remote DHCP servers specified
   in "Relay servers."

Range
++++++

Specify the range of IPv4 addresses within the connected IP's network to
be given out by DHCP (only enabled for "Local" DHCP servers).

Lease time
+++++++++++

The amount of time that the leases are given out for. Lease time should
be written as seconds (e.g. 100s), or minutes (e.g. 10m), or hours (e.g.
12h), or as "infinite." The lease time must be a minimum of 2 minutes
and is "24h" by default (only enabled for "Local" DHCP servers).

Domain (optional)
++++++++++++++++++

Specify a DNS domain address for the DHCP server. This domain name will
be provided to any hosts that request it (only enabled for "Local" DHCP
servers).

TFTP server (optional)
+++++++++++++++++++++++

Specify a TFTP server for file transfer (only enabled for "Local" DHCP
servers).

Relay servers
++++++++++++++

Up to three addresses may be specified as DHCP relay servers (only
enabled for "Relay" DHCP servers).

DNS caching & DNS servers (optional)
++++++++++++++++++++++++++++++++++++++

.. note::
    For historical reasons, DHCP services can also be configured to perform DNS caching for a particular connected IP.
    Configuring any DNS caching options on a DHCP service will conflict with the stand-alone `DNS caching service <./dns-caching.html>`__
    for that connected IP.

If DNS caching is **disabled** on a DHCP service with **at least one DNS server** defined on the DHCP service,
the DHCP service will send those DNS servers to clients. A limit of 3 DNS servers can be defined on a single
DHCP service. If **no DNS servers** are defined, the DHCP service will send its own IP as a DNS server to clients,
which will forward client requests to the bonder's own upstream DNS servers.

If DNS caching is **enabled** on a DHCP service, the DHCP service will send its own IP as a DNS server to clients,
which will forward client requests to the bonder's own upstream DNS servers. If any DNS servers are defined on the
DHCP service, the bonder will also forward requests to these servers. A limit of 3 DNS servers can be defined on a single
DHCP service.

Custom configuration (optional)
++++++++++++++++++++++++++++++++

Add a raw dnsmasq configuration to configure more options. For example,
the following custom configuration would assign the address
``192.168.1.1`` to the host with MAC address ``aa:bb:cc:dd:ee:ff``.

.. code::

    dhcp-host=aa:bb:cc:dd:ee:ff,192.168.1.1


Viewing DHCP leases
--------------------

Monitor the currently leased IP addresses and MAC addresses by viewing
the following file:

.. code::

    cat /var/run/bonding/dnsmasq.leases


Viewing bonding-dnsmasq conf file
----------------------------------

The conf file is automatically generated on the bonder when a connected
IP is saved with DHCP enabled. You can run the following command to view
the file:

.. code::

    cat /var/run/bonding/dnsmasq.conf

The following option comes preconfigured in the conf file:

dhcp-client-update
^^^^^^^^^^^^^^^^^^^

Helps with DNS name resolution by allowing the client to attempt DDNS
updates with its name and IP address (useful option for Windows
clients).

Viewing bonding-dnsmasq log file
---------------------------------

The bonding-dnsmasq log files can be viewed for debugging purposes at:

.. code::

    journalctl /usr/lib/bonding/bin/dnsmasq  # for jessie nodes only

.. code::

    less /var/log/syslog | grep dnsmasq  # for wheezy and jessie nodes
