[libvirt] [PATCH] nwfilter: Add extra verbiage for binding create/delete

[John Ferlan]

https://bugzilla.redhat.com/show_bug.cgi?id=1609454

Add some cautionary words related to the create and delete
NWFilter Binding use cases and possible issues that may result
to the virsh nwfilter-binding-{create|delete} descriptions
and the virNWFilterBinding{CreateXML|Delete) API descriptions.

Essentially summarizing commit 2d9318b6c without using the
shoot yourself in the foot wording.

Signed-off-by: John Ferlan <jferlan at redhat.com>
---
 Perhaps not the exact "answer" for the bz; however, using the bz as the
 excuse to say it was a bit confusing and let's try to clarify the wording
 a bit more.

 src/libvirt-nwfilter.c | 16 ++++++++++++++--
 tools/virsh.pod        | 14 ++++++++++++--
 2 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/src/libvirt-nwfilter.c b/src/libvirt-nwfilter.c
index e572d46c18..3da85adc9e 100644
--- a/src/libvirt-nwfilter.c
+++ b/src/libvirt-nwfilter.c
@@ -678,7 +678,14 @@ virNWFilterBindingGetFilterName(virNWFilterBindingPtr binding)
  * @flags: currently unused, pass 0
  *
  * Define a new network filter, based on an XML description
- * similar to the one returned by virNWFilterGetXMLDesc()
+ * similar to the one returned by virNWFilterGetXMLDesc(). This
+ * API may be used to associate a filter with a currently running
+ * guest that does not have a filter defined for a specific network
+ * port. Since the bindings are generally automatically managed by
+ * the hypervisor, using this command to define a filter for a network
+ * port and then starting the guest afterwards may prevent the guest
+ * from starting if it attempts to use the network port and finds a
+ * filter already defined.
  *
  * virNWFilterFree should be used to free the resources after the
  * binding object is no longer needed.
@@ -717,7 +724,12 @@ virNWFilterBindingCreateXML(virConnectPtr conn, const char *xml, unsigned int fl
  * @binding: a binding object
  *
  * Delete the binding object. This does not free the
- * associated virNWFilterBindingPtr object.
+ * associated virNWFilterBindingPtr object. This API
+ * may be used to remove the network port binding filter
+ * currently in use for the guest while the guest is
+ * running without needing to restart the guest. Restoring
+ * the network port binding filter for the running guest
+ * would be accomplished by using virNWFilterBindingCreateXML.
  *
  * Returns 0 in case of success and -1 in case of failure.
  */
diff --git a/tools/virsh.pod b/tools/virsh.pod
index 4e118851f8..86c041d575 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -4836,13 +4836,23 @@ of the network filters directly.
 =item B<nwfilter-binding-create> I<xmlfile>
 
 Associate a network port with a network filter. The network filter backend
-will immediately attempt to instantiate the filter rules on the port.
+will immediately attempt to instantiate the filter rules on the port. This
+command may be used to associate a filter with a currently running guest
+that does not have a filter defined for a specific network port. Since the
+bindings are generally automatically managed by the hypervisor, using this
+command to define a filter for a network port and then starting the guest
+afterwards may prevent the guest from starting if it attempts to use the
+network port and finds a filter already defined.
 
 =item B<nwfilter-binding-delete> I<port-name>
 
 Disassociate a network port from a network filter. The network filter
 backend will immediately tear down the filter rules that exist on the
-port.
+port. This command may be used to remove the network port binding for
+a filter currently in use for the guest while the guest is running
+without needing to restart the guest. Restoring the network port binding
+filter for the running guest would be accomplished by using
+I<nwfilter-binding-create>.
 
 =item B<nwfilter-binding-list>
 
-- 
2.17.1