From: Stefan Hajnoczi <stefanha@redhat.com>
To: qemu-devel@nongnu.org
Cc: "Kevin Wolf" <kwolf@redhat.com>,
"Peter Maydell" <peter.maydell@linaro.org>,
"Daniel P. Berrangé" <berrange@redhat.com>,
qemu-block@nongnu.org, "Kashyap Chamarthy" <kchamart@redhat.com>,
afrosi@redhat.com, "Laszlo Ersek" <lersek@redhat.com>,
"Markus Armbruster" <armbru@redhat.com>,
"Stefan Hajnoczi" <stefanha@redhat.com>,
"Philippe Mathieu-Daudé" <philmd@redhat.com>
Subject: [PATCH v2 0/3] docs: add qemu-storage-daemon documentation
Date: Thu, 10 Sep 2020 15:43:57 +0100 [thread overview]
Message-ID: <20200910144400.69615-1-stefanha@redhat.com> (raw)
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
--
2.26.2
next reply other threads:[~2020-09-10 14:45 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-10 14:43 Stefan Hajnoczi [this message]
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
2020-09-10 14:43 ` [PATCH v2 2/3] docs: add qemu-storage-daemon(1) " 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-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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200910144400.69615-1-stefanha@redhat.com \
--to=stefanha@redhat.com \
--cc=afrosi@redhat.com \
--cc=armbru@redhat.com \
--cc=berrange@redhat.com \
--cc=kchamart@redhat.com \
--cc=kwolf@redhat.com \
--cc=lersek@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=philmd@redhat.com \
--cc=qemu-block@nongnu.org \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.