mirror of https://gitlab.com/qemu-project/qemu
docs: Render binary names as monospaced text
Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com> Message-Id: <20211118192744.64325-1-philmd@redhat.com> Reviewed-by: Darren Kenny <darren.kenny@oracle.com> Signed-off-by: Thomas Huth <thuth@redhat.com>
This commit is contained in:
parent
eff708a876
commit
c5ba621954
|
@ -658,8 +658,8 @@ enforce that any failure to open the backing image (including if the
|
||||||
backing file is missing or an incorrect format was specified) is an
|
backing file is missing or an incorrect format was specified) is an
|
||||||
error when ``-u`` is not used.
|
error when ``-u`` is not used.
|
||||||
|
|
||||||
qemu-img amend to adjust backing file (removed in 6.1)
|
``qemu-img amend`` to adjust backing file (removed in 6.1)
|
||||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||||
|
|
||||||
The use of ``qemu-img amend`` to modify the name or format of a qcow2
|
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
|
backing image was never fully documented or tested, and interferes
|
||||||
|
@ -670,8 +670,8 @@ backing chain should be performed with ``qemu-img rebase -u`` either
|
||||||
before or after the remaining changes being performed by amend, as
|
before or after the remaining changes being performed by amend, as
|
||||||
appropriate.
|
appropriate.
|
||||||
|
|
||||||
qemu-img backing file without format (removed in 6.1)
|
``qemu-img`` backing file without format (removed in 6.1)
|
||||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''
|
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||||
|
|
||||||
The use of ``qemu-img create``, ``qemu-img rebase``, or ``qemu-img
|
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
|
convert`` to create or modify an image that depends on a backing file
|
||||||
|
|
|
@ -121,11 +121,11 @@ process for:
|
||||||
|
|
||||||
1) executables, which include:
|
1) executables, which include:
|
||||||
|
|
||||||
- Tools - qemu-img, qemu-nbd, qga (guest agent), etc
|
- Tools - ``qemu-img``, ``qemu-nbd``, ``qga`` (guest agent), etc
|
||||||
|
|
||||||
- System emulators - qemu-system-$ARCH
|
- System emulators - ``qemu-system-$ARCH``
|
||||||
|
|
||||||
- Userspace emulators - qemu-$ARCH
|
- Userspace emulators - ``qemu-$ARCH``
|
||||||
|
|
||||||
- Unit tests
|
- Unit tests
|
||||||
|
|
||||||
|
|
|
@ -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.
|
access the files or devices the VM it's running on behalf of can access.
|
||||||
#### qemu-io model
|
#### qemu-io model
|
||||||
|
|
||||||
Qemu-io is a test harness used to test changes to the QEMU block backend
|
``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
|
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
|
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
|
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
|
QEMU one. This could be useful for disk device emulation, since its
|
||||||
emulation applications will need to include the QEMU block objects.
|
emulation applications will need to include the QEMU block objects.
|
||||||
|
|
|
@ -564,11 +564,11 @@ exploiting a QEMU security bug to compromise the host.
|
||||||
QEMU binaries
|
QEMU binaries
|
||||||
~~~~~~~~~~~~~
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
By default, qemu-system-x86_64 is searched in $PATH to run the guest. If there
|
By default, ``qemu-system-x86_64`` is searched in $PATH to run the guest. If
|
||||||
isn't one, or if it is older than 2.10, the test won't work. In this case,
|
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=/path/to/qemu-2.10+``.
|
provide the QEMU binary in env var: ``QEMU=/path/to/qemu-2.10+``.
|
||||||
|
|
||||||
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 variable.
|
||||||
|
|
||||||
Make jobs
|
Make jobs
|
||||||
~~~~~~~~~
|
~~~~~~~~~
|
||||||
|
@ -650,7 +650,7 @@ supported. To start the fuzzer, run
|
||||||
|
|
||||||
tests/image-fuzzer/runner.py -c '[["qemu-img", "info", "$test_img"]]' /tmp/test qcow2
|
tests/image-fuzzer/runner.py -c '[["qemu-img", "info", "$test_img"]]' /tmp/test qcow2
|
||||||
|
|
||||||
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.
|
changing the ``-c`` option.
|
||||||
|
|
||||||
Integration tests using the Avocado Framework
|
Integration tests using the Avocado Framework
|
||||||
|
|
|
@ -51,10 +51,10 @@ assumes that core dumps will be generated in the current working directory.
|
||||||
For comprehensive test results, please, set up your test environment
|
For comprehensive test results, please, set up your test environment
|
||||||
properly.
|
properly.
|
||||||
|
|
||||||
Paths to binaries under test (SUTs) qemu-img and qemu-io are retrieved from
|
Paths to binaries under test (SUTs) ``qemu-img`` and ``qemu-io`` are retrieved
|
||||||
environment variables. If the environment check fails the runner will
|
from environment variables. If the environment check fails the runner will
|
||||||
use SUTs installed in system paths.
|
use SUTs installed in system paths.
|
||||||
qemu-img is required for creation of backing files, so it's mandatory to set
|
``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.
|
the related environment variable if it's not installed in the system path.
|
||||||
For details about environment variables see qemu-iotests/check.
|
For details about environment variables see qemu-iotests/check.
|
||||||
|
|
||||||
|
|
|
@ -128,7 +128,7 @@ Alternatively, you can also choose to build you own image with buildroot
|
||||||
using the orangepi_pc_defconfig. Also see https://buildroot.org for more information.
|
using the orangepi_pc_defconfig. Also see https://buildroot.org for more information.
|
||||||
|
|
||||||
When using an image as an SD card, it must be resized to a power of two. This can be
|
When using an image as an SD card, it must be resized to a power of two. This can be
|
||||||
done with the qemu-img command. It is recommended to only increase the image 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 example,
|
instead of shrinking it to a power of two, to avoid loss of data. For example,
|
||||||
to prepare a downloaded Armbian image, first extract it and then increase
|
to prepare a downloaded Armbian image, first extract it and then increase
|
||||||
its size to one gigabyte as follows:
|
its size to one gigabyte as follows:
|
||||||
|
|
|
@ -20,7 +20,7 @@ where myimage.img is the disk image filename and mysize is its size in
|
||||||
kilobytes. You can add an ``M`` suffix to give the size in megabytes and
|
kilobytes. You can add an ``M`` suffix to give the size in megabytes and
|
||||||
a ``G`` suffix for gigabytes.
|
a ``G`` suffix for gigabytes.
|
||||||
|
|
||||||
See the qemu-img invocation documentation for more information.
|
See the ``qemu-img`` invocation documentation for more information.
|
||||||
|
|
||||||
.. _disk_005fimages_005fsnapshot_005fmode:
|
.. _disk_005fimages_005fsnapshot_005fmode:
|
||||||
|
|
||||||
|
|
|
@ -511,13 +511,13 @@ of an inet socket:
|
||||||
|
|
||||||
|qemu_system| linux.img -hdb nbd+unix://?socket=/tmp/my_socket
|
|qemu_system| linux.img -hdb nbd+unix://?socket=/tmp/my_socket
|
||||||
|
|
||||||
In this case, the block device must be exported using qemu-nbd:
|
In this case, the block device must be exported using ``qemu-nbd``:
|
||||||
|
|
||||||
.. parsed-literal::
|
.. parsed-literal::
|
||||||
|
|
||||||
qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
|
qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
|
||||||
|
|
||||||
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:
|
||||||
|
|
||||||
.. parsed-literal::
|
.. parsed-literal::
|
||||||
|
|
||||||
|
@ -530,7 +530,7 @@ and then you can use it with two guests:
|
||||||
|qemu_system| linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
|
|qemu_system| linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
|
||||||
|qemu_system| linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
|
|qemu_system| linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
|
||||||
|
|
||||||
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 with QEMU's
|
||||||
own embedded NBD server), you must specify an export name in the URI:
|
own embedded NBD server), you must specify an export name in the URI:
|
||||||
|
|
||||||
.. parsed-literal::
|
.. parsed-literal::
|
||||||
|
|
|
@ -311,7 +311,7 @@ containing one or more usernames and random keys::
|
||||||
mkdir -m 0700 /tmp/keys
|
mkdir -m 0700 /tmp/keys
|
||||||
psktool -u rich -p /tmp/keys/keys.psk
|
psktool -u rich -p /tmp/keys/keys.psk
|
||||||
|
|
||||||
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::
|
||||||
|
|
||||||
qemu-nbd \
|
qemu-nbd \
|
||||||
-t -x / \
|
-t -x / \
|
||||||
|
|
|
@ -127,9 +127,9 @@ by the used format or see the format descriptions below for details.
|
||||||
.. option:: -S SIZE
|
.. option:: -S SIZE
|
||||||
|
|
||||||
Indicates the consecutive number of bytes that must contain only zeros
|
Indicates the consecutive number of bytes that must contain only zeros
|
||||||
for qemu-img to create a sparse image during conversion. This value is rounded
|
for ``qemu-img`` to create a sparse image during conversion. This value is
|
||||||
down to the nearest 512 bytes. You may use the common size suffixes like
|
rounded down to the nearest 512 bytes. You may use the common size suffixes
|
||||||
``k`` for kilobytes.
|
like ``k`` for kilobytes.
|
||||||
|
|
||||||
.. option:: -t CACHE
|
.. option:: -t CACHE
|
||||||
|
|
||||||
|
@ -431,7 +431,7 @@ Command description:
|
||||||
suppressed from the destination image.
|
suppressed from the destination image.
|
||||||
|
|
||||||
*SPARSE_SIZE* indicates the consecutive number of bytes (defaults to 4k)
|
*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 during
|
||||||
conversion. If *SPARSE_SIZE* is 0, the source will not be scanned for
|
conversion. If *SPARSE_SIZE* is 0, the source will not be scanned for
|
||||||
unallocated or zero sectors, and the destination image will always be
|
unallocated or zero sectors, and the destination image will always be
|
||||||
fully allocated.
|
fully allocated.
|
||||||
|
@ -447,7 +447,7 @@ Command description:
|
||||||
If the ``-n`` option is specified, the target volume creation will be
|
If the ``-n`` option is specified, the target volume creation will be
|
||||||
skipped. This is useful for formats such as ``rbd`` if the target
|
skipped. This is useful for formats such as ``rbd`` if the target
|
||||||
volume has already been created with site specific options that cannot
|
volume has already been created with site specific options that cannot
|
||||||
be supplied through qemu-img.
|
be supplied through ``qemu-img``.
|
||||||
|
|
||||||
Out of order writes can be enabled with ``-W`` to improve performance.
|
Out of order writes can be enabled with ``-W`` to improve performance.
|
||||||
This is only recommended for preallocated devices like host devices or other
|
This is only recommended for preallocated devices like host devices or other
|
||||||
|
@ -472,7 +472,7 @@ Command description:
|
||||||
If the option *BACKING_FILE* is specified, then the image will record
|
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
|
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
|
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``).
|
||||||
|
|
||||||
If a relative path name is given, the backing file is looked up relative to
|
If a relative path name is given, the backing file is looked up relative to
|
||||||
the directory containing *FILENAME*.
|
the directory containing *FILENAME*.
|
||||||
|
@ -684,7 +684,7 @@ Command description:
|
||||||
|
|
||||||
Safe mode
|
Safe mode
|
||||||
This is the default mode and performs a real rebase operation. The
|
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*
|
will take care of keeping the guest-visible content of *FILENAME*
|
||||||
unchanged.
|
unchanged.
|
||||||
|
|
||||||
|
@ -697,7 +697,7 @@ Command description:
|
||||||
exists.
|
exists.
|
||||||
|
|
||||||
Unsafe mode
|
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
|
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
|
without any checks on the file contents. The user must take care of
|
||||||
specifying the correct new backing file, or the guest-visible
|
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!
|
sizes accordingly. Failure to do so will result in data loss!
|
||||||
|
|
||||||
When shrinking images, the ``--shrink`` option must be given. This informs
|
When shrinking images, the ``--shrink`` option must be given. This informs
|
||||||
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 truncated
|
||||||
image's end.
|
image's end.
|
||||||
|
|
||||||
After using this command to grow a disk image, you must use file system and
|
After using this command to grow a disk image, you must use file system and
|
||||||
|
|
|
@ -38,7 +38,7 @@ driver options if ``--image-opts`` is specified.
|
||||||
supported. The common object types that it makes sense to define are the
|
supported. The common object types that it makes sense to define are the
|
||||||
``secret`` object, which is used to supply passwords and/or encryption
|
``secret`` object, which is used to supply passwords and/or encryption
|
||||||
keys, and the ``tls-creds`` object, which is used to supply TLS
|
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.
|
||||||
|
|
||||||
.. option:: -p, --port=PORT
|
.. option:: -p, --port=PORT
|
||||||
|
|
||||||
|
@ -238,7 +238,7 @@ daemon:
|
||||||
Expose the guest-visible contents of a qcow2 file via a block device
|
Expose the guest-visible contents of a qcow2 file via a block device
|
||||||
/dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for
|
/dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for
|
||||||
partitions found within), then disconnect the device when done.
|
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``
|
privileges, and may also require the execution of ``modprobe nbd``
|
||||||
to enable the kernel NBD client module. *CAUTION*: Do not use
|
to enable the kernel NBD client module. *CAUTION*: Do not use
|
||||||
this method to mount filesystems from an untrusted guest image - a
|
this method to mount filesystems from an untrusted guest image - a
|
||||||
|
|
|
@ -10,9 +10,10 @@ Synopsis
|
||||||
Description
|
Description
|
||||||
-----------
|
-----------
|
||||||
|
|
||||||
qemu-storage-daemon provides disk image functionality from QEMU, qemu-img, and
|
``qemu-storage-daemon`` provides disk image functionality from QEMU,
|
||||||
qemu-nbd in a long-running process controlled via QMP commands without running
|
``qemu-img``, and ``qemu-nbd`` in a long-running process controlled via QMP
|
||||||
a virtual machine. It can export disk images, run block job operations, and
|
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
|
perform other disk-related operations. The daemon is controlled via a QMP
|
||||||
monitor and initial configuration from the command-line.
|
monitor and initial configuration from the command-line.
|
||||||
|
|
||||||
|
|
|
@ -136,8 +136,8 @@ Extended attribute (xattr) mapping
|
||||||
By default the name of xattr's used by the client are passed through to the server
|
By default the name of xattr's used by the client are passed through to the server
|
||||||
file system. This can be a problem where either those xattr names are used
|
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
|
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 cannot
|
``virtiofsd`` is running in a container with restricted privileges where it
|
||||||
access some attributes.
|
cannot access some attributes.
|
||||||
|
|
||||||
Mapping syntax
|
Mapping syntax
|
||||||
~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~
|
||||||
|
|
Loading…
Reference in New Issue