From 81d6db6e7af7d9f159cfb1c5b7bfc7b6f16b4b23 Mon Sep 17 00:00:00 2001

Message-Id: <81d6db6e7af7d9f159cfb1c5b7bfc7b6f16b4b23@dist-git>

From: John Ferlan <jferlan@redhat.com>

Date: Wed, 3 Apr 2019 07:04:46 -0400

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

MIME-Version: 1.0

Content-Type: text/plain; charset=UTF-8

Content-Transfer-Encoding: 8bit

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

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

(cherry picked from commit b4833917f12a0ffa4b5957ef77edea737cb8ad58)

Message-Id: <20190403110446.15118-1-jferlan@redhat.com>

Reviewed-by: Erik Skultety <eskultet@redhat.com>

---

 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 368ce89ed8..0e704bc407 100644

--- a/tools/virsh.pod

+++ b/tools/virsh.pod

@@ -4825,13 +4825,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.21.0