* [PATCH v2 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
2020-09-10 14:43 [PATCH v2 0/3] docs: add qemu-storage-daemon documentation Stefan Hajnoczi
@ 2020-09-10 14:43 ` Stefan Hajnoczi
2020-10-06 10:22 ` Kevin Wolf
2020-09-10 14:43 ` [PATCH v2 2/3] docs: add qemu-storage-daemon(1) " Stefan Hajnoczi
` (2 subsequent siblings)
3 siblings, 1 reply; 10+ messages in thread
From: Stefan Hajnoczi @ 2020-09-10 14:43 UTC (permalink / raw)
To: qemu-devel
Cc: Kevin Wolf, Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi, Laszlo Ersek,
Markus Armbruster, Stefan Hajnoczi, Philippe Mathieu-Daudé
Although qemu-storage-daemon QMP commands are identical to QEMU QMP
commands they are a subset. Generate a manual page of just the commands
supported by qemu-storage-daemon so that users know exactly what is
available in qemu-storage-daemon.
Add an h1 heading in storage-daemon/qapi/qapi-schema.json so that
block-core.json is at the h2 heading level.
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
storage-daemon/qapi/qapi-schema.json | 4 +
docs/interop/qemu-storage-daemon-qmp-ref.texi | 80 +++++++++++++++++++
meson.build | 9 +++
storage-daemon/qapi/meson.build | 2 +
4 files changed, 95 insertions(+)
create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.texi
diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qapi-schema.json
index 6100d1f0c9..939a6afd18 100644
--- a/storage-daemon/qapi/qapi-schema.json
+++ b/storage-daemon/qapi/qapi-schema.json
@@ -15,7 +15,11 @@
{ 'include': '../../qapi/pragma.json' }
+##
+# = Block devices
+##
{ 'include': '../../qapi/block-core.json' }
+
{ 'include': '../../qapi/char.json' }
{ 'include': '../../qapi/common.json' }
{ 'include': '../../qapi/control.json' }
diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.texi b/docs/interop/qemu-storage-daemon-qmp-ref.texi
new file mode 100644
index 0000000000..a6a70c9674
--- /dev/null
+++ b/docs/interop/qemu-storage-daemon-qmp-ref.texi
@@ -0,0 +1,80 @@
+\input texinfo
+@setfilename qemu-storage-daemon-qmp-ref.info
+
+@include version.texi
+
+@exampleindent 0
+@paragraphindent 0
+
+@settitle QEMU Storage Daemon QMP Reference Manual
+
+@iftex
+@center @image{docs/qemu_logo}
+@end iftex
+
+@copying
+This is the QEMU Storage Daemon QMP reference manual.
+
+Copyright @copyright{} 2020 The QEMU Project developers
+
+@quotation
+This manual is free documentation: you can redistribute it and/or
+modify it under the terms of the GNU General Public License as
+published by the Free Software Foundation, either version 2 of the
+License, or (at your option) any later version.
+
+This manual is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this manual. If not, see http://www.gnu.org/licenses/.
+@end quotation
+@end copying
+
+@dircategory QEMU
+@direntry
+* QEMU-Storage-Daemon-QMP-Ref: (qemu-storage-daemon-qmp-ref). QEMU Storage Daemon QMP Reference Manual
+@end direntry
+
+@titlepage
+@title QEMU Storage Daemon QMP Reference Manual
+@subtitle QEMU version @value{VERSION}
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top QEMU Storage Daemon QMP reference
+@end ifnottex
+
+@menu
+* API Reference::
+* Commands and Events Index::
+* Data Types Index::
+@end menu
+
+@node API Reference
+@chapter API Reference
+
+@c for texi2pod:
+@c man begin DESCRIPTION
+
+@include storage-daemon/qapi/qapi-doc.texi
+
+@c man end
+
+@node Commands and Events Index
+@unnumbered Commands and Events Index
+@printindex fn
+
+@node Data Types Index
+@unnumbered Data Types Index
+@printindex tp
+
+@bye
diff --git a/meson.build b/meson.build
index 5421eca66a..f20e409f8e 100644
--- a/meson.build
+++ b/meson.build
@@ -1229,6 +1229,15 @@ if build_docs
if 'CONFIG_GUEST_AGENT' in config_host
texi += {'qemu-ga-ref': ['docs/interop/qemu-ga-ref.texi', qga_qapi_doc_texi, version_texi]}
endif
+ if have_tools
+ texi += {
+ 'qemu-storage-daemon-qmp-ref': [
+ 'docs/interop/qemu-storage-daemon-qmp-ref.texi',
+ qsd_qapi_doc_texi,
+ version_texi
+ ]
+ }
+ endif
if makeinfo.found()
cmd = [
diff --git a/storage-daemon/qapi/meson.build b/storage-daemon/qapi/meson.build
index cea618bec0..7c48a388d4 100644
--- a/storage-daemon/qapi/meson.build
+++ b/storage-daemon/qapi/meson.build
@@ -4,4 +4,6 @@ qsd_qapi_files = custom_target('QAPI files for qemu-storage-daemon',
command: [ qapi_gen, '-o', 'storage-daemon/qapi', '@INPUT@' ],
depend_files: [ qapi_inputs, qapi_gen_depends ])
+qsd_qapi_doc_texi = qsd_qapi_files[-1]
+
qsd_ss.add(qsd_qapi_files.to_list())
--
2.26.2
^ permalink raw reply related [flat|nested] 10+ messages in thread* Re: [PATCH v2 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
2020-09-10 14:43 ` [PATCH v2 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page Stefan Hajnoczi
@ 2020-10-06 10:22 ` Kevin Wolf
2020-12-09 10:21 ` Stefan Hajnoczi
0 siblings, 1 reply; 10+ messages in thread
From: Kevin Wolf @ 2020-10-06 10:22 UTC (permalink / raw)
To: Stefan Hajnoczi
Cc: Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi, Laszlo Ersek, qemu-devel,
Markus Armbruster, Philippe Mathieu-Daudé
Am 10.09.2020 um 16:43 hat Stefan Hajnoczi geschrieben:
> Although qemu-storage-daemon QMP commands are identical to QEMU QMP
> commands they are a subset. Generate a manual page of just the commands
> supported by qemu-storage-daemon so that users know exactly what is
> available in qemu-storage-daemon.
>
> Add an h1 heading in storage-daemon/qapi/qapi-schema.json so that
> block-core.json is at the h2 heading level.
>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
As the series doesn't apply any more, I can't actually try it out
easily, but is the order of includes in the schema right now?
I seem to remember that in v1 we discussed that nested includes result
in an unexpected section structure in the documentation in some cases
(such as generic jobs being documented in a subsection of block
devices), and that we need to reorder includes in qapi-schema.json to
fix this because a more clever doc generator wasn't considered worth the
effort.
Kevin
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH v2 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
2020-10-06 10:22 ` Kevin Wolf
@ 2020-12-09 10:21 ` Stefan Hajnoczi
0 siblings, 0 replies; 10+ messages in thread
From: Stefan Hajnoczi @ 2020-12-09 10:21 UTC (permalink / raw)
To: Kevin Wolf
Cc: Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi, Laszlo Ersek, qemu-devel,
Markus Armbruster, Philippe Mathieu-Daudé
[-- Attachment #1: Type: text/plain, Size: 1174 bytes --]
On Tue, Oct 06, 2020 at 12:22:55PM +0200, Kevin Wolf wrote:
> Am 10.09.2020 um 16:43 hat Stefan Hajnoczi geschrieben:
> > Although qemu-storage-daemon QMP commands are identical to QEMU QMP
> > commands they are a subset. Generate a manual page of just the commands
> > supported by qemu-storage-daemon so that users know exactly what is
> > available in qemu-storage-daemon.
> >
> > Add an h1 heading in storage-daemon/qapi/qapi-schema.json so that
> > block-core.json is at the h2 heading level.
> >
> > Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
>
> As the series doesn't apply any more, I can't actually try it out
> easily, but is the order of includes in the schema right now?
>
> I seem to remember that in v1 we discussed that nested includes result
> in an unexpected section structure in the documentation in some cases
> (such as generic jobs being documented in a subsection of block
> devices), and that we need to reorder includes in qapi-schema.json to
> fix this because a more clever doc generator wasn't considered worth the
> effort.
v2 onwards takes a different approach and leaves the header where it is.
Stefan
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
^ permalink raw reply [flat|nested] 10+ messages in thread
* [PATCH v2 2/3] docs: add qemu-storage-daemon(1) man page
2020-09-10 14:43 [PATCH v2 0/3] docs: add qemu-storage-daemon documentation Stefan Hajnoczi
2020-09-10 14:43 ` [PATCH v2 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page Stefan Hajnoczi
@ 2020-09-10 14:43 ` Stefan Hajnoczi
2020-10-06 10:18 ` Kevin Wolf
2020-09-10 14:44 ` [PATCH v2 3/3] MAINTAINERS: add Kevin Wolf as storage daemon maintainer Stefan Hajnoczi
2020-09-23 12:53 ` [PATCH v2 0/3] docs: add qemu-storage-daemon documentation Stefan Hajnoczi
3 siblings, 1 reply; 10+ messages in thread
From: Stefan Hajnoczi @ 2020-09-10 14:43 UTC (permalink / raw)
To: qemu-devel
Cc: Kevin Wolf, Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi, Laszlo Ersek,
Markus Armbruster, Stefan Hajnoczi, Philippe Mathieu-Daudé
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 <stefanha@redhat.com>
---
docs/tools/conf.py | 2 +
docs/tools/index.rst | 1 +
docs/tools/qemu-storage-daemon.rst | 121 +++++++++++++++++++++++++++++
3 files changed, 124 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 <anthony@codemonkey.ws>'], 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 0000000000..a0b8b1a2bf
--- /dev/null
+++ b/docs/tools/qemu-storage-daemon.rst
@@ -0,0 +1,121 @@
+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=<host>,addr.port=<port>[,tls-creds=<id>][,tls-authz=<id>]
+ --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>]
+
+ 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 <type>,help
+ --object <type>[,<property>=<value>...]
+
+ is a QEMU user creatable object definition. List object types with ``help``.
+ List object properties with ``<type>,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.
+
+Examples
+--------
+Launch the daemon with QMP monitor socket ``qmp.sock`` so clients can execute
+QMP commands::
+
+ $ qemu-storage-daemon \
+ --chardev socket,path=qmp.sock,server,nowait,id=char1 \
+ --monitor chardev=char1
+
+Export raw image file ``disk.img`` over NBD UNIX domain socket ``nbd.sock``::
+
+ $ qemu-storage-daemon \
+ --blockdev driver=file,node-name=disk,filename=disk.img \
+ --nbd-server addr.type=unix,addr.path=nbd.sock \
+ --export type=nbd,device=disk,writable=on
+
+See also
+--------
+
+:manpage:`qemu(1)`, :manpage:`qemu-block-drivers(7)`, :manpage:`qemu-storage-daemon-qmp-ref(7)`
--
2.26.2
^ permalink raw reply related [flat|nested] 10+ messages in thread* Re: [PATCH v2 2/3] docs: add qemu-storage-daemon(1) man page
2020-09-10 14:43 ` [PATCH v2 2/3] docs: add qemu-storage-daemon(1) " Stefan Hajnoczi
@ 2020-10-06 10:18 ` Kevin Wolf
0 siblings, 0 replies; 10+ messages in thread
From: Kevin Wolf @ 2020-10-06 10:18 UTC (permalink / raw)
To: Stefan Hajnoczi
Cc: Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi, Laszlo Ersek, qemu-devel,
Markus Armbruster, Philippe Mathieu-Daudé
Am 10.09.2020 um 16:43 hat Stefan Hajnoczi geschrieben:
> 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 <stefanha@redhat.com>
> ---
> docs/tools/conf.py | 2 +
> docs/tools/index.rst | 1 +
> docs/tools/qemu-storage-daemon.rst | 121 +++++++++++++++++++++++++++++
> 3 files changed, 124 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 <anthony@codemonkey.ws>'], 8),
> 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 0000000000..a0b8b1a2bf
> --- /dev/null
> +++ b/docs/tools/qemu-storage-daemon.rst
> @@ -0,0 +1,121 @@
> +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
While this is true today, I think we should phrase it in a more generic
way so that we don't have to modify it each time we add something.
Specifically, I wouldn't mention NBD here, but just say "can export disk
images". If you want, you can add something like "(e.g. over NBD)" to
make clear that this won't be the only option.
> +operations, and perform other disk-related operations. The daemon is controlled
> +via a QMP monitor socket and initial configuration from the command-line.
Likewise I would s/socket// because you can have the QMP monitor on any
chardev. It could be a socket, it could be stdio, maybe there is even a
third option that makes sense.
> +The daemon offers the following subset of QEMU features:
> +
> +* Blockdev nodes
I think we call this "Block nodes" usually in documentation.
> +* Block jobs
> +* NBD server
Let's make this "Block exports"
> +* Character devices
> +* Crypto and secrets
> +* QMP
If we mention crypto/secrets, should we also mention iothreads
explicitly? Or throttle groups?
Or again more generically something like "User-creatable QOM objects
such as crypto secrets and iothread"?
> +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
It's not "this" help in the man page.
> +.. 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.
s/blockdev/block/g
qemu-block-drivers(7) was originally a list of options for 'qemu-img
create'. I see that it now describes runtime options for some drivers (in
particular the network drivers), but not the image format drivers.
I guess this needs some cleanup so that create options and runtime
options are clearly separated, and that runtime options for format
drivers are documented.
It doesn't have to stop this patch, though the reference could be
confusing when the other man page starts with create options.
> +.. 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=<host>,addr.port=<port>[,tls-creds=<id>][,tls-authz=<id>]
> + --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>]
> +
> + 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 <type>,help
> + --object <type>[,<property>=<value>...]
> +
> + is a QEMU user creatable object definition. List object types with ``help``.
> + List object properties with ``<type>,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.
Isn't iothread more common actually?
> +Examples
> +--------
> +Launch the daemon with QMP monitor socket ``qmp.sock`` so clients can execute
> +QMP commands::
> +
> + $ qemu-storage-daemon \
> + --chardev socket,path=qmp.sock,server,nowait,id=char1 \
> + --monitor chardev=char1
> +
> +Export raw image file ``disk.img`` over NBD UNIX domain socket ``nbd.sock``::
> +
> + $ qemu-storage-daemon \
> + --blockdev driver=file,node-name=disk,filename=disk.img \
> + --nbd-server addr.type=unix,addr.path=nbd.sock \
> + --export type=nbd,device=disk,writable=on
The --export syntax for NBD has changed with the block export series.
I think that you need s/device/node-name/ and that it requires an id=...
option now, too.
> +See also
> +--------
> +
> +:manpage:`qemu(1)`, :manpage:`qemu-block-drivers(7)`, :manpage:`qemu-storage-daemon-qmp-ref(7)`
> --
> 2.26.2
Kevin
^ permalink raw reply [flat|nested] 10+ messages in thread
* [PATCH v2 3/3] MAINTAINERS: add Kevin Wolf as storage daemon maintainer
2020-09-10 14:43 [PATCH v2 0/3] docs: add qemu-storage-daemon documentation Stefan Hajnoczi
2020-09-10 14:43 ` [PATCH v2 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page Stefan Hajnoczi
2020-09-10 14:43 ` [PATCH v2 2/3] docs: add qemu-storage-daemon(1) " Stefan Hajnoczi
@ 2020-09-10 14:44 ` Stefan Hajnoczi
2020-10-06 10:23 ` Kevin Wolf
2020-10-06 11:20 ` Philippe Mathieu-Daudé
2020-09-23 12:53 ` [PATCH v2 0/3] docs: add qemu-storage-daemon documentation Stefan Hajnoczi
3 siblings, 2 replies; 10+ messages in thread
From: Stefan Hajnoczi @ 2020-09-10 14:44 UTC (permalink / raw)
To: qemu-devel
Cc: Kevin Wolf, Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi, Laszlo Ersek,
Markus Armbruster, Stefan Hajnoczi, Philippe Mathieu-Daudé
The MAINTAINERS file was not updated when the storage daemon was merged.
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
MAINTAINERS | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 7d0a5e91e4..eb80b6c548 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2099,6 +2099,15 @@ F: qobject/block-qdict.c
F: tests/check-block-qdict.c
T: git https://repo.or.cz/qemu/kevin.git block
+Storage daemon
+M: Kevin Wolf <kwolf@redhat.com>
+L: qemu-block@nongnu.org
+S: Supported
+F: storage-daemon/
+F: docs/interop/qemu-storage-daemon-qmp-ref.texi
+F: docs/tools/qemu-storage-daemon.rst
+T: git https://repo.or.cz/qemu/kevin.git block
+
Block I/O path
M: Stefan Hajnoczi <stefanha@redhat.com>
M: Fam Zheng <fam@euphon.net>
--
2.26.2
^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH v2 3/3] MAINTAINERS: add Kevin Wolf as storage daemon maintainer
2020-09-10 14:44 ` [PATCH v2 3/3] MAINTAINERS: add Kevin Wolf as storage daemon maintainer Stefan Hajnoczi
@ 2020-10-06 10:23 ` Kevin Wolf
2020-10-06 11:20 ` Philippe Mathieu-Daudé
1 sibling, 0 replies; 10+ messages in thread
From: Kevin Wolf @ 2020-10-06 10:23 UTC (permalink / raw)
To: Stefan Hajnoczi
Cc: Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi, Laszlo Ersek, qemu-devel,
Markus Armbruster, Philippe Mathieu-Daudé
Am 10.09.2020 um 16:44 hat Stefan Hajnoczi geschrieben:
> The MAINTAINERS file was not updated when the storage daemon was merged.
>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Acked-by: Kevin Wolf <kwolf@redhat.com>
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH v2 3/3] MAINTAINERS: add Kevin Wolf as storage daemon maintainer
2020-09-10 14:44 ` [PATCH v2 3/3] MAINTAINERS: add Kevin Wolf as storage daemon maintainer Stefan Hajnoczi
2020-10-06 10:23 ` Kevin Wolf
@ 2020-10-06 11:20 ` Philippe Mathieu-Daudé
1 sibling, 0 replies; 10+ messages in thread
From: Philippe Mathieu-Daudé @ 2020-10-06 11:20 UTC (permalink / raw)
To: Stefan Hajnoczi, qemu-devel
Cc: Kevin Wolf, Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi, Markus Armbruster,
Laszlo Ersek
On 9/10/20 4:44 PM, Stefan Hajnoczi wrote:
> The MAINTAINERS file was not updated when the storage daemon was merged.
>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
> MAINTAINERS | 9 +++++++++
> 1 file changed, 9 insertions(+)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 7d0a5e91e4..eb80b6c548 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2099,6 +2099,15 @@ F: qobject/block-qdict.c
> F: tests/check-block-qdict.c
> T: git https://repo.or.cz/qemu/kevin.git block
>
> +Storage daemon
> +M: Kevin Wolf <kwolf@redhat.com>
> +L: qemu-block@nongnu.org
> +S: Supported
> +F: storage-daemon/
> +F: docs/interop/qemu-storage-daemon-qmp-ref.texi
> +F: docs/tools/qemu-storage-daemon.rst
> +T: git https://repo.or.cz/qemu/kevin.git block
> +
> Block I/O path
> M: Stefan Hajnoczi <stefanha@redhat.com>
> M: Fam Zheng <fam@euphon.net>
>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
=)
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH v2 0/3] docs: add qemu-storage-daemon documentation
2020-09-10 14:43 [PATCH v2 0/3] docs: add qemu-storage-daemon documentation Stefan Hajnoczi
` (2 preceding siblings ...)
2020-09-10 14:44 ` [PATCH v2 3/3] MAINTAINERS: add Kevin Wolf as storage daemon maintainer Stefan Hajnoczi
@ 2020-09-23 12:53 ` Stefan Hajnoczi
3 siblings, 0 replies; 10+ messages in thread
From: Stefan Hajnoczi @ 2020-09-23 12:53 UTC (permalink / raw)
To: qemu-devel
Cc: Kevin Wolf, Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi, Laszlo Ersek,
Markus Armbruster, Philippe Mathieu-Daudé
[-- Attachment #1: Type: text/plain, Size: 6749 bytes --]
On Thu, Sep 10, 2020 at 03:43:57PM +0100, Stefan Hajnoczi wrote:
> v2:
> * Drop block-core.json h2 header removal, add an h1 header to
> storage-daemon/qapi/qapi-schema.json instead [Kevin]
> * Add Examples section to man page [Kevin]
Ping
> Add documentation for the qemu-storage-daemon program and its QMP commands.
>
> The man page looks like this:
>
> QEMU-STORAGE-DAEMON(1) QEMU QEMU-STORAGE-DAEMON(1)
>
> NAME
> qemu-storage-daemon - 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 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
> Standard options:
>
> -h, --help
> Display this help and exit
>
> -V, --version
> Display version information and exit
>
> -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
> Specify tracing options.
>
> [enable=]PATTERN
> Immediately enable events matching PATTERN (either event name or a globbing pattern). This option is only available if QEMU has been compiled with the simple, log
> or ftrace tracing backend. To specify multiple events or patterns, specify the -trace option multiple times.
>
> Use -trace help to print a list of names of trace points.
>
> events=FILE
> Immediately enable events listed in FILE. The file must contain one event name (as listed in the trace-events-all file) per line; globbing patterns are accepted
> too. This option is only available if QEMU has been compiled with the simple, log or ftrace tracing backend.
>
> file=FILE
> Log output traces to FILE. This option is only available if QEMU has been compiled with the simple tracing backend.
>
> --blockdev BLOCKDEVDEF
> is a blockdev node definition. See the qemu(1) manual page for a description of blockdev node properties and the qemu-block-drivers(7) manual page for a description of
> driver-specific parameters.
>
> --chardev CHARDEVDEF
> is a character device definition. See the 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
>
> --monitor MONITORDEF
> is a QMP monitor definition. See the 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
>
> --nbd-server addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-authz=<id>]
>
> --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>]
> 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
>
> --object help
>
> --object <type>,help
>
> --object <type>[,<property>=<value>...]
> is a QEMU user creatable object definition. List object types with help. List object properties with <type>,help. See the 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.
>
> EXAMPLES
> Launch the daemon with QMP monitor socket qmp.sock so clients can
> execute QMP commands:
>
> $ qemu-storage-daemon \
> --chardev socket,path=qmp.sock,server,nowait,id=char1 \
> --monitor chardev=char1
>
> Export raw image file disk.img over NBD UNIX domain socket nbd.sock:
>
> $ qemu-storage-daemon \
> --blockdev driver=file,node-name=disk,filename=disk.img \
> --nbd-server addr.type=unix,addr.path=nbd.sock \
> --export type=nbd,device=disk,writable=on
>
> SEE ALSO
> qemu(1), qemu-block-drivers(7), qemu-storage-daemon-qmp-ref(7)
>
> COPYRIGHT
> 2020, The QEMU Project Developers
>
> 5.1.50 Sep 10, 2020 QEMU-STORAGE-DAEMON(1)
>
> Stefan Hajnoczi (3):
> docs: generate qemu-storage-daemon-qmp-ref(7) man page
> docs: add qemu-storage-daemon(1) man page
> MAINTAINERS: add Kevin Wolf as storage daemon maintainer
>
> MAINTAINERS | 9 ++
> storage-daemon/qapi/qapi-schema.json | 4 +
> docs/interop/qemu-storage-daemon-qmp-ref.texi | 80 ++++++++++++
> docs/tools/conf.py | 2 +
> docs/tools/index.rst | 1 +
> docs/tools/qemu-storage-daemon.rst | 121 ++++++++++++++++++
> meson.build | 9 ++
> storage-daemon/qapi/meson.build | 2 +
> 8 files changed, 228 insertions(+)
> create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.texi
> create mode 100644 docs/tools/qemu-storage-daemon.rst
>
> --
> 2.26.2
>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
^ permalink raw reply [flat|nested] 10+ messages in thread