From nobody Mon Feb 9 19:05:41 2026 Delivered-To: importer@patchew.org Received-SPF: none (zohomail.com: 8.43.85.245 is neither permitted nor denied by domain of lists.libvirt.org) client-ip=8.43.85.245; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; spf=none (zohomail.com: 8.43.85.245 is neither permitted nor denied by domain of lists.libvirt.org) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 1708423061447740.9275870952822; Tue, 20 Feb 2024 01:57:41 -0800 (PST) Received: by lists.libvirt.org (Postfix, from userid 996) id 6930A1E25; Tue, 20 Feb 2024 04:57:40 -0500 (EST) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id A83D21A84; Tue, 20 Feb 2024 04:43:00 -0500 (EST) Received: by lists.libvirt.org (Postfix, from userid 996) id E2C46176C; Tue, 20 Feb 2024 04:41:45 -0500 (EST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id BA56318D1 for ; Tue, 20 Feb 2024 04:41:42 -0500 (EST) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-20-Apk9Zfr2P3Snh1hpnUh9GA-1; Tue, 20 Feb 2024 04:41:40 -0500 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id B547B869EC3 for ; Tue, 20 Feb 2024 09:41:40 +0000 (UTC) Received: from harajuku.usersys.redhat.com.homenet.telecomitalia.it (unknown [10.45.224.52]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2B1CA1074A for ; Tue, 20 Feb 2024 09:41:40 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=5.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL,SPF_HELO_NONE,T_SCC_BODY_TEXT_LINE autolearn=unavailable autolearn_force=no version=3.4.4 X-MC-Unique: Apk9Zfr2P3Snh1hpnUh9GA-1 From: Andrea Bolognani To: devel@lists.libvirt.org Subject: [PATCH 4/9] docs: Don't use "line blocks" Date: Tue, 20 Feb 2024 10:41:30 +0100 Message-ID: <20240220094135.359112-5-abologna@redhat.com> In-Reply-To: <20240220094135.359112-1-abologna@redhat.com> References: <20240220094135.359112-1-abologna@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.5 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Message-ID-Hash: OBLSJRMU6A6I6OFLES22LE67GSCC7IIS X-Message-ID-Hash: OBLSJRMU6A6I6OFLES22LE67GSCC7IIS X-MailFrom: abologna@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-config-2; header-match-config-3; header-match-devel.lists.libvirt.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header X-Mailman-Version: 3.2.2 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: Content-Type: text/plain; charset="utf-8"; x-default="true" Content-Transfer-Encoding: quoted-printable X-ZM-MESSAGEID: 1708423062770100001 It's unclear why the conversion process decided to insert them, but they don't seem to do much. Signed-off-by: Andrea Bolognani --- docs/bugs.rst | 14 ++-- docs/firewall.rst | 23 ++++--- docs/formatdomain.rst | 17 ++--- docs/hooks.rst | 146 +++++++++++++++++++++--------------------- 4 files changed, 102 insertions(+), 98 deletions(-) diff --git a/docs/bugs.rst b/docs/bugs.rst index b5d2e42b0c..5fd1970caf 100644 --- a/docs/bugs.rst +++ b/docs/bugs.rst @@ -99,13 +99,13 @@ that for the data to be really useful libvirt debug inf= ormation must be present for example by installing libvirt debuginfo package on Fedora or Red Hat Enterprise Linux (with debuginfo-install libvirt) prior to running gdb. =20 -| It may also happen that the libvirt daemon itself crashes or gets stuck,= in - the first case run it (as root) under gdb, and reproduce the sequence le= ading - to the crash, similarly to a normal program provide the "bt" backtrace - information to where gdb will have stopped. -| But if libvirtd gets stuck, for example seems to stop processing command= s, try - to attach to the faulty daemon and issue a gdb command "thread apply all= bt" - to show all the threads backtraces, as in: +It may also happen that the libvirt daemon itself crashes or gets stuck, in +the first case run it (as root) under gdb, and reproduce the sequence lead= ing +to the crash, similarly to a normal program provide the "bt" backtrace +information to where gdb will have stopped. +But if libvirtd gets stuck, for example seems to stop processing commands,= try +to attach to the faulty daemon and issue a gdb command "thread apply all b= t" +to show all the threads backtraces, as in: =20 :: =20 diff --git a/docs/firewall.rst b/docs/firewall.rst index eff9de5a89..26474d3317 100644 --- a/docs/firewall.rst +++ b/docs/firewall.rst @@ -77,8 +77,9 @@ LAN/WAN. The next rules depend on the type of connectivity allowed, and go in the m= ain FORWARD chain: =20 -- | type=3Disolated - | Allow traffic between guests. Deny inbound. Deny outbound. +- type=3Disolated + + Allow traffic between guests. Deny inbound. Deny outbound. =20 :: =20 @@ -87,10 +88,11 @@ FORWARD chain: REJECT all -- * virbr1 0.0.0.0/0 0.0.0.0/0 = reject-with icmp-port-unreachable REJECT all -- virbr1 * 0.0.0.0/0 0.0.0.0/0 = reject-with icmp-port-unreachable =20 -- | type=3Dnat - | Allow inbound related to an established connection. Allow outbound, b= ut - only from our expected subnet. Allow traffic between guests. Deny all= other - inbound. Deny all other outbound. +- type=3Dnat + + Allow inbound related to an established connection. Allow outbound, but + only from our expected subnet. Allow traffic between guests. Deny all o= ther + inbound. Deny all other outbound. =20 :: =20 @@ -101,10 +103,11 @@ FORWARD chain: REJECT all -- * virbr0 0.0.0.0/0 0.0.0.0/0 = reject-with icmp-port-unreachable REJECT all -- virbr0 * 0.0.0.0/0 0.0.0.0/0 = reject-with icmp-port-unreachable =20 -- | type=3Drouted - | Allow inbound, but only to our expected subnet. Allow outbound, but o= nly - from our expected subnet. Allow traffic between guests. Deny all other - inbound. Deny all other outbound. +- type=3Drouted + + Allow inbound, but only to our expected subnet. Allow outbound, but only + from our expected subnet. Allow traffic between guests. Deny all other + inbound. Deny all other outbound. =20 :: =20 diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index fa42883809..f56f40d5cc 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5118,14 +5118,15 @@ integration is required. Direct attachment to physical interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =20 -| Provides direct attachment of the virtual machine's NIC to the given phy= sical - interface of the host. :since:`Since 0.7.7 (QEMU and KVM only)` -| This setup requires the Linux macvtap driver to be available. :since:`(S= ince - Linux 2.6.34.)` One of the modes 'vepa' ( `'Virtual Ethernet Port - Aggregator' `__), - 'bridge' or 'private' can be chosen for the operation mode of the macvtap - device, 'vepa' being the default mode. The individual modes cause the de= livery - of packets to behave as follows: +Provides direct attachment of the virtual machine's NIC to the given physi= cal +interface of the host. :since:`Since 0.7.7 (QEMU and KVM only)` + +This setup requires the Linux macvtap driver to be available. :since:`(Sin= ce +Linux 2.6.34.)` One of the modes 'vepa' ( `'Virtual Ethernet Port +Aggregator' `__), +'bridge' or 'private' can be chosen for the operation mode of the macvtap +device, 'vepa' being the default mode. The individual modes cause the deli= very +of packets to behave as follows: =20 If the model type is set to ``virtio`` and interface's ``trustGuestRxFilte= rs`` attribute is set to ``yes``, changes made to the interface mac address, diff --git a/docs/hooks.rst b/docs/hooks.rst index bd197c0d6e..4a0454a454 100644 --- a/docs/hooks.rst +++ b/docs/hooks.rst @@ -151,20 +151,20 @@ This translates to the following specifics for each h= ook script: /etc/libvirt/hooks/daemon ^^^^^^^^^^^^^^^^^^^^^^^^^ =20 -- | When the libvirt daemon is started, this script is called as: +- When the libvirt daemon is started, this script is called as: =20 :: =20 /etc/libvirt/hooks/daemon - start - start =20 -- | When the libvirt daemon is shut down, this script is called as: +- When the libvirt daemon is shut down, this script is called as: =20 :: =20 /etc/libvirt/hooks/daemon - shutdown - shutdown =20 -- | When the libvirt daemon receives the SIGHUP signal, it reloads its - configuration and triggers the hook script as: +- When the libvirt daemon receives the SIGHUP signal, it reloads its + configuration and triggers the hook script as: =20 :: =20 @@ -177,41 +177,41 @@ operation. There is no specific operation to indicate= a "restart" is occurring. /etc/libvirt/hooks/qemu ^^^^^^^^^^^^^^^^^^^^^^^ =20 -- | Before a QEMU guest is started, the qemu hook script is called in thr= ee - locations; if any location fails, the guest is not started. The first - location, :since:`since 0.9.0` , is before libvirt performs any resou= rce - labeling, and the hook can allocate resources not managed by libvirt = such - as DRBD or missing bridges. This is called as: +- Before a QEMU guest is started, the qemu hook script is called in three + locations; if any location fails, the guest is not started. The first + location, :since:`since 0.9.0` , is before libvirt performs any resource + labeling, and the hook can allocate resources not managed by libvirt su= ch + as DRBD or missing bridges. This is called as: =20 :: =20 /etc/libvirt/hooks/qemu guest_name prepare begin - =20 - | The second location, available :since:`Since 0.8.0` , occurs after li= bvirt - has finished labeling all resources, but has not yet started the gues= t, - called as: + The second location, available :since:`Since 0.8.0` , occurs after libv= irt + has finished labeling all resources, but has not yet started the guest, + called as: =20 :: =20 /etc/libvirt/hooks/qemu guest_name start begin - =20 - | The third location, :since:`0.9.13` , occurs after the QEMU process h= as - successfully started up: + The third location, :since:`0.9.13` , occurs after the QEMU process has + successfully started up: =20 :: =20 /etc/libvirt/hooks/qemu guest_name started begin - =20 -- | When a QEMU guest is stopped, the qemu hook script is called in two - locations, to match the startup. First, :since:`since 0.8.0` , the ho= ok is - called before libvirt restores any labels: +- When a QEMU guest is stopped, the qemu hook script is called in two + locations, to match the startup. First, :since:`since 0.8.0` , the hook= is + called before libvirt restores any labels: =20 :: =20 /etc/libvirt/hooks/qemu guest_name stopped end - =20 - | Then, after libvirt has released all resources, the hook is called ag= ain, - :since:`since 0.9.0` , to allow any additional resource cleanup: + Then, after libvirt has released all resources, the hook is called agai= n, + :since:`since 0.9.0` , to allow any additional resource cleanup: =20 :: =20 @@ -274,41 +274,41 @@ operation. There is no specific operation to indicate= a "restart" is occurring. /etc/libvirt/hooks/lxc ^^^^^^^^^^^^^^^^^^^^^^ =20 -- | Before a LXC guest is started, the lxc hook script is called in three - locations; if any location fails, the guest is not started. The first - location, :since:`since 0.9.13` , is before libvirt performs any reso= urce - labeling, and the hook can allocate resources not managed by libvirt = such - as DRBD or missing bridges. This is called as: +- Before a LXC guest is started, the lxc hook script is called in three + locations; if any location fails, the guest is not started. The first + location, :since:`since 0.9.13` , is before libvirt performs any resour= ce + labeling, and the hook can allocate resources not managed by libvirt su= ch + as DRBD or missing bridges. This is called as: =20 :: =20 /etc/libvirt/hooks/lxc guest_name prepare begin - =20 - | The second location, available :since:`Since 0.8.0` , occurs after li= bvirt - has finished labeling all resources, but has not yet started the gues= t, - called as: + The second location, available :since:`Since 0.8.0` , occurs after libv= irt + has finished labeling all resources, but has not yet started the guest, + called as: =20 :: =20 /etc/libvirt/hooks/lxc guest_name start begin - =20 - | The third location, :since:`0.9.13` , occurs after the LXC process has - successfully started up: + The third location, :since:`0.9.13` , occurs after the LXC process has + successfully started up: =20 :: =20 /etc/libvirt/hooks/lxc guest_name started begin - =20 -- | When a LXC guest is stopped, the lxc hook script is called in two - locations, to match the startup. First, :since:`since 0.8.0` , the ho= ok is - called before libvirt restores any labels: +- When a LXC guest is stopped, the lxc hook script is called in two + locations, to match the startup. First, :since:`since 0.8.0` , the hook= is + called before libvirt restores any labels: =20 :: =20 /etc/libvirt/hooks/lxc guest_name stopped end - =20 - | Then, after libvirt has released all resources, the hook is called ag= ain, - :since:`since 0.9.0` , to allow any additional resource cleanup: + Then, after libvirt has released all resources, the hook is called agai= n, + :since:`since 0.9.0` , to allow any additional resource cleanup: =20 :: =20 @@ -325,41 +325,41 @@ operation. There is no specific operation to indicate= a "restart" is occurring. /etc/libvirt/hooks/libxl ^^^^^^^^^^^^^^^^^^^^^^^^ =20 -- | Before a Xen guest is started using libxl driver, the libxl hook scri= pt is - called in three locations; if any location fails, the guest is not st= arted. - The first location, :since:`since 2.1.0` , is before libvirt performs= any - resource labeling, and the hook can allocate resources not managed by - libvirt. This is called as: +- Before a Xen guest is started using libxl driver, the libxl hook script= is + called in three locations; if any location fails, the guest is not star= ted. + The first location, :since:`since 2.1.0` , is before libvirt performs a= ny + resource labeling, and the hook can allocate resources not managed by + libvirt. This is called as: =20 :: =20 /etc/libvirt/hooks/libxl guest_name prepare begin - =20 - | The second location, available :since:`Since 2.1.0` , occurs after li= bvirt - has finished labeling all resources, but has not yet started the gues= t, - called as: + The second location, available :since:`Since 2.1.0` , occurs after libv= irt + has finished labeling all resources, but has not yet started the guest, + called as: =20 :: =20 /etc/libvirt/hooks/libxl guest_name start begin - =20 - | The third location, :since:`2.1.0` , occurs after the domain has - successfully started up: + The third location, :since:`2.1.0` , occurs after the domain has + successfully started up: =20 :: =20 /etc/libvirt/hooks/libxl guest_name started begin - =20 -- | When a libxl-handled Xen guest is stopped, the libxl hook script is c= alled - in two locations, to match the startup. First, :since:`since 2.1.0` ,= the - hook is called before libvirt restores any labels: +- When a libxl-handled Xen guest is stopped, the libxl hook script is cal= led + in two locations, to match the startup. First, :since:`since 2.1.0` , t= he + hook is called before libvirt restores any labels: =20 :: =20 /etc/libvirt/hooks/libxl guest_name stopped end - =20 - | Then, after libvirt has released all resources, the hook is called ag= ain, - :since:`since 2.1.0` , to allow any additional resource cleanup: + Then, after libvirt has released all resources, the hook is called agai= n, + :since:`since 2.1.0` , to allow any additional resource cleanup: =20 :: =20 @@ -399,41 +399,41 @@ operation. There is no specific operation to indicate= a "restart" is occurring. /etc/libvirt/hooks/bhyve ^^^^^^^^^^^^^^^^^^^^^^^^ =20 -- | Before an bhyve guest is started, the bhyve hook script is called in = three - locations; if any location fails, the guest is not started. The first - location, :since:`since 6.1.0` , is before libvirt performs any resou= rce - labeling, and the hook can allocate resources not managed by libvirt.= This is - called as: +- Before an bhyve guest is started, the bhyve hook script is called in th= ree + locations; if any location fails, the guest is not started. The first + location, :since:`since 6.1.0` , is before libvirt performs any resource + labeling, and the hook can allocate resources not managed by libvirt. T= his is + called as: =20 :: =20 /etc/libvirt/hooks/bhyve guest_name prepare begin - =20 - | The second location, available :since:`Since 6.1.0` , occurs after li= bvirt - has finished labeling all resources, but has not yet started the gues= t, - called as: + The second location, available :since:`Since 6.1.0` , occurs after libv= irt + has finished labeling all resources, but has not yet started the guest, + called as: =20 :: =20 /etc/libvirt/hooks/bhyve guest_name start begin - =20 - | The third location, :since:`6.1.0` , occurs after the bhyve process h= as - successfully started up: + The third location, :since:`6.1.0` , occurs after the bhyve process has + successfully started up: =20 :: =20 /etc/libvirt/hooks/bhyve guest_name started begin - =20 -- | When an bhyve guest is stopped, the bhyve hook script is called in two - locations, to match the startup. First, :since:`since 6.1.0` , the ho= ok is - called before libvirt restores any labels: +- When an bhyve guest is stopped, the bhyve hook script is called in two + locations, to match the startup. First, :since:`since 6.1.0` , the hook= is + called before libvirt restores any labels: =20 :: =20 /etc/libvirt/hooks/bhyve guest_name stopped end - =20 - | Then, after libvirt has released all resources, the hook is called ag= ain, - :since:`since 6.1.0` , to allow any additional resource cleanup: + Then, after libvirt has released all resources, the hook is called agai= n, + :since:`since 6.1.0` , to allow any additional resource cleanup: =20 :: =20 @@ -442,27 +442,27 @@ operation. There is no specific operation to indicate= a "restart" is occurring. /etc/libvirt/hooks/network ^^^^^^^^^^^^^^^^^^^^^^^^^^ =20 -- | :since:`Since 1.2.2` , before a network is started, this script is ca= lled - as: +- :since:`Since 1.2.2` , before a network is started, this script is call= ed + as: =20 :: =20 /etc/libvirt/hooks/network network_name start begin - =20 -- | After the network is started, up & running, the script is called as: +- After the network is started, up & running, the script is called as: =20 :: =20 /etc/libvirt/hooks/network network_name started begin - =20 -- | When a network is shut down, this script is called as: +- When a network is shut down, this script is called as: =20 :: =20 /etc/libvirt/hooks/network network_name stopped end - =20 -- | Later, when network is started and there's an interface from a domain= to be - plugged into the network, the hook script is called as: +- Later, when network is started and there's an interface from a domain t= o be + plugged into the network, the hook script is called as: =20 :: =20 @@ -471,14 +471,14 @@ operation. There is no specific operation to indicate= a "restart" is occurring. Please note, that in this case, the script is passed both network and p= ort XMLs on its stdin. =20 -- | When network is updated, the hook script is called as: +- When network is updated, the hook script is called as: =20 :: =20 /etc/libvirt/hooks/network network_name updated begin - =20 -- | When the domain from previous case is shutting down, the interface is - unplugged. This leads to another script invocation: +- When the domain from previous case is shutting down, the interface is + unplugged. This leads to another script invocation: =20 :: =20 --=20 2.43.2 _______________________________________________ Devel mailing list -- devel@lists.libvirt.org To unsubscribe send an email to devel-leave@lists.libvirt.org