qemu-nbd: Enhance man page

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).

@end itemize

@c man end

@c man begin OPTIONS

@var{filename} is a disk image filename, or a set of block

driver options if @var{--image-opts} is specified.

driver options if @option{--image-opts} is specified.

@var{dev} is an NBD device.

keys, and the @code{tls-creds} object, which is used to supply TLS

credentials for the qemu-nbd server.

@item -p, --port=@var{port}

The TCP port to listen on (default @samp{10809})

The TCP port to listen on (default @samp{10809}).

@item -o, --offset=@var{offset}

The offset into the image

The offset into the image.

@item -b, --bind=@var{iface}

The interface to bind to (default @samp{0.0.0.0})

The interface to bind to (default @samp{0.0.0.0}).

@item -k, --socket=@var{path}

Use a unix socket with path @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

auto-detecting.

@item -r, --read-only

Export the disk as read-only

Export the disk as read-only.

@item -P, --partition=@var{num}

Only expose 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

@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

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

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}

Connect @var{filename} to NBD device @var{dev} (Linux only).

@item -d, --disconnect

Disconnect the device @var{dev}

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})

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

Don't exit on the last connection.

@item -x, --export-name=@var{name}

Set the NBD volume export name. This switches the server to use

the new style NBD protocol negotiation

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. Requires the use of @option{-x}

string.

@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

@item --fork

Fork off the server process and exit the parent once the server is running.

@item -v, --verbose

Display extra debugging information

Display extra debugging information.

@item -h, --help

Display this help and exit

Display this help and exit.

@item -V, --version

Display version information and exit

Display version information and exit.

@item -T, --trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]

@findex --trace

@include qemu-option-trace.texi

@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

@c man end

@ignore

@setfilename qemu-nbd