From nobody Thu Apr 25 12:25:10 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=fail(p=quarantine dis=quarantine) header.from=suse.com Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1641591519410131.0929931977346; Fri, 7 Jan 2022 13:38:39 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-422-aoFk7qB-OjOpUOEGoveP_g-1; Fri, 07 Jan 2022 16:38:36 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 9145481CCB9; Fri, 7 Jan 2022 21:38:31 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 7EA4756F78; Fri, 7 Jan 2022 21:38:29 +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 434DB1809CB8; Fri, 7 Jan 2022 21:38:26 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx09.intmail.prod.int.rdu2.redhat.com [10.11.54.9]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 207LcOOv029554 for ; Fri, 7 Jan 2022 16:38:24 -0500 Received: by smtp.corp.redhat.com (Postfix) id 58950492D51; Fri, 7 Jan 2022 21:38:24 +0000 (UTC) Received: from mimecast-mx02.redhat.com (mimecast02.extmail.prod.ext.rdu2.redhat.com [10.11.55.18]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 53465492D4E for ; Fri, 7 Jan 2022 21:38:24 +0000 (UTC) Received: from us-smtp-1.mimecast.com (us-smtp-1.mimecast.com [205.139.110.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id F402E800B36 for ; Fri, 7 Jan 2022 21:38:23 +0000 (UTC) Received: from de-smtp-delivery-102.mimecast.com (de-smtp-delivery-102.mimecast.com [194.104.109.102]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-168-HISqRHuEMWaMoNaiSTeFbQ-1; Fri, 07 Jan 2022 16:38:22 -0500 Received: from EUR04-DB3-obe.outbound.protection.outlook.com (mail-db3eur04lp2059.outbound.protection.outlook.com [104.47.12.59]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id de-mta-19-pKe6Lux8Pc2Q8MM0ldsZRg-1; Fri, 07 Jan 2022 22:38:20 +0100 Received: from AM0PR04MB4899.eurprd04.prod.outlook.com (2603:10a6:208:c5::16) by AM0PR04MB4292.eurprd04.prod.outlook.com (2603:10a6:208:67::19) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4867.7; Fri, 7 Jan 2022 21:38:18 +0000 Received: from AM0PR04MB4899.eurprd04.prod.outlook.com ([fe80::d5d2:21c0:eae6:3aea]) by AM0PR04MB4899.eurprd04.prod.outlook.com ([fe80::d5d2:21c0:eae6:3aea%5]) with mapi id 15.20.4867.011; Fri, 7 Jan 2022 21:38:18 +0000 X-MC-Unique: aoFk7qB-OjOpUOEGoveP_g-1 X-MC-Unique: HISqRHuEMWaMoNaiSTeFbQ-1 X-MC-Unique: pKe6Lux8Pc2Q8MM0ldsZRg-1 From: Jim Fehlig To: libvir-list@redhat.com Subject: [PATCH] docs: Add man page for libvirt-guests Date: Fri, 7 Jan 2022 14:38:15 -0700 Message-ID: <20220107213815.17863-1-jfehlig@suse.com> X-ClientProxiedBy: AS8P251CA0009.EURP251.PROD.OUTLOOK.COM (2603:10a6:20b:2f2::34) To AM0PR04MB4899.eurprd04.prod.outlook.com (2603:10a6:208:c5::16) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: ed205239-b36b-46ee-916b-08d9d22604da X-MS-TrafficTypeDiagnostic: AM0PR04MB4292:EE_ X-Microsoft-Antispam-PRVS: X-MS-Oob-TLC-OOBClassifiers: OLM:8273 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0 X-Microsoft-Antispam-Message-Info: 4BhiiP2DPdAdusA6c/HIptdJjQsApVbkUOyPTiJK+/6XXNrzKyKXS5ew+oHoPBKgbPwV4XMC+vG4Gr7blwm+EXaPb8kLTp3xsES7puyrTtbarr/MfSUhX4sTZcGFeAcabrdFbV6LaYn6Xj2JvptRzIMKwZL7s4aym3PZJGrtCEgLJUrCFV4zBgzBikVezAU7+px1k1Uqj+XlaRtpj0XgsvqInsg2LW3uuNRhdfSTOrUJjbhstRxjmq8y6ZeNkS+YcW8L4EYUOD+GqlSB77V+aroHq3p2UBcgphDd0lAE8B2+kJcFUHPyE6S82YZFcLfjR/OkVaBS+6REC2vuK0KWBjDK16Z9bkRMUDueDRbbknDtDXT8xU6tM2kq0yfkLqaQ7ECb8AhOaoGe5W3D6n0tNuMhwlJmA/KDrjss7tIkm+D6KzfrvEibvmCH8k+iZzpOyFPv0EEA7a9mqnTVfIs86jqgFWD8vUlXNtX+l7ITmMQrYKtfOYbOOCCmtLQ8VCXLKnBimvXWKJTAXP2Lk68SBf/Ae1IYOVNIxweHtpmHNystXfKwhxzrNQa7qDNV9ofjkJtJHDuu8K0OQuV6Rh5sSJjVJxVldv9+7aYGu46UtepGfo721T8Wzi18Bov063hviezU7UektBLfq+BiultZrz2rvmEqSc2L3R1cHnuT+9JAQhs3Gbxqbu5E1wOnFcYWo6qAZsR35wh1NGxNGt7h+CTMwu8b4URENN/3JH26lxe850ZWZ4Nb60267kAj7PT30afEmLlSYJXczzO3ma8DPBJ6VMZGWhmshC5r4WqTS/MCwZT9i8eV6QXIDt7k3JX3 X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:AM0PR04MB4899.eurprd04.prod.outlook.com; PTR:; CAT:NONE; SFS:(366004)(83380400001)(5660300002)(66946007)(36756003)(66556008)(66476007)(38100700002)(8936002)(6486002)(8676002)(6916009)(1076003)(2906002)(508600001)(6666004)(2616005)(86362001)(6512007)(6506007)(186003)(26005)(316002)(2004002); DIR:OUT; SFP:1101 X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?BZDcWLQNTRGsTLd4B247mfD0pDEGipFNuRxO4N4YKvRFSfLJMJuA3cfN3AVZ?= =?us-ascii?Q?55jr2iJg6yjjaAfhcNdkbBhGLZsZ9F6MEzj2ioNuuUvi3QCPiErh5r/fManx?= =?us-ascii?Q?gDGfyH2UmSJu3BjoBZE3bBGc3XdSvYhFF/Xwyxua+bi+n+1k/CYuJyMi+CW9?= =?us-ascii?Q?Ovk4nvU8n+d3AaqW6h7bZFAQnrNnZsPeg20z8oo9WUW7ueFtPpnbV/0MfbTK?= =?us-ascii?Q?n76SRVO3BKGr6zalpVffYacMEDQx0zM5aOr6b1qEFUBm3JfkchNQ7KokK0Z+?= =?us-ascii?Q?nN6dw/+idmFppwVzBdkk/HDlfnn/e3p7R1FUT5/PiubvwtmHXKptmZY/1R4p?= =?us-ascii?Q?+3fw7/l6dkc+1MT7NvKBrmqmCWyzPtEeH4YOg7muhj7x2NC1zVt3H5/rB8Ys?= =?us-ascii?Q?xkB6LllhrNGt/8UY/+U1YoqK9UnYWKRGY8M+NIwD0jxE9t6178UUcHXn6Ycl?= =?us-ascii?Q?jnvQM8dBGz0HE6jLL5GxC7CDGLqNqHFmPL0ebPJTR8sNh8vZ/5/QpP34hYkJ?= =?us-ascii?Q?wchhACwuhezBe5vG9IW3CAmoKgIWTuEjkPOPRzSAWrnVO9+bKadKj+s3RArM?= =?us-ascii?Q?Ck88ohxa7mcG5RjYpeegH60ChJrSkIoosr0LxtSYkYv6QkuWB2cHF7eCIK9n?= =?us-ascii?Q?7ps/XrWt2BOECNORWENtTstT+7A+N9AiKMXyMmfb4ePga/U1A2KhMl8bWGZI?= =?us-ascii?Q?UB+XQWBcVC6SXN3xp/OXSAugCjtGApSP0XOd6or42y9Ry9MG+WbeAX2z8tD5?= =?us-ascii?Q?qMPZZ+C0hGZZD1usln8OsNn1upArdfhT9EM2LniJgREDKd29ZWA1HPu//54V?= =?us-ascii?Q?JJQqjoqmSi3eAA7OdnJToxR1rSxTdASPrs1sqS6T4XzFnHj02Un6Lpu9g7+Z?= =?us-ascii?Q?QYv/gCLnVCGyR2uwswMYSZ8PP/+RtCSJS/1J6WnEpK5clIF6M9PSURfqHqiX?= =?us-ascii?Q?pKL2i3ZSKI+VHuj0ukRJbnqeE8mVnr6jYkuGiisGwgjybiv5hTrt5fvKjX4n?= =?us-ascii?Q?pgEan2nnXKdz1qNtaREOa7kO0bKdoDOpwYtkxMcOj3PGSY/dxyjHZDehqKJV?= =?us-ascii?Q?phXF3vIxMFuNMX65W8+Efj63Yia4Ait67b8ZlaYXZvce3Kw8538DRMki0eMM?= =?us-ascii?Q?ptRaF5i2pWR1N8sxUswKoHaXwR77+QXtMTVV6hsPDiud5SSTlYKo3DXQHU1/?= =?us-ascii?Q?Motzv3rS2t3iHKsP9AvlIIVNqICw+KjEgTGdiKCErs7h5JVM6F1NlykYa/78?= =?us-ascii?Q?gelcFa3fu+H6s5njwQN0eggLpAb+jRKKf9uJVAEONg9gc4bCkCC5VN2WuX3o?= =?us-ascii?Q?FdMPTMtxsJ4dsJHslgPBOpLF6lGD57XdkSKdLx+P+1mE1uSAuWeLA5UFvk3x?= =?us-ascii?Q?K3zEeYTbp2DNS7vjjp9NtOb8RlU4Ij2WaX7oZa+MxZ3sm+cqdmLGsEfvj0Xh?= =?us-ascii?Q?parS8qVEyB1RossoxbsVGXyDK1h3w/qii+OtrbJhyY9O7uPldbF7399lSxvC?= =?us-ascii?Q?1hPeo8e20RvMWx82oFh3T0vOk3a4tKY2Zp/sKkjk2uwMZ1dAKRgu4tM4ndGm?= =?us-ascii?Q?qqFHxVb6R2Wa3wtpzo7YsrK7N5WTiur35H8Ox2b6E9Xuss06z4r3qBOvxwBf?= =?us-ascii?Q?RHqDhzqyJWdz19tArV6u5hY=3D?= X-OriginatorOrg: suse.com X-MS-Exchange-CrossTenant-Network-Message-Id: ed205239-b36b-46ee-916b-08d9d22604da X-MS-Exchange-CrossTenant-AuthSource: AM0PR04MB4899.eurprd04.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 07 Jan 2022 21:38:18.4315 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: f7a17af6-1c5c-4a36-aa8b-f5be247aa4ba X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: w9Y4d1FLJ4ldX8ApPjhYaKugZiPeCzMftEuOUdtOScZH8de611VI/tHGq7n8B59hOy1LJuPmEi9dwXM6/EQfNg== X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM0PR04MB4292 X-Mimecast-Impersonation-Protect: Policy=CLT - Impersonation Protection Definition; Similar Internal Domain=false; Similar Monitored External Domain=false; Custom External Domain=false; Mimecast External Domain=false; Newly Observed Domain=false; Internal User Name=false; Custom Display Name List=false; Reply-to Address Mismatch=false; Targeted Threat Dictionary=false; Mimecast Threat Dictionary=false; Custom Threat Dictionary=false X-Scanned-By: MIMEDefang 2.85 on 10.11.54.9 X-MIME-Autoconverted: from quoted-printable to 8bit by lists01.pubmisc.prod.ext.phx2.redhat.com id 207LcOOv029554 X-loop: libvir-list@redhat.com 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: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZM-MESSAGEID: 1641591521375100003 Content-Type: text/plain; charset="utf-8" Signed-off-by: Jim Fehlig --- docs/manpages/index.rst | 1 + docs/manpages/libvirt-guests.rst | 146 +++++++++++++++++++++++++++++++ docs/manpages/meson.build | 1 + tools/libvirt-guests.service.in | 2 +- 4 files changed, 149 insertions(+), 1 deletion(-) diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index fb4a36d46a..b2717bc9f2 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -41,6 +41,7 @@ Tools * `virt-admin(1) `__ - daemon administration interface * `virsh(1) `__ - management user interface * `virt-qemu-run(1) `__ - run standalone QEMU instances +* `libvirt-guests(8) `__ - Suspend/Resume running lib= virt guests =20 Key codes =3D=3D=3D=3D=3D=3D=3D=3D=3D diff --git a/docs/manpages/libvirt-guests.rst b/docs/manpages/libvirt-guest= s.rst new file mode 100644 index 0000000000..9dc7ed3473 --- /dev/null +++ b/docs/manpages/libvirt-guests.rst @@ -0,0 +1,146 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +libvirt-guests +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +------------------------------------- +suspend/resume running libvirt guests +------------------------------------- + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``libvirt-guests`` *COMMAND* + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``libvirt-guests`` is a service that can be used to coordinate guest and h= ost +lifecyle actions. By default, ``libvirt-guests`` will suspend running gues= ts +when the host shuts down, and restore them to their pre-shutdown state when +the host reboots. + +``libvirt-guests`` is typically under control of systemd. When +``libvirt-guests.service`` is enabled, systemd will call ``libvirt-guests`` +with the ``start`` *command* when the host boots. Conversely, systemd will= call +``libvirt-guests`` with the ``stop`` *command* when the host shuts down. + +``libvirt-guests`` can be used directly. In addition to the ``start`` and +``stop`` *commands*, it also supports ``status``, ``restart``, ``condresta= rt``, +``try-restart``, ``reload``, ``force-reload``, ``gueststatus``, and +``shutdown`` *commands*. + + +ENVIRONMENT +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The following environment variables can be used to alter the behavior of +``libvirt-guests`` + +- URIS=3Ddefault + + URIs to check for running guests + +- ON_BOOT=3Dstart + + Action taken on host boot + + * start + + All guests which were running on shutdown are started on boot regardle= ss + of their autostart settings + + * ignore + + ``libvirt-guests`` won't start any guest on boot, however, guests mark= ed + as autostart will still be automatically started by libvirtd + +- START_DELAY=3D0 + + Number of seconds to wait between each guest start. Set to 0 to allow pa= rallel + startup. + +- ON_SHUTDOWN=3Dsuspend + + Action taken on host shutdown + + * suspend + + All running guests are suspended using virsh managedsave + + * shutdown + + All running guests are asked to shutdown. Please be careful with this + settings since there is no way to distinguish between a guest which is + stuck or ignores shutdown requests and a guest which just needs a long + time to shutdown. When setting ON_SHUTDOWN=3Dshutdown, you must also s= et + SHUTDOWN_TIMEOUT to a value suitable for your guests. + +- PARALLEL_SHUTDOWN=3D0 + + Number of guests will be shutdown concurrently, taking effect when + "ON_SHUTDOWN" is set to "shutdown". If Set to 0, guests will be shutdown= one + after another. Number of guests on shutdown at any time will not exceed = number + set in this variable. + +- SHUTDOWN_TIMEOUT=3D300 + + Number of seconds we're willing to wait for a guest to shut down. If par= allel + shutdown is enabled, this timeout applies as a timeout for shutting down= all + guests on a single URI defined in the variable URIS. If this is 0, then = there + is no time out (use with caution, as guests might not respond to a shutd= own + request). The default value is 300 seconds (5 minutes). + +- BYPASS_CACHE=3D0 + + If non-zero, try to bypass the file system cache when saving and + restoring guests, even though this may give slower operation for + some file systems. + + - SYNC_TIME=3D1 + + If non-zero, try to sync guest time on domain resume. Be aware, that + this requires guest agent with support for time synchronization + running in the guest. By default, this functionality is turned off. + + +BUGS +=3D=3D=3D=3D + +Please report all bugs you discover. This should be done via either: + +#. the mailing list + + `https://libvirt.org/contact.html `_ + +#. the bug tracker + + `https://libvirt.org/bugs.html `_ + +Alternatively, you may report bugs to your software distributor / vendor. + + +AUTHORS +=3D=3D=3D=3D=3D=3D=3D + +Please refer to the AUTHORS file distributed with libvirt. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``libvirt-guests`` is distributed under the terms of the GNU LGPL v2.1+. +This is free software; see the source for copying conditions. There +is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE + + +SEE ALSO +=3D=3D=3D=3D=3D=3D=3D=3D + +libvirtd(8), `https://libvirt.org/ `_ diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index 6763d19af8..2c84011aa7 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -39,6 +39,7 @@ docs_man_files =3D [ { 'name': 'virtvboxd', 'section': '8', 'install': conf.has('WITH_VBOX') = }, { 'name': 'virtvzd', 'section': '8', 'install': conf.has('WITH_VZ') }, { 'name': 'virtxend', 'section': '8', 'install': conf.has('WITH_LIBXL') = }, + { 'name': 'libvirt-guests', 'section': '8', 'install': true }, ] =20 foreach name : keycode_list diff --git a/tools/libvirt-guests.service.in b/tools/libvirt-guests.service= .in index 10c664016a..1a9b233e11 100644 --- a/tools/libvirt-guests.service.in +++ b/tools/libvirt-guests.service.in @@ -6,7 +6,7 @@ After=3Dnetwork.target After=3Dtime-sync.target After=3Dlibvirtd.service After=3Dvirt-guest-shutdown.target -Documentation=3Dman:libvirtd(8) +Documentation=3Dman:libvirt-guests(8) Documentation=3Dhttps://libvirt.org =20 [Service] --=20 2.34.1