Skip to content

docs: add qemu-storage-daemon documentation

Stefan Hajnoczi qemu-devel 3 versions – In review

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v3 Latest3 patches 5 repliesIn review
  2. v23 patches 6 repliesSuperseded
  3. v14 patches 14 repliesSuperseded

Changes in v3 from the cover letter

* Address Kevin's comments

Patches in v3 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/3docs: generate qemu-storage-daemon-qmp-ref(7) man pagedocs/interop/conf.py docs/interop/index.rst docs/interop/qemu-storage-daemon-qmp-ref.rst +2 more+20 -05 replies
2/3docs: add qemu-storage-daemon(1) man pagedocs/tools/conf.py docs/tools/index.rst docs/tools/qemu-storage-daemon.rst+151 -00 replies
3/3MAINTAINERS: add Kevin Wolf as storage daemon maintainerMAINTAINERS+9 -00 replies

Reviews trailers per patch

1 of 3 patches has a Reviewed-by or Acked-by.

PatchKevin WolfPhilippe Mathieu-Daudé
1/3
2/3
3/3A-b R-b

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.

Read the v3 thread

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=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
Signature · 1 line
2.28.0