Skip to content

Commit 7d79f65

Browse files
MonviechMonviech
authored
dnsmasq: Add dhcp boot section to docs (opnsense#731)
1 parent 4991e77 commit 7d79f65

File tree

1 file changed

+116
-5
lines changed

1 file changed

+116
-5
lines changed

‎source/manual/dnsmasq.rst

Lines changed: 116 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,12 @@ General Settings
6060
Most settings are pretty straightforward here when the service is enabled, it should just start forwarding dns requests
6161
when received from the network. DHCP requires at least one dhcp-range and matching dhcp-options.
6262

63+
.. Tip::
64+
65+
- To disable the DNS feature, set the `Listen Port` to ``0``.
66+
- To disable the DHCP feature, select interfaces in `Interface [no dhcp]`.
67+
68+
6369
.. tabs::
6470

6571
.. tab:: General
@@ -90,9 +96,9 @@ when received from the network. DHCP requires at least one dhcp-range and matchi
9096
**Listen Port** The port used for responding to DNS queries. It should normally be left blank unless
9197
another service needs to bind to TCP/UDP port 53. Setting this to zero (0) completely
9298
disables DNS function.
93-
**DNSSEC**
99+
**DNSSEC** Enable DNSSEC.
94100
**No Hosts Lookup** Do not read hostnames in /etc/hosts.
95-
**Log the results of DNS queries**
101+
**Log the results of DNS queries** Log all DNS queries.
96102
**Maximum concurrent queries** Set the maximum number of concurrent DNS queries. On configurations with tight
97103
resources, this value may need to be reduced.
98104
**Cache size** Set the size of the cache. Setting the cache size to zero disables caching. Please
@@ -116,8 +122,7 @@ when received from the network. DHCP requires at least one dhcp-range and matchi
116122
**Require domain** If this option is set, we will not forward A or AAAA queries for plain names, without
117123
dots or domain parts, to upstream name servers. If the name is not known from /etc/hosts
118124
or DHCP then a "not found" answer is returned.
119-
**Do not forward private reverse** If this option is set, we will not forward reverse DNS lookups (PTR) for private
120-
**lookups**
125+
**Do not forward private reverse lookup** If this option is set, we will not forward reverse DNS lookups (PTR) for private
121126
addresses (RFC 1918) to upstream name servers. Any entries in the Domain Overrides
122127
section forwarding private "n.n.n.in-addr.arpa" names to a specific server are still
123128
forwarded. If the IP to name is not known from /etc/hosts, DHCP or a specific domain
@@ -207,7 +212,8 @@ DNS Settings
207212
**Hardware addresses** Match the hardware address of the client. Can be multiple addresses, e.g., if the client has
208213
multiple network cards. Though keep in mind that Dnsmasq cannot assume which address is the correct
209214
one when multiple send DHCP Discover at the same time.
210-
**Lease time** Defines how long the addresses (leases) given out by the server are valid (in seconds)
215+
**Lease time** Defines how long the addresses (leases) given out by the server are valid (in seconds).
216+
Set ``0`` for infinite.
211217
**Tag [set]** Optional tag to set for requests matching this range which can be used to selectively match DHCP options.
212218
**Ignore** Ignore any DHCP packets of this host. Useful if it should get served by a different DHCP server.
213219
**Description** You may enter a description here for your reference (not parsed).
@@ -273,6 +279,7 @@ DHCP Settings
273279
Going lower than that can pose issues in busy networks.
274280
**Mode** Mode flags to set for this range, 'static' means no addresses will be automatically assigned.
275281
**Lease time** Defines how long the addresses (leases) given out by the server are valid (in seconds).
282+
Set ``0`` for infinite; be careful as this might deplete the pool.
276283
**Domain** Offer the specified domain to machines in this range.
277284
**Disable HA sync** Ignore this range from being transferred or updated by HA sync.
278285
**Description** You may enter a description here for your reference (not parsed).
@@ -311,6 +318,19 @@ DHCP Settings
311318
**Description** You may enter a description here for your reference (not parsed).
312319
========================================= ====================================================================================
313320

321+
.. tab:: DHCP boot
322+
323+
========================================= ====================================================================================
324+
**Option** **Description**
325+
========================================= ====================================================================================
326+
**Interface** This adds a single interface as tag so this DHCP boot option can match the interface of a DHCP range.
327+
**Tag** Only offer this boot image to the clients matched by the given tag. Can be optionally combined with an interface tag.
328+
**Filename** The boot image file name.
329+
**Servername** The name of the server which serves the boot image.
330+
**Server address** The address of the server which serves the boot image.
331+
**Description** You may enter a description here for your reference (not parsed).
332+
========================================= ====================================================================================
333+
314334
.. tab:: DHCP tags
315335

316336
========================================= ====================================================================================
@@ -728,6 +748,97 @@ Option Value
728748
This ensures that only clients identifying as VoIP phones receive the appropriate TFTP server information via option 150. You can add
729749
additional options under the same tag if they should be offered to the VOIP phones.
730750

751+
DHCP boot
752+
------------------------------------------
753+
754+
In a network, we have different clients that should receive different boot images depending on if they require a BIOS or EFI boot.
755+
756+
By using DHCP tags, we can configure this behavior by matching DHCP options and combining them with a DHCP boot directive.
757+
758+
Go to :menuselection:`Services --> Dnsmasq DNS & DHCP --> DHCP tags` and create two tags:
759+
760+
.. tabs::
761+
762+
.. tab:: BIOS Tag
763+
764+
================================== =======================================================================================================
765+
Option Value
766+
================================== =======================================================================================================
767+
**Name** ``IsBIOS``
768+
================================== =======================================================================================================
769+
770+
.. tab:: EFI Tag
771+
772+
================================== =======================================================================================================
773+
Option Value
774+
================================== =======================================================================================================
775+
**Name** ``IsEFI``
776+
================================== =======================================================================================================
777+
778+
Go to :menuselection:`Services --> Dnsmasq DNS & DHCP --> DHCP options`
779+
780+
We will match the DHCP option ``client-arch[93]`` which has multiple possibilities when it comes to the client architecture.
781+
Value ``0`` matches `x86 BIOS` and value ``7`` matches `EFI BC (EFI x64)`. Choose the correct values to match your specific clients.
782+
783+
.. tabs::
784+
785+
.. tab:: BIOS Match Tag
786+
787+
================================== =======================================================================================================
788+
Option Value
789+
================================== =======================================================================================================
790+
**Type** Match
791+
**Option** ``client-arch[93]``
792+
**Tag [set]** ``IsBIOS``
793+
**Value** 0
794+
================================== =======================================================================================================
795+
796+
.. tab:: EFI Match Tag
797+
798+
================================== =======================================================================================================
799+
Option Value
800+
================================== =======================================================================================================
801+
**Type** Match
802+
**Option** ``client-arch[93]``
803+
**Tag [set]** ``IsEFI``
804+
**Value** 7
805+
================================== =======================================================================================================
806+
807+
Go to :menuselection:`Services --> Dnsmasq DNS & DHCP --> DHCP options --> DHCP boot`
808+
809+
Create two boot entries that serve the correct image to matching clients. We assume the requests are on LAN, though it can be left empty
810+
if these boot images should be served on any interfaces. Adjust IP addresses and filenames to fit your environment.
811+
812+
.. tabs::
813+
814+
.. tab:: BIOS Boot
815+
816+
========================================= ====================================================================================
817+
**Option** **Description**
818+
========================================= ====================================================================================
819+
**Interface** ``LAN``
820+
**Tag** ``IsBIOS``
821+
**Filename** ``undionly.kpxe``
822+
**Servername** ``192.168.99.10``
823+
**Server address** ``192.168.99.10``
824+
========================================= ====================================================================================
825+
826+
.. tabs::
827+
828+
.. tab:: EFI Boot
829+
830+
========================================= ====================================================================================
831+
**Option** **Description**
832+
========================================= ====================================================================================
833+
**Interface** ``LAN``
834+
**Tag** ``IsEFI``
835+
**Filename** ``snponly.efi``
836+
**Servername** ``192.168.99.10``
837+
**Server address** ``192.168.99.10``
838+
========================================= ====================================================================================
839+
840+
**Apply** the new configuration, and check the PXE boot server if clients request the correct boot image files.
841+
731842

732843
DHCPv4 for small HA setups
733844
------------------------------------------

0 commit comments

Comments
 (0)