From nobody Sat May 18 21:16:03 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1534977981545310.4610673322469; Wed, 22 Aug 2018 15:46:21 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id E58A980F7C; Wed, 22 Aug 2018 22:46:16 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id DB8277EE3C; Wed, 22 Aug 2018 22:46:15 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 81E1E4BB75; Wed, 22 Aug 2018 22:46:11 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx09.intmail.prod.int.phx2.redhat.com [10.5.11.24]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w7MMk9Eu001897 for ; Wed, 22 Aug 2018 18:46:09 -0400 Received: by smtp.corp.redhat.com (Postfix) id 6465B308BDA4; Wed, 22 Aug 2018 22:46:09 +0000 (UTC) Received: from unknown54ee7586bd10.attlocal.net.com (ovpn-116-58.phx2.redhat.com [10.3.116.58]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1D53B308BE72 for ; Wed, 22 Aug 2018 22:46:06 +0000 (UTC) From: John Ferlan To: libvir-list@redhat.com Date: Wed, 22 Aug 2018 18:46:03 -0400 Message-Id: <20180822224603.23652-1-jferlan@redhat.com> X-Scanned-By: MIMEDefang 2.84 on 10.5.11.24 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH] nwfilter: Add extra verbiage for binding create/delete X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.27]); Wed, 22 Aug 2018 22:46:19 +0000 (UTC) X-ZohoMail: RDMRC_0 RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" https://bugzilla.redhat.com/show_bug.cgi?id=3D1609454 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=C3=A9 --- 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. =3Ditem B I =20 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. =20 =3Ditem B I =20 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. =20 =3Ditem B =20 --=20 2.17.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list