Re: [PATCH 3/4] docs: add qemu-storage-daemon(1) man page
On Tue, Sep 08, 2020 at 04:33:47PM +0200, Kevin Wolf wrote: > Am 08.09.2020 um 13:42 hat Kashyap Chamarthy geschrieben: > > On Tue, Sep 08, 2020 at 10:31:12AM +0100, Stefan Hajnoczi wrote: > > > Document the qemu-storage-daemon tool. Most of the command-line options > > > are identical to their QEMU counterparts. Perhaps Sphinx hxtool > > > integration could be extended to extract documentation for individual > > > command-line options so they can be shared. For now the > > > qemu-storage-daemon simply refers to the qemu(1) man page where the > > > command-line options are identical. > > > > > > Signed-off-by: Stefan Hajnoczi > > Looks good to me. > > If you have to respin, maybe an example section with some full command > lines for common cases would be nice. Maybe one for exporting a qcow2 > image via NBD, and another one for attaching a host_device and having a > QMP monitor, or something like this. Good idea. Will fix in v2. > > > +**Warning:** Never modify images in use by a running virtual machine or > > > any > > > +other process; this may destroy the image. Also, be aware that querying > > > an > > > +image that is being modified by another process may encounter > > > inconsistent > > > +state. > > > > I wonder if it's appropriate to mention libguestfs for safe, read-only > > access to disk images (via `guestfish -ro -i -a disk.qcow2`). I say > > this because, the above warning tells what _not_ to do; a pointer on > > what to do could be useful. I let you decide on this. > > libguestfs may expose exactly the inconsistent state that the above > warning is about. Maybe it breaks not very often in practice, but it's > fundamentally unsafe and if it breaks, you get to keep both pieces. > > The safe way is to access it from the guest. I agree. If a guest has disk.qcow2 open read/write then libguestfs cannot open it (even just for reading) and expect a consistent view of the disk. Stefan signature.asc Description: PGP signature
Re: [PATCH 3/4] docs: add qemu-storage-daemon(1) man page
Am 08.09.2020 um 13:42 hat Kashyap Chamarthy geschrieben: > On Tue, Sep 08, 2020 at 10:31:12AM +0100, Stefan Hajnoczi wrote: > > Document the qemu-storage-daemon tool. Most of the command-line options > > are identical to their QEMU counterparts. Perhaps Sphinx hxtool > > integration could be extended to extract documentation for individual > > command-line options so they can be shared. For now the > > qemu-storage-daemon simply refers to the qemu(1) man page where the > > command-line options are identical. > > > > Signed-off-by: Stefan Hajnoczi Looks good to me. If you have to respin, maybe an example section with some full command lines for common cases would be nice. Maybe one for exporting a qcow2 image via NBD, and another one for attaching a host_device and having a QMP monitor, or something like this. > > +**Warning:** Never modify images in use by a running virtual machine or any > > +other process; this may destroy the image. Also, be aware that querying an > > +image that is being modified by another process may encounter inconsistent > > +state. > > I wonder if it's appropriate to mention libguestfs for safe, read-only > access to disk images (via `guestfish -ro -i -a disk.qcow2`). I say > this because, the above warning tells what _not_ to do; a pointer on > what to do could be useful. I let you decide on this. libguestfs may expose exactly the inconsistent state that the above warning is about. Maybe it breaks not very often in practice, but it's fundamentally unsafe and if it breaks, you get to keep both pieces. The safe way is to access it from the guest. Kevin
Re: [PATCH 3/4] docs: add qemu-storage-daemon(1) man page
On Tue, Sep 08, 2020 at 10:31:12AM +0100, Stefan Hajnoczi wrote:
> Document the qemu-storage-daemon tool. Most of the command-line options
> are identical to their QEMU counterparts. Perhaps Sphinx hxtool
> integration could be extended to extract documentation for individual
> command-line options so they can be shared. For now the
> qemu-storage-daemon simply refers to the qemu(1) man page where the
> command-line options are identical.
>
> Signed-off-by: Stefan Hajnoczi
> ---
> docs/tools/conf.py | 2 +
> docs/tools/index.rst | 1 +
> docs/tools/qemu-storage-daemon.rst | 105 +
> 3 files changed, 108 insertions(+)
> create mode 100644 docs/tools/qemu-storage-daemon.rst
>
> diff --git a/docs/tools/conf.py b/docs/tools/conf.py
> index 9052d17d6d..c16290e716 100644
> --- a/docs/tools/conf.py
> +++ b/docs/tools/conf.py
> @@ -20,6 +20,8 @@ html_theme_options['description'] = \
> man_pages = [
> ('qemu-img', 'qemu-img', u'QEMU disk image utility',
> ['Fabrice Bellard'], 1),
> +('qemu-storage-daemon', 'qemu-storage-daemon', u'QEMU storage daemon',
> + [], 1),
> ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
> ['Anthony Liguori '], 8),
> ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
> diff --git a/docs/tools/index.rst b/docs/tools/index.rst
> index 232ce9f3e4..9b076adb62 100644
> --- a/docs/tools/index.rst
> +++ b/docs/tools/index.rst
> @@ -11,6 +11,7 @@ Contents:
> :maxdepth: 2
>
> qemu-img
> + qemu-storage-daemon
> qemu-nbd
> qemu-trace-stap
> virtfs-proxy-helper
> diff --git a/docs/tools/qemu-storage-daemon.rst
> b/docs/tools/qemu-storage-daemon.rst
> new file mode 100644
> index 00..729a5e7248
> --- /dev/null
> +++ b/docs/tools/qemu-storage-daemon.rst
> @@ -0,0 +1,105 @@
> +QEMU Storage Daemon
> +===
> +
> +Synopsis
> +
> +
> +**qemu-storage-daemon** [options]
> +
> +Description
> +---
> +
> +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 over NBD, run block job
> +operations, and perform other disk-related operations. The daemon is
> controlled
> +via a QMP monitor socket and initial configuration from the command-line.
> +
> +The daemon offers the following subset of QEMU features:
> +
> +* Blockdev nodes
> +* Block jobs
> +* NBD server
> +* Character devices
> +* Crypto and secrets
> +* QMP
> +
> +Commands can be sent over a QEMU Monitor Protocol (QMP) connection. See the
> +:manpage:`qemu-storage-daemon-qmp-ref(7)` manual page for a description of
> the
> +commands.
> +
> +The daemon runs until it is stopped using the ``quit`` QMP command or
> +SIGINT/SIGHUP/SIGTERM.
> +
> +**Warning:** Never modify images in use by a running virtual machine or any
> +other process; this may destroy the image. Also, be aware that querying an
> +image that is being modified by another process may encounter inconsistent
> +state.
I wonder if it's appropriate to mention libguestfs for safe, read-only
access to disk images (via `guestfish -ro -i -a disk.qcow2`). I say
this because, the above warning tells what _not_ to do; a pointer on
what to do could be useful. I let you decide on this.
The rest looks good to me; I couldn't even spot a typo.
Reviewed-by: Kashyap Chamarthy
[...]
--
/kashyap
[PATCH 3/4] docs: add qemu-storage-daemon(1) man page
Document the qemu-storage-daemon tool. Most of the command-line options
are identical to their QEMU counterparts. Perhaps Sphinx hxtool
integration could be extended to extract documentation for individual
command-line options so they can be shared. For now the
qemu-storage-daemon simply refers to the qemu(1) man page where the
command-line options are identical.
Signed-off-by: Stefan Hajnoczi
---
docs/tools/conf.py | 2 +
docs/tools/index.rst | 1 +
docs/tools/qemu-storage-daemon.rst | 105 +
3 files changed, 108 insertions(+)
create mode 100644 docs/tools/qemu-storage-daemon.rst
diff --git a/docs/tools/conf.py b/docs/tools/conf.py
index 9052d17d6d..c16290e716 100644
--- a/docs/tools/conf.py
+++ b/docs/tools/conf.py
@@ -20,6 +20,8 @@ html_theme_options['description'] = \
man_pages = [
('qemu-img', 'qemu-img', u'QEMU disk image utility',
['Fabrice Bellard'], 1),
+('qemu-storage-daemon', 'qemu-storage-daemon', u'QEMU storage daemon',
+ [], 1),
('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
['Anthony Liguori '], 8),
('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
index 232ce9f3e4..9b076adb62 100644
--- a/docs/tools/index.rst
+++ b/docs/tools/index.rst
@@ -11,6 +11,7 @@ Contents:
:maxdepth: 2
qemu-img
+ qemu-storage-daemon
qemu-nbd
qemu-trace-stap
virtfs-proxy-helper
diff --git a/docs/tools/qemu-storage-daemon.rst
b/docs/tools/qemu-storage-daemon.rst
new file mode 100644
index 00..729a5e7248
--- /dev/null
+++ b/docs/tools/qemu-storage-daemon.rst
@@ -0,0 +1,105 @@
+QEMU Storage Daemon
+===
+
+Synopsis
+
+
+**qemu-storage-daemon** [options]
+
+Description
+---
+
+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 over NBD, run block job
+operations, and perform other disk-related operations. The daemon is controlled
+via a QMP monitor socket and initial configuration from the command-line.
+
+The daemon offers the following subset of QEMU features:
+
+* Blockdev nodes
+* Block jobs
+* NBD server
+* Character devices
+* Crypto and secrets
+* QMP
+
+Commands can be sent over a QEMU Monitor Protocol (QMP) connection. See the
+:manpage:`qemu-storage-daemon-qmp-ref(7)` manual page for a description of the
+commands.
+
+The daemon runs until it is stopped using the ``quit`` QMP command or
+SIGINT/SIGHUP/SIGTERM.
+
+**Warning:** Never modify images in use by a running virtual machine or any
+other process; this may destroy the image. Also, be aware that querying an
+image that is being modified by another process may encounter inconsistent
+state.
+
+Options
+---
+
+.. program:: qemu-storage-daemon
+
+Standard options:
+
+.. option:: -h, --help
+
+ Display this help and exit
+
+.. option:: -V, --version
+
+ Display version information and exit
+
+.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
+
+ .. include:: ../qemu-option-trace.rst.inc
+
+.. option:: --blockdev BLOCKDEVDEF
+
+ is a blockdev node definition. See the :manpage:`qemu(1)` manual page for a
+ description of blockdev node properties and the
+ :manpage:`qemu-block-drivers(7)` manual page for a description of
+ driver-specific parameters.
+
+.. option:: --chardev CHARDEVDEF
+
+ is a character device definition. See the :manpage:`qemu(1)` manual page for
+ a description of character device properties. A common character device
+ definition configures a UNIX domain socket::
+
+ --chardev socket,id=char1,path=/tmp/qmp.sock,server,nowait
+
+.. option:: --monitor MONITORDEF
+
+ is a QMP monitor definition. See the :manpage:`qemu(1)` manual page for
+ a description of QMP monitor properties. A common QMP monitor definition
+ configures a monitor on character device ``char1``::
+
+ --monitor chardev=char1
+
+.. option:: --nbd-server
addr.type=inet,addr.host=,addr.port=[,tls-creds=][,tls-authz=]
+ --nbd-server
addr.type=unix,addr.path=[,tls-creds=][,tls-authz=]
+
+ is a NBD server definition. Both TCP and UNIX domain sockets are supported.
+ TLS encryption can be configured using ``--object`` tls-creds-* and authz-*
+ secrets (see below).
+
+ To configure an NBD server on UNIX domain socket path ``/tmp/nbd.sock``::
+
+ --nbd-server addr.type=unix,addr.path=/tmp/nbd.sock
+
+.. option:: --object help
+ --object ,help
+ --object [,=...]
+
+ is a QEMU user creatable object definition. List object types with ``help``.
+ List object properties with ``,help``. See the :manpage:`qemu(1)`
+ manual page for a description of the object properties. The most common
+ object type is a ``secret``, which is used to supply passwords and/or
+ encryption keys.
+
+See also
+
+
+:manpage:`qemu(1)`, :manpage:`qem
