From nobody Sat May 18 20:15:22 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=philmd@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=philmd@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1637263679; cv=none; d=zohomail.com; s=zohoarc; b=S3k2XwHZNCuUzMUpT934XPhaLNYdGtzHszUK5tIOjHj43E6vCBFzyPW83wLxxlY0q0i+P7s20YO+rPCoOA6+1u74I6KJIxMfLY/Fp0E9fn87gyh+AU2tV4rhJJJ8nhbucFkh79t0YN4v6+7ZSUNUmzbpvmOEhKj/EfbVIGxYlao= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1637263679; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:MIME-Version:Message-ID:Subject:To; bh=onQzSf5POREpUX9e4aWGOLccXTbzTIctz5gjtxaTXRY=; b=kIs/dRwHNb6ySl7fN49LaVf2iXoUldiIf30qZoRk38gRPEuCJUH2gXW7gj62dr9JYZPTRs+ZxGkr151wxtiEzw/oWqqawgU1TQEbQK0vyi/0eg69D4E4f04qn/nSP56Wof3wSAbIo1I+VqLomPvS5x6beOUVGw/Pa8xW2XpVfv0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=philmd@redhat.com; dmarc=pass header.from= (p=none dis=none) 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 1637263678978123.17086556492916; Thu, 18 Nov 2021 11:27:58 -0800 (PST) Received: from mail-wm1-f69.google.com (mail-wm1-f69.google.com [209.85.128.69]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-342--KGP2Mu9O3u1G6FzL1JTew-1; Thu, 18 Nov 2021 14:27:48 -0500 Received: by mail-wm1-f69.google.com with SMTP id z126-20020a1c7e84000000b003335e5dc26bso3013093wmc.8 for ; Thu, 18 Nov 2021 11:27:48 -0800 (PST) Return-Path: Return-Path: Received: from x1w.. (62.red-83-57-168.dynamicip.rima-tde.net. [83.57.168.62]) by smtp.gmail.com with ESMTPSA id az4sm10019966wmb.20.2021.11.18.11.27.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 18 Nov 2021 11:27:46 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1637263677; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=onQzSf5POREpUX9e4aWGOLccXTbzTIctz5gjtxaTXRY=; b=YRgsqiqLNJwREP/I1elSnqRZ7W+lyzwSihKCNbEub0qoCXsN24FPeBMc8v/XqOC1Sry1JX IvYw0pNE54gKLlQy2MA+5ncQWmtKky7g/MTMcPgJgg2zkUh6xm1T+oBbsGQVawFGn3ENH7 8G9ygn1PpP+A+furgWbDRPB4yaHMOZ8= X-MC-Unique: -KGP2Mu9O3u1G6FzL1JTew-1 X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=onQzSf5POREpUX9e4aWGOLccXTbzTIctz5gjtxaTXRY=; b=qAHsG1c3l4hZb/q4D27gjOEq+TeYV4MJj5Drk82YnYolDO7qFxMkOaFGtBqCTL4fmn z0iErZzOYNwrG6NJ7vVpVOhURd4fSJtDxdDHlYiIwRJ+njT9DSL7c6Yf8ZQunA42VclN aAwFRluP9YCXhOhI/+aWcOtzKOBReMEiIaaDZthzmfKW5pTYKYh2BOIDPEFOFcHhaAD/ KZoOWU0VPSUxWJy24Si3k4N94hg3CI0QnkgmEBAli68uyvTWTceqGU7qDyRHlN1bb6+h wKbBBwwfmdQVaCqXwteFWKhs+0wUbQIr6+/yGjH0RmJzjoNCkPPLIG8vk1FA0g9redN7 lNBw== X-Gm-Message-State: AOAM530TbHE5R+otA2pIRAa0QzoNFiAtpKvpxrENuYgISkvjXgxez6vj bDwd8C91XQ1q7cKztxE6PdC8LklctB9h8wa4+7RxLgNrcR8wztCo5G/dfkTqdbu6cJbAn8Hj6AC 8i27buvJxXTgzcg== X-Received: by 2002:a05:600c:378b:: with SMTP id o11mr12912040wmr.157.1637263666746; Thu, 18 Nov 2021 11:27:46 -0800 (PST) X-Google-Smtp-Source: ABdhPJwsc0virqKg5xKRs0HmiLac2buNTNghh22UVjfYIYamWWHMqcGf1Kt4+r4TkdP4S1EUUdQDww== X-Received: by 2002:a05:600c:378b:: with SMTP id o11mr12912007wmr.157.1637263666458; Thu, 18 Nov 2021 11:27:46 -0800 (PST) From: =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= To: qemu-devel@nongnu.org Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Niek Linnenbank , "Dr. David Alan Gilbert" , Stefan Hajnoczi , John G Johnson , Kevin Wolf , qemu-block@nongnu.org, Eric Blake , Vladimir Sementsov-Ogievskiy , Elena Ufimtseva , Hanna Reitz , Jagannathan Raman , qemu-arm@nongnu.org, virtio-fs@redhat.com, =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Darren Kenny Subject: [PATCH-for-6.2? v2] docs: Render binary names as monospaced text Date: Thu, 18 Nov 2021 20:27:44 +0100 Message-Id: <20211118192744.64325-1-philmd@redhat.com> X-Mailer: git-send-email 2.31.1 MIME-Version: 1.0 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=philmd@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1637263679396100001 Reviewed-by: Darren Kenny Signed-off-by: Philippe Mathieu-Daud=C3=A9 --- v2: Addressed Eric comments --- docs/about/removed-features.rst | 8 ++++---- docs/devel/build-system.rst | 6 +++--- docs/devel/multi-process.rst | 6 +++--- docs/devel/testing.rst | 8 ++++---- docs/image-fuzzer.txt | 6 +++--- docs/system/arm/orangepi.rst | 2 +- docs/system/images.rst | 2 +- docs/system/qemu-block-drivers.rst.inc | 6 +++--- docs/system/tls.rst | 2 +- docs/tools/qemu-img.rst | 18 +++++++++--------- docs/tools/qemu-nbd.rst | 4 ++-- docs/tools/qemu-storage-daemon.rst | 7 ++++--- docs/tools/virtiofsd.rst | 4 ++-- 13 files changed, 40 insertions(+), 39 deletions(-) diff --git a/docs/about/removed-features.rst b/docs/about/removed-features.= rst index 9d0d90c90d9..d42c3341dee 100644 --- a/docs/about/removed-features.rst +++ b/docs/about/removed-features.rst @@ -658,8 +658,8 @@ enforce that any failure to open the backing image (inc= luding if the backing file is missing or an incorrect format was specified) is an error when ``-u`` is not used. =20 -qemu-img amend to adjust backing file (removed in 6.1) -'''''''''''''''''''''''''''''''''''''''''''''''''''''' +``qemu-img amend`` to adjust backing file (removed in 6.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' =20 The use of ``qemu-img amend`` to modify the name or format of a qcow2 backing image was never fully documented or tested, and interferes @@ -670,8 +670,8 @@ backing chain should be performed with ``qemu-img rebas= e -u`` either before or after the remaining changes being performed by amend, as appropriate. =20 -qemu-img backing file without format (removed in 6.1) -''''''''''''''''''''''''''''''''''''''''''''''''''''' +``qemu-img`` backing file without format (removed in 6.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''' =20 The use of ``qemu-img create``, ``qemu-img rebase``, or ``qemu-img convert`` to create or modify an image that depends on a backing file diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst index 7a83f5fc0db..431caba7aa0 100644 --- a/docs/devel/build-system.rst +++ b/docs/devel/build-system.rst @@ -121,11 +121,11 @@ process for: =20 1) executables, which include: =20 - - Tools - qemu-img, qemu-nbd, qga (guest agent), etc + - Tools - ``qemu-img``, ``qemu-nbd``, ``qga`` (guest agent), etc =20 - - System emulators - qemu-system-$ARCH + - System emulators - ``qemu-system-$ARCH`` =20 - - Userspace emulators - qemu-$ARCH + - Userspace emulators - ``qemu-$ARCH`` =20 - Unit tests =20 diff --git a/docs/devel/multi-process.rst b/docs/devel/multi-process.rst index e5758a79aba..2c5ec977df8 100644 --- a/docs/devel/multi-process.rst +++ b/docs/devel/multi-process.rst @@ -187,9 +187,9 @@ desired, in which the emulation application should only= be allowed to access the files or devices the VM it's running on behalf of can access. #### qemu-io model =20 -Qemu-io is a test harness used to test changes to the QEMU block backend -object code. (e.g., the code that implements disk images for disk driver -emulation) Qemu-io is not a device emulation application per se, but it +``qemu-io`` is a test harness used to test changes to the QEMU block backe= nd +object code (e.g., the code that implements disk images for disk driver +emulation). ``qemu-io`` is not a device emulation application per se, but = it does compile the QEMU block objects into a separate binary from the main QEMU one. This could be useful for disk device emulation, since its emulation applications will need to include the QEMU block objects. diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index 60c59023e58..755343c7dd0 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -564,11 +564,11 @@ exploiting a QEMU security bug to compromise the host. QEMU binaries ~~~~~~~~~~~~~ =20 -By default, qemu-system-x86_64 is searched in $PATH to run the guest. If t= here -isn't one, or if it is older than 2.10, the test won't work. In this case, +By default, ``qemu-system-x86_64`` is searched in $PATH to run the guest. = If +there isn't one, or if it is older than 2.10, the test won't work. In this= case, provide the QEMU binary in env var: ``QEMU=3D/path/to/qemu-2.10+``. =20 -Likewise the path to qemu-img can be set in QEMU_IMG environment variable. +Likewise the path to ``qemu-img`` can be set in QEMU_IMG environment varia= ble. =20 Make jobs ~~~~~~~~~ @@ -650,7 +650,7 @@ supported. To start the fuzzer, run =20 tests/image-fuzzer/runner.py -c '[["qemu-img", "info", "$test_img"]]' /t= mp/test qcow2 =20 -Alternatively, some command different from "qemu-img info" can be tested, = by +Alternatively, some command different from ``qemu-img info`` can be tested= , by changing the ``-c`` option. =20 Integration tests using the Avocado Framework diff --git a/docs/image-fuzzer.txt b/docs/image-fuzzer.txt index 3e23ebec331..279cc8c807f 100644 --- a/docs/image-fuzzer.txt +++ b/docs/image-fuzzer.txt @@ -51,10 +51,10 @@ assumes that core dumps will be generated in the curren= t working directory. For comprehensive test results, please, set up your test environment properly. =20 -Paths to binaries under test (SUTs) qemu-img and qemu-io are retrieved from -environment variables. If the environment check fails the runner will +Paths to binaries under test (SUTs) ``qemu-img`` and ``qemu-io`` are retri= eved +from environment variables. If the environment check fails the runner will use SUTs installed in system paths. -qemu-img is required for creation of backing files, so it's mandatory to s= et +``qemu-img`` is required for creation of backing files, so it's mandatory = to set the related environment variable if it's not installed in the system path. For details about environment variables see qemu-iotests/check. =20 diff --git a/docs/system/arm/orangepi.rst b/docs/system/arm/orangepi.rst index c55694dd91b..83c7445197b 100644 --- a/docs/system/arm/orangepi.rst +++ b/docs/system/arm/orangepi.rst @@ -128,7 +128,7 @@ Alternatively, you can also choose to build you own ima= ge with buildroot using the orangepi_pc_defconfig. Also see https://buildroot.org for more i= nformation. =20 When using an image as an SD card, it must be resized to a power of two. T= his can be -done with the qemu-img command. It is recommended to only increase the ima= ge size +done with the ``qemu-img`` command. It is recommended to only increase the= image size instead of shrinking it to a power of two, to avoid loss of data. For exam= ple, to prepare a downloaded Armbian image, first extract it and then increase its size to one gigabyte as follows: diff --git a/docs/system/images.rst b/docs/system/images.rst index 3d9144e6258..d000bd6b6f1 100644 --- a/docs/system/images.rst +++ b/docs/system/images.rst @@ -20,7 +20,7 @@ where myimage.img is the disk image filename and mysize i= s its size in kilobytes. You can add an ``M`` suffix to give the size in megabytes and a ``G`` suffix for gigabytes. =20 -See the qemu-img invocation documentation for more information. +See the ``qemu-img`` invocation documentation for more information. =20 .. _disk_005fimages_005fsnapshot_005fmode: =20 diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-bloc= k-drivers.rst.inc index 16225710ebb..e313784426d 100644 --- a/docs/system/qemu-block-drivers.rst.inc +++ b/docs/system/qemu-block-drivers.rst.inc @@ -511,13 +511,13 @@ of an inet socket: =20 |qemu_system| linux.img -hdb nbd+unix://?socket=3D/tmp/my_socket =20 -In this case, the block device must be exported using qemu-nbd: +In this case, the block device must be exported using ``qemu-nbd``: =20 .. parsed-literal:: =20 qemu-nbd --socket=3D/tmp/my_socket my_disk.qcow2 =20 -The use of qemu-nbd allows sharing of a disk between several guests: +The use of ``qemu-nbd`` allows sharing of a disk between several guests: =20 .. parsed-literal:: =20 @@ -530,7 +530,7 @@ and then you can use it with two guests: |qemu_system| linux1.img -hdb nbd+unix://?socket=3D/tmp/my_socket |qemu_system| linux2.img -hdb nbd+unix://?socket=3D/tmp/my_socket =20 -If the nbd-server uses named exports (supported since NBD 2.9.18, or with = QEMU's +If the ``nbd-server`` uses named exports (supported since NBD 2.9.18, or w= ith QEMU's own embedded NBD server), you must specify an export name in the URI: =20 .. parsed-literal:: diff --git a/docs/system/tls.rst b/docs/system/tls.rst index b0973afe1bf..1a04674362e 100644 --- a/docs/system/tls.rst +++ b/docs/system/tls.rst @@ -311,7 +311,7 @@ containing one or more usernames and random keys:: mkdir -m 0700 /tmp/keys psktool -u rich -p /tmp/keys/keys.psk =20 -TLS-enabled servers such as qemu-nbd can use this directory like so:: +TLS-enabled servers such as ``qemu-nbd`` can use this directory like so:: =20 qemu-nbd \ -t -x / \ diff --git a/docs/tools/qemu-img.rst b/docs/tools/qemu-img.rst index c0a44431467..d663dd92bd7 100644 --- a/docs/tools/qemu-img.rst +++ b/docs/tools/qemu-img.rst @@ -127,9 +127,9 @@ by the used format or see the format descriptions below= for details. .. option:: -S SIZE =20 Indicates the consecutive number of bytes that must contain only zeros - for qemu-img to create a sparse image during conversion. This value is r= ounded - down to the nearest 512 bytes. You may use the common size suffixes like - ``k`` for kilobytes. + for ``qemu-img`` to create a sparse image during conversion. This value = is + rounded down to the nearest 512 bytes. You may use the common size suffi= xes + like ``k`` for kilobytes. =20 .. option:: -t CACHE =20 @@ -431,7 +431,7 @@ Command description: suppressed from the destination image. =20 *SPARSE_SIZE* indicates the consecutive number of bytes (defaults to 4k) - that must contain only zeros for qemu-img to create a sparse image during + that must contain only zeros for ``qemu-img`` to create a sparse image d= uring conversion. If *SPARSE_SIZE* is 0, the source will not be scanned for unallocated or zero sectors, and the destination image will always be fully allocated. @@ -447,7 +447,7 @@ Command description: If the ``-n`` option is specified, the target volume creation will be skipped. This is useful for formats such as ``rbd`` if the target volume has already been created with site specific options that cannot - be supplied through qemu-img. + be supplied through ``qemu-img``. =20 Out of order writes can be enabled with ``-W`` to improve performance. This is only recommended for preallocated devices like host devices or o= ther @@ -472,7 +472,7 @@ Command description: If the option *BACKING_FILE* is specified, then the image will record only the differences from *BACKING_FILE*. No size needs to be specified = in this case. *BACKING_FILE* will never be modified unless you use the - ``commit`` monitor command (or qemu-img commit). + ``commit`` monitor command (or ``qemu-img commit``). =20 If a relative path name is given, the backing file is looked up relative= to the directory containing *FILENAME*. @@ -684,7 +684,7 @@ Command description: =20 Safe mode This is the default mode and performs a real rebase operation. The - new backing file may differ from the old one and qemu-img rebase + new backing file may differ from the old one and ``qemu-img rebase`` will take care of keeping the guest-visible content of *FILENAME* unchanged. =20 @@ -697,7 +697,7 @@ Command description: exists. =20 Unsafe mode - qemu-img uses the unsafe mode if ``-u`` is specified. In this + ``qemu-img`` uses the unsafe mode if ``-u`` is specified. In this mode, only the backing file name and format of *FILENAME* is changed without any checks on the file contents. The user must take care of specifying the correct new backing file, or the guest-visible @@ -735,7 +735,7 @@ Command description: sizes accordingly. Failure to do so will result in data loss! =20 When shrinking images, the ``--shrink`` option must be given. This infor= ms - qemu-img that the user acknowledges all loss of data beyond the truncated + ``qemu-img`` that the user acknowledges all loss of data beyond the trun= cated image's end. =20 After using this command to grow a disk image, you must use file system = and diff --git a/docs/tools/qemu-nbd.rst b/docs/tools/qemu-nbd.rst index 56e54cd4411..fdcee0244af 100644 --- a/docs/tools/qemu-nbd.rst +++ b/docs/tools/qemu-nbd.rst @@ -38,7 +38,7 @@ driver options if ``--image-opts`` is specified. supported. The common object types that it makes sense to define are the ``secret`` object, which is used to supply passwords and/or encryption keys, and the ``tls-creds`` object, which is used to supply TLS - credentials for the qemu-nbd server or client. + credentials for the ``qemu-nbd`` server or client. =20 .. option:: -p, --port=3DPORT =20 @@ -238,7 +238,7 @@ daemon: Expose the guest-visible contents of a qcow2 file via a block device /dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for partitions found within), then disconnect the device when done. -Access to bind qemu-nbd to an /dev/nbd device generally requires root +Access to bind ``qemu-nbd`` to a /dev/nbd device generally requires root privileges, and may also require the execution of ``modprobe nbd`` to enable the kernel NBD client module. *CAUTION*: Do not use this method to mount filesystems from an untrusted guest image - a diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-d= aemon.rst index b8ef4486f1e..3e5a9dc0320 100644 --- a/docs/tools/qemu-storage-daemon.rst +++ b/docs/tools/qemu-storage-daemon.rst @@ -10,9 +10,10 @@ Synopsis Description ----------- =20 -qemu-storage-daemon provides disk image functionality from QEMU, qemu-img,= and -qemu-nbd in a long-running process controlled via QMP commands without run= ning -a virtual machine. It can export disk images, run block job operations, and +``qemu-storage-daemon`` provides disk image functionality from QEMU, +``qemu-img``, and ``qemu-nbd`` in a long-running process controlled via QMP +commands without running a virtual machine. +It can export disk images, run block job operations, and perform other disk-related operations. The daemon is controlled via a QMP monitor and initial configuration from the command-line. =20 diff --git a/docs/tools/virtiofsd.rst b/docs/tools/virtiofsd.rst index cc314028309..07ac0be5511 100644 --- a/docs/tools/virtiofsd.rst +++ b/docs/tools/virtiofsd.rst @@ -136,8 +136,8 @@ Extended attribute (xattr) mapping By default the name of xattr's used by the client are passed through to th= e server file system. This can be a problem where either those xattr names are used by something on the server (e.g. selinux client/server confusion) or if the -virtiofsd is running in a container with restricted privileges where it ca= nnot -access some attributes. +``virtiofsd`` is running in a container with restricted privileges where it +cannot access some attributes. =20 Mapping syntax ~~~~~~~~~~~~~~ --=20 2.31.1