From nobody Fri Apr 19 15:48:31 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 1552893625766879.5381709733726; Mon, 18 Mar 2019 00:20:25 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id C808F81DE0; Mon, 18 Mar 2019 07:20:23 +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 3EAE760C8A; Mon, 18 Mar 2019 07:20:23 +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 A05013FB11; Mon, 18 Mar 2019 07:20:22 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id x2I7JsjR025501 for ; Mon, 18 Mar 2019 03:19:54 -0400 Received: by smtp.corp.redhat.com (Postfix) id 4D80F5D704; Mon, 18 Mar 2019 07:19:54 +0000 (UTC) Received: from angien.brq.redhat.com (unknown [10.43.2.229]) by smtp.corp.redhat.com (Postfix) with ESMTP id CB1285EDE1 for ; Mon, 18 Mar 2019 07:19:53 +0000 (UTC) From: Peter Krempa To: libvir-list@redhat.com Date: Mon, 18 Mar 2019 08:19:49 +0100 Message-Id: <92cad8ce09405ba466bfbc035020e7023f0d1356.1552893522.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH 1/2] virsh: man: Document quirks of device-detach and friends 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: , 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.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.25]); Mon, 18 Mar 2019 07:20:24 +0000 (UTC) Content-Type: text/plain; charset="utf-8" Mention that successful return does not equal to device being detached similarly as we do at the API level. Signed-off-by: Peter Krempa Reviewed-by: Erik Skultety --- tools/virsh.pod | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/tools/virsh.pod b/tools/virsh.pod index 66e2bf24ec..39ff8cd7c9 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -3264,6 +3264,16 @@ or attempting to detach a device that is not present= in the domain XML, but shares some specific attributes with one that is present, may lead to unexpected results. +B: Device unplug is asynchronous in most cases and requires guest +cooperation. This means that it's up to the discretion of the guest to dis= allow +or delay the unplug arbitrarily. As the libvirt API used in this command w= as +designed as synchronous it returns success after some timeout even if the = device +was not unplugged yet to allow further interactions with the domain if the= guest +e.g. if the guest is unresponsive. Callers which need to make sure that the +device was unplugged can use libvirt events (see virsh event) to be notifi= ed +when the device is removed. Note that the even may arrive before the comma= nd +returns. + If I<--live> is specified, affect a running domain. If I<--config> is specified, affect the next startup of a persistent domai= n. If I<--current> is specified, affect the current domain state. @@ -3311,6 +3321,8 @@ I<--persistent>. If B<--print-xml> is specified, then the XML which would be used to detach= the disk is printed instead. +Please see documentation for B for known quirks. + =3Ditem B I I [I<--mac mac>] [[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]] @@ -3333,6 +3345,8 @@ an offline domain, and like I<--live> I<--config> for= a running domain. Note that older versions of virsh used I<--config> as an alias for I<--persistent>. +Please see documentation for B for known quirks. + =3Ditem B I I [I<--force>] [[[I<--live>] [I<--config>] | [I<--current>]] | [I<--persistent>]] --=20 2.20.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list From nobody Fri Apr 19 15:48:31 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 1552893630486235.20771058865353; Mon, 18 Mar 2019 00:20:30 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id B083E307D848; Mon, 18 Mar 2019 07:20:28 +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 8B3F960851; Mon, 18 Mar 2019 07:20:28 +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 44EE73FB14; Mon, 18 Mar 2019 07:20:28 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id x2I7JtcB025506 for ; Mon, 18 Mar 2019 03:19:55 -0400 Received: by smtp.corp.redhat.com (Postfix) id 1D4365D707; Mon, 18 Mar 2019 07:19:55 +0000 (UTC) Received: from angien.brq.redhat.com (unknown [10.43.2.229]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9A9625D704 for ; Mon, 18 Mar 2019 07:19:54 +0000 (UTC) From: Peter Krempa To: libvir-list@redhat.com Date: Mon, 18 Mar 2019 08:19:50 +0100 Message-Id: <23fec18fecc1e55fc7fae90fbb3279fdaf1f5e2e.1552893522.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH 2/2] virsh: man: Document asynchronous behaviour of detach-device-alias 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: , 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.13 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.48]); Mon, 18 Mar 2019 07:20:29 +0000 (UTC) Content-Type: text/plain; charset="utf-8" This command is fully async. Note that users can use virsh event to be notified of the guest actually removing the device. Signed-off-by: Peter Krempa Reviewed-by: Erik Skultety --- tools/virsh.pod | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index 39ff8cd7c9..2889e17531 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -3290,7 +3290,10 @@ I<--persistent>. =3Ditem B I I [[[I<--live>] [I<--config>] | [I<--current>]]]] -Detach a device with given I from the I. +Detach a device with given I from the I. This command retur= ns +successfully after the unplug request was sent to the hypervisor. The actu= al +removal of the device is notified asynchronously via libvirt events +(see virsh event). If I<--live> is specified, affect a running domain. If I<--config> is specified, affect the next startup of a persistent domai= n. --=20 2.20.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list