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=qcow2
SEE 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
--
2.28.0
