[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v2 0/3] docs: add qemu-storage-daemon documentation
From: |
Stefan Hajnoczi |
Subject: |
Re: [PATCH v2 0/3] docs: add qemu-storage-daemon documentation |
Date: |
Wed, 23 Sep 2020 13:53:48 +0100 |
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
>
signature.asc
Description: PGP signature