Dnsmasq filter docs follow-up

This is a follow-up patch to address documentation nits from the patch:
  I63fe91ee4f9ac3021bcfd9a4a378af56af800fac

Change-Id: If3e4ac1fcc3d3be1508086db122a11df71e7e3e6
This commit is contained in:
dparalen 2017-11-28 15:16:18 +01:00
parent b048b3da40
commit 92c6b5fcf3

View File

@ -3,15 +3,17 @@
**dnsmasq** PXE filter **dnsmasq** PXE filter
====================== ======================
Often an inspection PXE DHCP stack is implemented by the **dnsmasq** service. An inspection PXE DHCP stack is often implemented by the **dnsmasq** service.
This PXE filter implementation relies on directly configuring the **dnsmasq** The **dnsmasq** PXE filter implementation relies on directly configuring the
DHCP service to provide a caching PXE-traffic filter of node MAC addresses. **dnsmasq** DHCP service to provide a caching PXE traffic filter of node MAC
addresses.
How it works How it works
------------ ------------
Using a configuration *file per MAC address* allows one to implement a The filter works by populating the **dnsmasq** DHCP hosts directory with a
filtering mechanism based on the ``ignore`` directive:: configuration file per MAC address. Each file is either enabling or disabling,
thru the ``ignore`` directive, the DHCP service for a particular MAC address::
$ cat /etc/dnsmasq.d/de-ad-be-ef-de-ad $ cat /etc/dnsmasq.d/de-ad-be-ef-de-ad
de:ad:be:ef:de:ad,ignore de:ad:be:ef:de:ad,ignore
@ -20,10 +22,9 @@ filtering mechanism based on the ``ignore`` directive::
The filename is used to keep track of all MAC addresses in the cache, avoiding The filename is used to keep track of all MAC addresses in the cache, avoiding
file parsing. The content of the file determines the MAC address access policy. file parsing. The content of the file determines the MAC address access policy.
Thanks to the ``inotify`` facility, **dnsmasq** is notified instantly once a Thanks to the ``inotify`` facility, **dnsmasq** is notified once a new file is
new file is *created* or an existing file is *modified* in the *created* or an existing file is *modified* in the DHCP hosts directory. Thus,
DHCP hosts directory. Thus, to white-list a MAC address, one has to to white-list a MAC address, the filter removes the ``ignore`` directive::
remove the ``ignore`` directive::
$ cat /etc/dnsmasq.d/de-ad-be-ef-de-ad $ cat /etc/dnsmasq.d/de-ad-be-ef-de-ad
de:ad:be:ef:de:ad de:ad:be:ef:de:ad
@ -34,13 +35,20 @@ kept synchronized with the **ironic** port list.
.. note:: .. note::
The **dnsmasq** inotify facility implementation doesn't react on a file being The **dnsmasq** inotify facility implementation doesn't react to a file being
removed or truncated. removed or truncated.
Configuration Configuration
------------- -------------
To enable the **dnsmasq** PXE filter, update the PXE filter driver name:: The ``inotify`` facility was introduced_ to **dnsmasq** in the version `2.73`.
This filter driver has been checked by **ironic-inspector** CI with
**dnsmasq** versions `>=2.76`.
.. _introduced: http://www.thekelleys.org.uk/dnsmasq/CHANGELOG
To enable the **dnsmasq** PXE filter, update the PXE filter driver name in the
**ironic-inspector** configuration file::
[pxe_filter] [pxe_filter]
driver = dnsmasq driver = dnsmasq
@ -52,13 +60,13 @@ The DHCP hosts directory can be specified to override the default
dhcp_hostsdir = /etc/ironic-inspector/dhcp-hostsdir dhcp_hostsdir = /etc/ironic-inspector/dhcp-hostsdir
The filter design relies on the hosts directory being in exclusive The filter design relies on the hosts directory being in exclusive
**inspector** control. The hosts directory should be considered a *private **ironic-inspector** control. The hosts directory should be considered a
cache* directory of **inspector** that **dnsmasq** polls configuration updates *private cache* directory of **ionic-inspector** that **dnsmasq** polls
from, through the ``inotify`` facility. The directory has to be writable by configuration updates from, through the ``inotify`` facility. The directory
**inspector** and readable by **dnsmasq**. has to be writable by **ironic-inspector** and readable by **dnsmasq**.
One can also override the default start and stop commands to control the It is also possible to override the default (empty) **dnsmasq** start and stop
**dnsmasq** service:: commands to, for instance, directly control the **dnsmasq** service::
[dnsmasq_pxe_filter] [dnsmasq_pxe_filter]
dnsmasq_start_command = dnsmasq --conf-file /etc/ironic-inspector/dnsmasq.conf dnsmasq_start_command = dnsmasq --conf-file /etc/ironic-inspector/dnsmasq.conf
@ -66,58 +74,53 @@ One can also override the default start and stop commands to control the
.. note:: .. note::
It is also possible to set an empty/none string or to use shell expansion in The commands support shell expansion. The default empty start command means
place of the commands. An empty start command means the **dnsmasq** service the **dnsmasq** service won't be started upon the filter initialization.
won't be started upon the filter initialization, an empty stop command means Conversely, the default empty stop command means the service won't be
the service won't be stopped upon an (error) exit. stopped upon an (error) exit.
.. note:: .. note::
These commands are executed through the ``rootwrap`` facility, so overriding These commands are executed through the rootwrap_ facility, so overriding
may require a filter file to be created in the ``rootwrap.d`` directory. A may require a filter file to be created in the ``rootwrap.d`` directory. A
sample configuration for **devstack** use might be: sample configuration to use with the **systemctl** facility might be:
.. code-block:: console .. code-block:: console
sudo cat > "$IRONIC_INSPECTOR_CONF_DIR/rootwrap.d/ironic-inspector-dnsmasq-systemctl.filters" <<EOF sudo cat > /etc/ironic-inspector/rootwrap.d/ironic-inspector-dnsmasq-systemctl.filters <<EOF
[Filters] [Filters]
# ironic_inspector/pxe_filter/dnsmasq.py # ironic_inspector/pxe_filter/dnsmasq.py
systemctl: CommandFilter, systemctl, root, restart, devstack@ironic-inspector-dnsmasq systemctl: CommandFilter, systemctl, root, restart, dnsmasq
systemctl: CommandFilter, systemctl, root, stop, devstack@ironic-inspector-dnsmasq systemctl: CommandFilter, systemctl, root, stop, dnsmasq
EOF EOF
Supported dnsmasq versions .. _rootwrap: https://docs.openstack.org/oslo.rootwrap/latest/
--------------------------
This filter driver has been checked by **inspector** CI with **dnsmasq**
versions `>=2.76`. The ``inotify`` facility was introduced_ to **dnsmasq** in
the version `2.73`.
.. _introduced: http://www.thekelleys.org.uk/dnsmasq/CHANGELOG
Caveats Caveats
------- -------
The initial synchronization will put some load on the **dnsmasq** service The initial synchronization will put some load on the **dnsmasq** service
starting based on the amount of ports **ironic** keeps. This can take up to a starting based on the amount of ports **ironic** keeps. The start-up can take
minute of full CPU load for huge amounts of MACs (tens of thousands). up to a minute of full CPU load for huge amounts of MACs (tens of thousands).
Subsequent filter synchronizations will only cause the **dnsmasq** to parse Subsequent filter synchronizations will only cause the **dnsmasq** to parse
the modified files. Typically those are the bare metal nodes being added or the modified files. Typically those are the bare metal nodes being added or
phased out from the compute service, meaning dozens of file updates per sync phased out from the compute service, meaning dozens of file updates per sync
call. call.
The **inspector** takes over the control of the DHCP hosts directory to The **ironic-inspector** takes over the control of the DHCP hosts directory to
implement its filter cache. Files are generated dynamically so should not be implement its filter cache. Files are generated dynamically so should not be
edited by hand. To minimize the interference between the deployment and edited by hand. To minimize the interference between the deployment and
introspection, **inspector** has to start the **dnsmasq** service only after introspection, **ironic-inspector** has to start the **dnsmasq** service only
the initial synchronization. Conversely, the **dnsmasq** service is stopped after the initial synchronization. Conversely, the **dnsmasq** service is
upon (unexpected) **inspector** exit. stopped upon (unexpected) **ironic-inspector** exit.
To avoid accumulating stale DHCP host files over time, the driver cleans up To avoid accumulating stale DHCP host files over time, the driver cleans up
the DHCP hosts directory during the ``init_filter`` call. the DHCP hosts directory before the initial synchronization during the
start-up.
Although the filter driver tries its best to always stop the **dnsmasq** Although the filter driver tries its best to always stop the **dnsmasq**
service, it is recommended that the operator configures the **dnsmasq** service, it is recommended that the operator configures the **dnsmasq**
service in such a way that it terminates upon **inspector** (unexpected) exit service in such a way that it terminates upon **ironic-inspector**
to prevent a stale blacklist from being used by the **dnsmasq** service. (unexpected) exit to prevent a stale blacklist from being used by the
**dnsmasq** service.