docs: add qemu-storage-daemon documentation
Get series with b4
b4 am [email protected]Versions newest first · linked by author and title
- v3 Latest3 patches 5 repliesIn review
- v23 patches 6 repliesSuperseded
- v14 patches 14 repliesSuperseded
Changes in v3 from the cover letter
* Address Kevin's comments
Patches in v3 No applies recorded yet
| # | Subject and files | Size | Replies | Applied |
|---|---|---|---|---|
| 1/3 | docs: generate qemu-storage-daemon-qmp-ref(7) man pagedocs/ docs/ docs/ +2 more | +20 | 5 replies | |
| 2/3 | docs: add qemu-storage-daemon(1) man pagedocs/ docs/ docs/ | +151 | 0 replies | |
| 3/3 | MAINTAINERS: add Kevin Wolf as storage daemon maintainerMAINTAINERS | +9 | 0 replies |
Reviews trailers per patch
1 of 3 patches has a Reviewed-by or Acked-by.
| Patch | Kevin Wolf | Philippe Mathieu-Daudé |
|---|---|---|
| 1/3 | ||
| 2/3 | ||
| 3/3 | A-b | R-b |
Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.
Cover letter [PATCH v3 0/3] docs: add qemu-storage-daemon documentation
v3:
* Address Kevin's comments
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 con‐ trolled 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.
The daemon offers the following subset of QEMU features:
• Block nodes
• Block jobs
• Block exports
• Throttle groups
• Character devices
• Crypto and secrets
• QMP
• IOThreads
Commands can be sent over a QEMU Monitor Protocol (QMP) connec‐ tion. 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 ma‐ chine or any other process; this may destroy the image. Also, be aware that querying an image that is being modified by an‐ other process may encounter inconsistent state.
OPTIONS
Standard options:
-h, --help
Display 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 op‐ tion 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 block node definition. See the qemu(1) manual page for a description of block 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 do‐ main socket:
--chardev socket,id=char1,path=/tmp/qmp.sock,server,nowait
--export [type=]nbd,id=<id>,node-name=<node-name>[,name=<ex‐
port-name>][,writable=on|off][,bitmap=<name>]
--export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=unix,addr.path=<socket-path>[,writable=on|off][,log‐ ical-block-size=<block-size>][,num-queues=<num-queues>]
--export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=fd,addr.str=<fd>[,writable=on|off][,log‐ ical-block-size=<block-size>][,num-queues=<num-queues>]
is a block export definition. node-name is the block
node that should be exported. writable determines
whether or not the export allows write requests for mod‐
ifying data (the default is off).
The nbd export type requires --nbd-server (see below). name is the NBD export name. bitmap is the name of a dirty bitmap reachable from the block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the meta‐ data context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap.
The vhost-user-blk export type takes a vhost-user socket address on which it accept incoming connections. Both addr.type=unix,addr.path=<socket-path> for UNIX domain sockets and addr.type=fd,addr.str=<fd> for file descrip‐ tor passing are supported. logical-block-size sets the logical block size in bytes (the default is 512). num-queues sets the number of virtqueues (the default is 1).
--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-au‐ thz=<id>][,max-connections=<n>]
--nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-au‐ thz=<id>][,max-connections=<n>]
is a server for NBD exports. Both TCP and UNIX domain sockets are supported. TLS encryption can be configured using --object tls-creds-* and authz-* secrets (see be‐ low).
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 descrip‐ tion of the object properties.
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,id=export,node-name=disk,writable=on
Export a qcow2 image file disk.qcow2 as a vhosts-user-blk de‐
vice over UNIX domain socket vhost-user-blk.sock:
$ qemu-storage-daemon \
--blockdev driver=file,node-name=file,filename=disk.qcow2 \
--blockdev driver=qcow2,node-name=qcow2,file=file \
--export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2SEE ALSO
qemu(1), qemu-block-drivers(7), qemu-storage-daemon-qmp-ref(7)
COPYRIGHT
2020, The QEMU Project Developers
5.1.94 Dec 09, 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 ++ docs/interop/index.rst | 1 + docs/interop/qemu-storage-daemon-qmp-ref.rst | 13 ++ docs/tools/index.rst | 1 + docs/tools/qemu-storage-daemon.rst | 148 +++++++++++++++++++ storage-daemon/qapi/qapi-schema.json | 3 + docs/interop/conf.py | 2 + docs/meson.build | 1 + docs/tools/conf.py | 2 + 9 files changed, 180 insertions(+) create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.rst create mode 100644 docs/tools/qemu-storage-daemon.rst
Signature · 1 line
2.28.0