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

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(a)redhat.com&gt; --- 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