docs/tools/qemu-nbd.rst

   1 =====================================
   2 QEMU Disk Network Block Device Server
   3 =====================================
   4
   5 Synopsis
   6 --------
   7
   8 **qemu-nbd** [*OPTION*]... *filename*
   9
  10 **qemu-nbd** -L [*OPTION*]...
  11
  12 **qemu-nbd** -d *dev*
  13
  14 Description
  15 -----------
  16
  17 Export a QEMU disk image using the NBD protocol.
  18
  19 Other uses:
  20
  21 - Bind a /dev/nbdX block device to a QEMU server (on Linux).
  22 - As a client to query exports of a remote NBD server.
  23
  24 Options
  25 -------
  26
  27 .. program:: qemu-nbd
  28
  29 *filename* is a disk image filename, or a set of block
  30 driver options if ``--image-opts`` is specified.
  31
  32 *dev* is an NBD device.
  33
  34 .. option:: --object type,id=ID,...
  35
  36   Define a new instance of the *type* object class identified by *ID*.
  37   See the :manpage:`qemu(1)` manual page for full details of the properties
  38   supported. The common object types that it makes sense to define are the
  39   ``secret`` object, which is used to supply passwords and/or encryption
  40   keys, and the ``tls-creds`` object, which is used to supply TLS
  41   credentials for the ``qemu-nbd`` server or client.
  42
  43 .. option:: -p, --port=PORT
  44
  45   TCP port to listen on as a server, or connect to as a client
  46   (default ``10809``).
  47
  48 .. option:: -o, --offset=OFFSET
  49
  50   The offset into the image.
  51
  52 .. option:: -b, --bind=IFACE
  53
  54   The interface to bind to as a server, or connect to as a client
  55   (default ``0.0.0.0``).
  56
  57 .. option:: -k, --socket=PATH
  58
  59   Use a unix socket with path *PATH*.
  60
  61 .. option:: --image-opts
  62
  63   Treat *filename* as a set of image options, instead of a plain
  64   filename. If this flag is specified, the ``-f`` flag should
  65   not be used, instead the :option:`format=` option should be set.
  66
  67 .. option:: -f, --format=FMT
  68
  69   Force the use of the block driver for format *FMT* instead of
  70   auto-detecting.
  71
  72 .. option:: -r, --read-only
  73
  74   Export the disk as read-only.
  75
  76 .. option:: -A, --allocation-depth
  77
  78   Expose allocation depth information via the
  79   ``qemu:allocation-depth`` metadata context accessible through
  80   NBD_OPT_SET_META_CONTEXT.
  81
  82 .. option:: -B, --bitmap=NAME
  83
  84   If *filename* has a qcow2 persistent bitmap *NAME*, expose
  85   that bitmap via the ``qemu:dirty-bitmap:NAME`` metadata context
  86   accessible through NBD_OPT_SET_META_CONTEXT.
  87
  88 .. option:: -s, --snapshot
  89
  90   Use *filename* as an external snapshot, create a temporary
  91   file with ``backing_file=``\ *filename*, redirect the write to
  92   the temporary one.
  93
  94 .. option:: -l, --load-snapshot=SNAPSHOT_PARAM
  95
  96   Load an internal snapshot inside *filename* and export it
  97   as an read-only device, SNAPSHOT_PARAM format is
  98   ``snapshot.id=[ID],snapshot.name=[NAME]`` or ``[ID_OR_NAME]``
  99
 100 .. option:: --cache=CACHE
 101
 102   The cache mode to be used with the file. Valid values are:
 103   ``none``, ``writeback`` (the default), ``writethrough``,
 104   ``directsync`` and ``unsafe``. See the documentation of
 105   the emulator's ``-drive cache=...`` option for more info.
 106
 107 .. option:: -n, --nocache
 108
 109   Equivalent to :option:`--cache=none`.
 110
 111 .. option:: --aio=AIO
 112
 113   Set the asynchronous I/O mode between ``threads`` (the default),
 114   ``native`` (Linux only), and ``io_uring`` (Linux 5.1+).
 115
 116 .. option:: --discard=DISCARD
 117
 118   Control whether ``discard`` (also known as ``trim`` or ``unmap``)
 119   requests are ignored or passed to the filesystem. *DISCARD* is one of
 120   ``ignore`` (or ``off``), ``unmap`` (or ``on``).  The default is
 121   ``ignore``.
 122
 123 .. option:: --detect-zeroes=DETECT_ZEROES
 124
 125   Control the automatic conversion of plain zero writes by the OS to
 126   driver-specific optimized zero write commands.  *DETECT_ZEROES* is one of
 127   ``off``, ``on``, or ``unmap``.  ``unmap``
 128   converts a zero write to an unmap operation and can only be used if
 129   *DISCARD* is set to ``unmap``.  The default is ``off``.
 130
 131 .. option:: -c, --connect=DEV
 132
 133   Connect *filename* to NBD device *DEV* (Linux only).
 134
 135 .. option:: -d, --disconnect
 136
 137   Disconnect the device *DEV* (Linux only).
 138
 139 .. option:: -e, --shared=NUM
 140
 141   Allow up to *NUM* clients to share the device (default
 142   ``1``), 0 for unlimited. Safe for readers, but for now,
 143   consistency is not guaranteed between multiple writers.
 144
 145 .. option:: -t, --persistent
 146
 147   Don't exit on the last connection.
 148
 149 .. option:: -x, --export-name=NAME
 150
 151   Set the NBD volume export name (default of a zero-length string).
 152
 153 .. option:: -D, --description=DESCRIPTION
 154
 155   Set the NBD volume export description, as a human-readable
 156   string.
 157
 158 .. option:: -L, --list
 159
 160   Connect as a client and list all details about the exports exposed by
 161   a remote NBD server.  This enables list mode, and is incompatible
 162   with options that change behavior related to a specific export (such as
 163   :option:`--export-name`, :option:`--offset`, ...).
 164
 165 .. option:: --tls-creds=ID
 166
 167   Enable mandatory TLS encryption for the server by setting the ID
 168   of the TLS credentials object previously created with the --object
 169   option; or provide the credentials needed for connecting as a client
 170   in list mode.
 171
 172 .. option:: --tls-hostname=hostname
 173
 174   When validating an x509 certificate received over a TLS connection,
 175   the hostname that the NBD client used to connect will be checked
 176   against information in the server provided certificate. Sometimes
 177   it might be required to override the hostname used to perform this
 178   check. For example, if the NBD client is using a tunnel from localhost
 179   to connect to the remote server, the `--tls-hostname` option should
 180   be used to set the officially expected hostname of the remote NBD
 181   server. This can also be used if accessing NBD over a UNIX socket
 182   where there is no inherent hostname available. This is only permitted
 183   when acting as a NBD client with the `--list` option.
 184
 185 .. option:: --fork
 186
 187   Fork off the server process and exit the parent once the server is running.
 188
 189 .. option:: --pid-file=PATH
 190
 191   Store the server's process ID in the given file.
 192
 193 .. option:: --tls-authz=ID
 194
 195   Specify the ID of a qauthz object previously created with the
 196   :option:`--object` option. This will be used to authorize connecting users
 197   against their x509 distinguished name.
 198
 199 .. option:: -v, --verbose
 200
 201   Display extra debugging information.
 202
 203 .. option:: -h, --help
 204
 205   Display this help and exit.
 206
 207 .. option:: -V, --version
 208
 209   Display version information and exit.
 210
 211 .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
 212
 213   .. include:: ../qemu-option-trace.rst.inc
 214
 215 Examples
 216 --------
 217
 218 Start a server listening on port 10809 that exposes only the
 219 guest-visible contents of a qcow2 file, with no TLS encryption, and
 220 with the default export name (an empty string). The command is
 221 one-shot, and will block until the first successful client
 222 disconnects:
 223
 224 ::
 225
 226   qemu-nbd -f qcow2 file.qcow2
 227
 228 Start a long-running server listening with encryption on port 10810,
 229 and whitelist clients with a specific X.509 certificate to connect to
 230 a 1 megabyte subset of a raw file, using the export name 'subset':
 231
 232 ::
 233
 234   qemu-nbd \
 235     --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \
 236     --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\
 237               O=Example Org,,L=London,,ST=London,,C=GB' \
 238     --tls-creds tls0 --tls-authz auth0 \
 239     -t -x subset -p 10810 \
 240     --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw
 241
 242 Serve a read-only copy of a guest image over a Unix socket with as
 243 many as 5 simultaneous readers, with a persistent process forked as a
 244 daemon:
 245
 246 ::
 247
 248   qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \
 249     --read-only --format=qcow2 file.qcow2
 250
 251 Expose the guest-visible contents of a qcow2 file via a block device
 252 /dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for
 253 partitions found within), then disconnect the device when done.
 254 Access to bind ``qemu-nbd`` to a /dev/nbd device generally requires root
 255 privileges, and may also require the execution of ``modprobe nbd``
 256 to enable the kernel NBD client module.  *CAUTION*: Do not use
 257 this method to mount filesystems from an untrusted guest image - a
 258 malicious guest may have prepared the image to attempt to trigger
 259 kernel bugs in partition probing or file system mounting.
 260
 261 ::
 262
 263   qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2
 264   qemu-nbd -d /dev/nbd0
 265
 266 Query a remote server to see details about what export(s) it is
 267 serving on port 10809, and authenticating via PSK:
 268
 269 ::
 270
 271   qemu-nbd \
 272     --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \
 273     --tls-creds tls0 -L -b remote.example.com
 274
 275 See also
 276 --------
 277
 278 :manpage:`qemu(1)`, :manpage:`qemu-img(1)`