| Message ID | 20200910144400.69615-1-stefanha@redhat.com |
|---|---|
| Headers | show |
| Series | docs: add qemu-storage-daemon documentation | expand |
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 >
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
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
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] 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