From 81d6db6e7af7d9f159cfb1c5b7bfc7b6f16b4b23 Mon Sep 17 00:00:00 2001 Message-Id: <81d6db6e7af7d9f159cfb1c5b7bfc7b6f16b4b23@dist-git> From: John Ferlan 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 Reviewed-by: Daniel P. Berrangé (cherry picked from commit b4833917f12a0ffa4b5957ef77edea737cb8ad58) Message-Id: <20190403110446.15118-1-jferlan@redhat.com> Reviewed-by: Erik Skultety --- 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 I 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 I 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. =item B -- 2.21.0