openstack
/
ironic-inspector
Code Issues Proposed changes

Merge "Dnsmasq filter docs follow-up"

This commit is contained in:
Zuul 2017-12-04 11:16:15 +00:00 committed by Gerrit Code Review
parent 4a68acd964 92c6b5fcf3
commit c4f5d64064
1 changed files with 46 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
doc/source/admin/dnsmasq-pxe-filter.rst
View File

@ -3,15 +3,17 @@
**dnsmasq** PXE filter
======================
Often an inspection PXE DHCP stack is implemented by the **dnsmasq** service.
This PXE filter implementation relies on directly configuring the **dnsmasq**
DHCP service to provide a caching PXE-traffic filter of node MAC addresses.
An inspection PXE DHCP stack is often implemented by the **dnsmasq** service.
The **dnsmasq** PXE filter implementation relies on directly configuring the
**dnsmasq** DHCP service to provide a caching PXE traffic filter of node MAC
addresses.
How it works
------------
Using a configuration *file per MAC address* allows one to implement a
filtering mechanism based on the ``ignore`` directive::
The filter works by populating the **dnsmasq** DHCP hosts directory with a
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
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
file parsing. The content of the file determines the MAC address access policy.
Thanks to the ``inotify`` facility, **dnsmasq** is notified instantly once a
new file is *created* or an existing file is *modified* in the
DHCP hosts directory. Thus, to white-list a MAC address, one has to
remove the ``ignore`` directive::
Thanks to the ``inotify`` facility, **dnsmasq** is notified once a new file is
*created* or an existing file is *modified* in the DHCP hosts directory. Thus,
to white-list a MAC address, the filter removes the ``ignore`` directive::
$ cat /etc/dnsmasq.d/de-ad-be-ef-de-ad
de:ad:be:ef:de:ad
@ -34,13 +35,20 @@ kept synchronized with the **ironic** port list.
.. 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.
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]
driver = dnsmasq
@ -52,13 +60,13 @@ The DHCP hosts directory can be specified to override the default
dhcp_hostsdir = /etc/ironic-inspector/dhcp-hostsdir
The filter design relies on the hosts directory being in exclusive
**inspector** control. The hosts directory should be considered a *private
cache* directory of **inspector** that **dnsmasq** polls configuration updates
from, through the ``inotify`` facility. The directory has to be writable by
**inspector** and readable by **dnsmasq**.
**ironic-inspector** control. The hosts directory should be considered a
*private cache* directory of **ionic-inspector** that **dnsmasq** polls
configuration updates from, through the ``inotify`` facility. The directory
has to be writable by **ironic-inspector** and readable by **dnsmasq**.
One can also override the default start and stop commands to control the
**dnsmasq** service::
It is also possible to override the default (empty) **dnsmasq** start and stop
commands to, for instance, directly control the **dnsmasq** service::
[dnsmasq_pxe_filter]
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::
It is also possible to set an empty/none string or to use shell expansion in
place of the commands. An empty start command means the **dnsmasq** service
won't be started upon the filter initialization, an empty stop command means
the service won't be stopped upon an (error) exit.
The commands support shell expansion. The default empty start command means
the **dnsmasq** service won't be started upon the filter initialization.
Conversely, the default empty stop command means the service won't be
stopped upon an (error) exit.
.. 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
sample configuration for **devstack** use might be:
sample configuration to use with the **systemctl** facility might be:
.. 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]
# ironic_inspector/pxe_filter/dnsmasq.py
systemctl: CommandFilter, systemctl, root, restart, devstack@ironic-inspector-dnsmasq
systemctl: CommandFilter, systemctl, root, stop, devstack@ironic-inspector-dnsmasq
systemctl: CommandFilter, systemctl, root, restart, dnsmasq
systemctl: CommandFilter, systemctl, root, stop, dnsmasq
EOF
Supported dnsmasq versions
--------------------------
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
.. _rootwrap: https://docs.openstack.org/oslo.rootwrap/latest/
Caveats
-------
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
minute of full CPU load for huge amounts of MACs (tens of thousands).
starting based on the amount of ports **ironic** keeps. The start-up can take
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
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
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
edited by hand. To minimize the interference between the deployment and
introspection, **inspector** has to start the **dnsmasq** service only after
the initial synchronization. Conversely, the **dnsmasq** service is stopped
upon (unexpected) **inspector** exit.
introspection, **ironic-inspector** has to start the **dnsmasq** service only
after the initial synchronization. Conversely, the **dnsmasq** service is
stopped upon (unexpected) **ironic-inspector** exit.
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**
service, it is recommended that the operator configures the **dnsmasq**
service in such a way that it terminates upon **inspector** (unexpected) exit
to prevent a stale blacklist from being used by the **dnsmasq** service.
service in such a way that it terminates upon **ironic-inspector**
(unexpected) exit to prevent a stale blacklist from being used by the
**dnsmasq** service.