Allow undionly.kpxe boot option to be overridden

As an operator, I may wish to provide DHCP boot options for hosts not
managed by bifrost using the bifrost dnsmasq server.

If a dhcp-boot configuration option is provided to dnsmasq via a file in
/etc/dnsmasq.d/, and the server is not booted via iPXE, it will be
overridden by the undionly.kpxe option added by bifrost in
/etc/dnsmasq.conf.

This occurs because the negated tag match !ipxe used in the
/undionly.kpxe dhcp-boot entry will match all hosts not using iPXE. The
dhcp-boot entries are processed in order and the last matching entry
wins. Since the config-dir option appears before the dhcp-boot options,
user-provided options are processed first and are therefore overridden.

The solution here is fairly simple - use a positive match for the ipxe
tag:

dhcp-boot=tag:ipxe,http://host:port/boot.ipxe
dhcp-boot=/undionly.kpxe

An entry with a tag will always win over the entry without a tag
specified, so it is now possible to add a rule to override
undionly.kpxe.

Change-Id: Ic0637e14504def73fbc0333eee9dc2456c57c32e
Closes-Bug: #1675367

doc/source/deploy/dhcp.rst

@@ -1,3 +1,53 @@
+Configuring the integrated DHCP server
+======================================
+
+Setting static DHCP assignments with the integrated DHCP server
+---------------------------------------------------------------
+
+You can set up a static DHCP reservation using the ``ipv4_address`` parameter
+and setting the ``inventory_dhcp`` setting to a value of ``true``.  This will
+result in the first MAC address defined in the list of hardware MAC addresses
+to receive a static address assignment in dnsmasq.
+
+Forcing DNS to resolve to ipv4_address
+--------------------------------------
+
+dnsmasq will resolve all entries to the IP assigned to each server in
+the leases file. However, this IP will not always be the desired one, if you
+are working with multiple networks.
+To force DNS to always resolve to ``ipv4_address`` please set the
+``inventory_dns`` setting to a value of ``true``. This will result in each
+server to resolve to ``ipv4_address`` by explicitly using address capabilities
+of dnsmasq.
+
+Extending dnsmasq configuration
+-------------------------------
+
+Bifrost manages the dnsmasq configuration file in ``/etc/dnsmasq.conf``. It is
+not recommended to make manual modifications to this file after it has been
+written.  dnsmasq supports the use of additional configuration files in
+``/etc/dnsmasq.d``, allowing extension of the dnsmasq configuration provided by
+bifrost.  It is possible to use this mechanism provide additional DHCP options
+to systems managed by ironic, or even to create a DHCP boot environment for
+systems not managed by ironic. For example, create a file
+``/etc/dnsmasq.d/example.conf`` with the following contents::
+
+    dhcp-match=set:<tag>,<match criteria>
+    dhcp-boot=tag:<tag>,<boot options>
+
+The tag, match critera and boot options should be modified for your
+environment.  Here we use dnsmasq tags to match against hosts that we want to
+manage.  dnsmasq will use the last matching tagged ``dhcp-boot`` option for a
+host or an untagged default ``dhcp-boot`` option if there were no matches.
+These options will be inserted at the ``conf-dir=/etc/dnsmasq.d`` line of the
+dnsmasq configuration file.  Once configured, send the ``HUP`` signal to
+dnsmasq, which will cause it to reread its configuration::
+
+    killall -HUP dnsmasq
+
+Using Bifrost with your own DHCP server
+=======================================
+
 The possibility exists that a user may already have a Dynamic Host
 Configuration Protocol (DHCP) server on their network.
 
@@ -23,8 +73,8 @@ depending on the environment configuration.
 dnsmasq::
 
     dhcp-match=set:ipxe,175 # iPXE sends a 175 option.
