+=====================================
QEMU Disk Network Block Device Server
=====================================
.. program:: qemu-nbd
*filename* is a disk image filename, or a set of block
-driver options if ``--image-opts`` is specified.
+driver options if :option:`--image-opts` is specified.
*dev* is an NBD device.
-.. option:: --object type,id=ID,...props...
+.. option:: --object type,id=ID,...
Define a new instance of the *type* object class identified by *ID*.
See the :manpage:`qemu(1)` manual page for full details of the properties
supported. The common object types that it makes sense to define are the
``secret`` object, which is used to supply passwords and/or encryption
keys, and the ``tls-creds`` object, which is used to supply TLS
- credentials for the qemu-nbd server or client.
+ credentials for the ``qemu-nbd`` server or client.
.. option:: -p, --port=PORT
.. option:: --cache=CACHE
- The cache mode to be used with the file. See the documentation of
- the emulator's ``-drive cache=...`` option for allowed values.
+ The cache mode to be used with the file. Valid values are:
+ ``none``, ``writeback`` (the default), ``writethrough``,
+ ``directsync`` and ``unsafe``. See the documentation of
+ the emulator's ``-drive cache=...`` option for more info.
.. option:: -n, --nocache
.. option:: -e, --shared=NUM
Allow up to *NUM* clients to share the device (default
- ``1``). Safe for readers, but for now, consistency is not
- guaranteed between multiple writers.
+ ``1``), 0 for unlimited.
.. option:: -t, --persistent
.. option:: --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.
+ of the TLS credentials object previously created with the
+ :option:`--object` option; or provide the credentials needed for
+ connecting as a client in list mode.
+
+.. option:: --tls-hostname=hostname
+
+ When validating an x509 certificate received over a TLS connection,
+ the hostname that the NBD client used to connect will be checked
+ against information in the server provided certificate. Sometimes
+ it might be required to override the hostname used to perform this
+ check. For example, if the NBD client is using a tunnel from localhost
+ to connect to the remote server, the :option:`--tls-hostname` option should
+ be used to set the officially expected hostname of the remote NBD
+ server. This can also be used if accessing NBD over a UNIX socket
+ where there is no inherent hostname available. This is only permitted
+ when acting as a NBD client with the :option:`--list` option.
.. option:: --fork
.. option:: -v, --verbose
- Display extra debugging information.
+ Display extra debugging information. This option also keeps the original
+ *STDERR* stream open if the ``qemu-nbd`` process is daemonized due to
+ other options like :option:`--fork` or :option:`-c`.
.. option:: -h, --help
qemu-nbd -f qcow2 file.qcow2
Start a long-running server listening with encryption on port 10810,
-and whitelist clients with a specific X.509 certificate to connect to
+and allow clients with a specific X.509 certificate to connect to
a 1 megabyte subset of a raw file, using the export name 'subset':
::
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
+Access to bind ``qemu-nbd`` to a /dev/nbd device generally requires root
privileges, and may also require the execution of ``modprobe nbd``
to enable the kernel NBD client module. *CAUTION*: Do not use
this method to mount filesystems from an untrusted guest image - a
projects / mirror_qemu.git / blobdiff