qemu/qemu-nbd.texi
Eric Blake 68b96f1583 qemu-nbd: Add --list option
We want to be able to detect whether a given qemu NBD server is
exposing the right export(s) and dirty bitmaps, at least for
regression testing.  We could use 'nbd-client -l' from the upstream
NBD project to list exports, but it's annoying to rely on
out-of-tree binaries; furthermore, nbd-client doesn't necessarily
know about all of the qemu NBD extensions.  Thus, it is time to add
a new mode to qemu-nbd that merely sniffs all possible information
from the server during handshake phase, then disconnects and dumps
the information.

This patch actually implements --list/-L, while reusing other
options such as --tls-creds for now designating how to connect
as the client (rather than their non-list usage of how to operate
as the server).

I debated about adding this functionality to something akin to
'qemu-img info' - but that tool does not readily lend itself
to connecting to an arbitrary NBD server without also tying to
a specific export (I may, however, still add ImageInfoSpecificNBD
for reporting the bitmaps available when connecting to a single
export).  And, while it may feel a bit odd that normally
qemu-nbd is a server but 'qemu-nbd -L' is a client, we are not
really making the qemu-nbd binary that much larger, because
'qemu-nbd -c' has to operate as both server and client
simultaneously across two threads when feeding the kernel module
for /dev/nbdN access.

Sample output:
$ qemu-nbd -L
exports available: 1
 export: ''
  size:  65536
  flags: 0x4ed ( flush fua trim zeroes df cache )
  min block: 512
  opt block: 4096
  max block: 33554432
  available meta contexts: 1
   base:allocation

Note that the output only lists sizes if the server sent
NBD_FLAG_HAS_FLAGS, because a newstyle server does not give
the size otherwise.  It has the side effect that for really
old servers that did not send any flags, the size is not
output even though it was available.  However, I'm not too
concerned about that - oldstyle servers are (rightfully)
getting less common to encounter (qemu 3.0 was the last
version where we even serve it), and most existing servers
that still even offer oldstyle negotiation (such as nbdkit)
still send flags (since that was added to the NBD protocol
in 2007 to permit read-only connections).

Not done here, but maybe worth future experiments: capture
the meat of NBDExportInfo into a QAPI struct, and use the
generated QAPI pretty-printers instead of hand-rolling our
output loop.  It would also permit us to add a JSON output
mode for machine parsing.

Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Richard W.M. Jones <rjones@redhat.com>
Message-Id: <20190117193658.16413-20-eblake@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
2019-01-21 15:49:52 -06:00

204 lines
7.3 KiB
Plaintext