-    dhcp-boot=tag:!ipxe,/undionly.kpxe,<TFTP Server Hostname>,<TFTP Server IP Address>
+    dhcp-boot=tag:ipxe,http://<Bifrost Host IP Address>:8080/boot.ipxe
-    dhcp-boot=http://<Bifrost Host IP Address>:8080/boot.ipxe
+    dhcp-boot=/undionly.kpxe,<TFTP Server Hostname>,<TFTP Server IP Address>
 
 Internet Systems Consortium DHCPd::
 
@@ -53,22 +103,3 @@ in a trusted environment.
           +-------------+       +-----------+
           |Ironic Server|       |   Server  |
           +-------------+       +-----------+
-
-Setting static DHCP assignments with the integrated DHCP server
----------------------------------------------------------------
-
-You can set up a static DHCP reservation using the ``ipv4_address`` parameter
-and setting the ``inventory_dhcp`` setting to a value of ``true``.  This will
-result in the first MAC address defined in the list of hardware MAC addresses
-to receive a static address assignment in dnsmasq.
-
-Forcing DNS to resolve to ipv4_address
---------------------------------------
-
-dnsmasq will resolve all entries to the IP assigned to each server in
-the leases file. However, this IP will not always be the desired one, if you
-are working with multiple networks.
-To force DNS to always resolve to ``ipv4_address`` please set the
-``inventory_dns`` setting to a value of ``true``. This will result in each
-server to resolve to ``ipv4_address`` by explicitly using address capabilities
-of dnsmasq.

doc/source/howto.rst

@@ -317,8 +317,6 @@ If you wish to include an extra element into the IPA disk image, such as a
 custom hardware manager, you can pass the variable ``ipa_extra_dib_elements``
 as a space-separated list of elements. This defaults to an empty string.
 
-Use Bifrost with your own DHCP server
-=====================================
 .. include:: deploy/dhcp.rst
 
 Use Bifrost with Keystone

playbooks/roles/bifrost-ironic-install/templates/dnsmasq.conf.j2

@@ -94,13 +94,15 @@ dhcp-userclass=set:gpxe,"gPXE"
 dhcp-boot=tag:gpxe,/ipxe.pxe
 
 dhcp-match=set:ipxe,175 # iPXE sends a 175 option.
-dhcp-boot=tag:!ipxe,/undionly.kpxe
 {% if testing | bool == true %}
-dhcp-boot=http://192.168.122.1:{{ file_url_port }}/boot.ipxe
+dhcp-boot=tag:ipxe,http://192.168.122.1:{{ file_url_port }}/boot.ipxe
 {% else %}
-dhcp-boot=http://{{ hostvars[inventory_hostname]['ansible_' + ans_network_interface]['ipv4']['address'] }}:{{ file_url_port }}/boot.ipxe
+dhcp-boot=tag:ipxe,http://{{ hostvars[inventory_hostname]['ansible_' + ans_network_interface]['ipv4']['address'] }}:{{ file_url_port }}/boot.ipxe
 {% endif %}
 
+# Catch-all boot options used when no other boot options are matched.
+dhcp-boot=/undionly.kpxe
+
 {% if testing | bool == true %}
 log-queries
 log-dhcp

releasenotes/notes/override-dhcp-boot-6659585b75d58757.yaml

@@ -0,0 +1,17 @@
+---
+fixes:
+  - |
+    Allows ``undionly.kpxe`` boot option to be overridden.
+
+    As an operator, I may wish to provide DHCP boot options for hosts not
+    managed by bifrost using the bifrost dnsmasq server.
+
+    Previously, if a ``dhcp-boot`` configuration option was provided to dnsmasq
+    via a file in ``/etc/dnsmasq.d/``, and the server was not booted via iPXE,
+    the option would have been overridden by the ``undionly.kpxe`` option added
+    by bifrost in ``/etc/dnsmasq.conf``.
+
+    Bifrost now supports user-provided ``dhcp-boot`` options in
+    ``/etc/dnsmasq.d``. These should be specified with an appropriate set of
+    tags to match against to ensure that the rule overrides the default rule
+    configured by bifrost.