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:
parent
b048b3da40
commit
92c6b5fcf3
@ -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.
|
||||||
|
Loading…
Reference in New Issue
Block a user