@example
@c man begin SYNOPSIS
@command{qemu-nbd} [OPTION]... @var{filename}
@command{qemu-nbd} @option{-L} [OPTION]...
@command{qemu-nbd} @option{-d} @var{dev}
@c man end
@end example
@c man begin DESCRIPTION
Export a QEMU disk image using the NBD protocol.
Other uses:
@itemize
@item
Bind a /dev/nbdX block device to a QEMU server (on Linux).
@item
As a client to query exports of a remote NBD server.
@end itemize
@c man end
@c man begin OPTIONS
@var{filename} is a disk image filename, or a set of block
driver options if @option{--image-opts} is specified.
@var{dev} is an NBD device.
@table @option
@item --object type,id=@var{id},...props...
Define a new instance of the @var{type} object class identified by @var{id}.
See the @code{qemu(1)} manual page for full details of the properties
supported. The common object types that it makes sense to define are the
@code{secret} object, which is used to supply passwords and/or encryption
keys, and the @code{tls-creds} object, which is used to supply TLS
credentials for the qemu-nbd server or client.
@item -p, --port=@var{port}
The TCP port to listen on as a server, or connect to as a client
(default @samp{10809}).
@item -o, --offset=@var{offset}
The offset into the image.
@item -b, --bind=@var{iface}
The interface to bind to as a server, or connect to as a client
(default @samp{0.0.0.0}).
@item -k, --socket=@var{path}
Use a unix socket with path @var{path}.
@item --image-opts
Treat @var{filename} as a set of image options, instead of a plain
filename. If this flag is specified, the @var{-f} flag should
not be used, instead the '@code{format=}' option should be set.
@item -f, --format=@var{fmt}
Force the use of the block driver for format @var{fmt} instead of
auto-detecting.
@item -r, --read-only
Export the disk as read-only.
@item -P, --partition=@var{num}
Only expose MBR partition @var{num}. Understands physical partitions
1-4 and logical partitions 5-8.
@item -B, --bitmap=@var{name}
If @var{filename} has a qcow2 persistent bitmap @var{name}, expose
that bitmap via the ``qemu:dirty-bitmap:@var{name}'' context
accessible through NBD_OPT_SET_META_CONTEXT.
@item -s, --snapshot
Use @var{filename} as an external snapshot, create a temporary
file with backing_file=@var{filename}, redirect the write to
the temporary one.
@item -l, --load-snapshot=@var{snapshot_param}
Load an internal snapshot inside @var{filename} and export it
as an read-only device, @var{snapshot_param} format is
'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]'
@item -n, --nocache
@itemx --cache=@var{cache}
The cache mode to be used with the file. See the documentation of
the emulator's @code{-drive cache=...} option for allowed values.
@item --aio=@var{aio}
Set the asynchronous I/O mode between @samp{threads} (the default)
and @samp{native} (Linux only).
@item --discard=@var{discard}
Control whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap})
requests are ignored or passed to the filesystem. @var{discard} is one of
@samp{ignore} (or @samp{off}), @samp{unmap} (or @samp{on}). The default is
@samp{ignore}.
@item --detect-zeroes=@var{detect-zeroes}
Control the automatic conversion of plain zero writes by the OS to
driver-specific optimized zero write commands. @var{detect-zeroes} is one of
@samp{off}, @samp{on} or @samp{unmap}. @samp{unmap}
converts a zero write to an unmap operation and can only be used if
@var{discard} is set to @samp{unmap}. The default is @samp{off}.
@item -c, --connect=@var{dev}
Connect @var{filename} to NBD device @var{dev} (Linux only).
@item -d, --disconnect
Disconnect the device @var{dev} (Linux only).
@item -e, --shared=@var{num}
Allow up to @var{num} clients to share the device (default
@samp{1}). Safe for readers, but for now, consistency is not
guaranteed between multiple writers.
@item -t, --persistent
Don't exit on the last connection.
@item -x, --export-name=@var{name}
Set the NBD volume export name (default of a zero-length string).
@item -D, --description=@var{description}
Set the NBD volume export description, as a human-readable
string.
@item -L, --list
Connect as a client and list all details about the exports exposed by
a remote NBD server. This enables list mode, and is incompatible
with options that change behavior related to a specific export (such as
@option{--export-name}, @option{--offset}, ...).
@item --tls-creds=ID
Enable mandatory TLS encryption for the server by setting the ID
of the TLS credentials object previously created with the --object
option; or provide the credentials needed for connecting as a client
in list mode.
@item --fork
Fork off the server process and exit the parent once the server is running.
@item -v, --verbose
Display extra debugging information.
@item -h, --help
Display this help and exit.
@item -V, --version
Display version information and exit.
@item -T, --trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
@findex --trace
@include qemu-option-trace.texi
@end table
@c man end
@c man begin EXAMPLES
Start a server listening on port 10809 that exposes only the
guest-visible contents of a qcow2 file, with no TLS encryption, and
with the default export name (an empty string). The command is
one-shot, and will block until the first successful client
disconnects:
@example
qemu-nbd -f qcow2 file.qcow2
@end example
Start a long-running server listening with encryption on port 10810,
and require clients to have a correct X.509 certificate to connect to
a 1 megabyte subset of a raw file, using the export name 'subset':
@example
qemu-nbd \
--object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \
--tls-creds tls0 -t -x subset -p 10810 \
--image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw
@end example
Serve a read-only copy of just the first MBR partition of a guest
image over a Unix socket with as many as 5 simultaneous readers, with
a persistent process forked as a daemon:
@example
qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \
--partition=1 --read-only --format=qcow2 file.qcow2
@end example
Expose the guest-visible contents of a qcow2 file via a block device
/dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for
partitions found within), then disconnect the device when done.
Access to bind qemu-nbd to an /dev/nbd device generally requires root
privileges, and may also require the execution of @code{modprobe nbd}
to enable the kernel NBD client module. @emph{CAUTION}: Do not use
this method to mount filesystems from an untrusted guest image - a
malicious guest may have prepared the image to attempt to trigger
kernel bugs in partition probing or file system mounting.
@example
qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2
qemu-nbd -d /dev/nbd0
@end example
Query a remote server to see details about what export(s) it is
serving on port 10809, and authenticating via PSK:
@example
qemu-nbd \
--object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \
--tls-creds tls0 -L -b remote.example.com
@end example
@c man end
@ignore
@setfilename qemu-nbd
@settitle QEMU Disk Network Block Device Server
@c man begin AUTHOR
Copyright (C) 2006 Anthony Liguori <anthony@codemonkey.ws>.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
@c man end
@c man begin SEEALSO
qemu(1), qemu-img(1)
@c man end
@end ignore