Dnsmasq filter docs follow-up

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

Change-Id: If3e4ac1fcc3d3be1508086db122a11df71e7e3e6

doc/source/admin/dnsmasq-pxe-filter.rst

@@ -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.