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 :option:`--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.
 143
 144 .. option:: -t, --persistent
 145
 146   Don't exit on the last connection.
 147
 148 .. option:: -x, --export-name=NAME
 149
 150   Set the NBD volume export name (default of a zero-length string).
 151
 152 .. option:: -D, --description=DESCRIPTION
 153
 154   Set the NBD volume export description, as a human-readable
 155   string.
 156
 157 .. option:: -L, --list
 158
 159   Connect as a client and list all details about the exports exposed by
 160   a remote NBD server.  This enables list mode, and is incompatible
 161   with options that change behavior related to a specific export (such as
 162   :option:`--export-name`, :option:`--offset`, ...).
 163
 164 .. option:: --tls-creds=ID
 165
 166   Enable mandatory TLS encryption for the server by setting the ID
 167   of the TLS credentials object previously created with the
 168   :option:`--object` option; or provide the credentials needed for
 169   connecting as a client in list mode.
 170
 171 .. option:: --tls-hostname=hostname
 172
 173   When validating an x509 certificate received over a TLS connection,
 174   the hostname that the NBD client used to connect will be checked
 175   against information in the server provided certificate. Sometimes
 176   it might be required to override the hostname used to perform this
 177   check. For example, if the NBD client is using a tunnel from localhost
 178   to connect to the remote server, the :option:`--tls-hostname` option should
 179   be used to set the officially expected hostname of the remote NBD
 180   server. This can also be used if accessing NBD over a UNIX socket
 181   where there is no inherent hostname available. This is only permitted
 182   when acting as a NBD client with the :option:`--list` option.
 183
 184 .. option:: --fork
 185
 186   Fork off the server process and exit the parent once the server is running.
 187
 188 .. option:: --pid-file=PATH
 189
 190   Store the server's process ID in the given file.
 191
 192 .. option:: --tls-authz=ID
 193
 194   Specify the ID of a qauthz object previously created with the
 195   :option:`--object` option. This will be used to authorize connecting users
 196   against their x509 distinguished name.
 197
 198 .. option:: -v, --verbose
 199
 200   Display extra debugging information.
 201
 202 .. option:: -h, --help
 203
 204   Display this help and exit.
 205
 206 .. option:: -V, --version
 207
 208   Display version information and exit.
 209
 210 .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
 211
 212   .. include:: ../qemu-option-trace.rst.inc
 213
 214 Examples
 215 --------
 216
 217 Start a server listening on port 10809 that exposes only the
 218 guest-visible contents of a qcow2 file, with no TLS encryption, and
 219 with the default export name (an empty string). The command is
 220 one-shot, and will block until the first successful client
 221 disconnects:
 222
 223 ::
 224
 225   qemu-nbd -f qcow2 file.qcow2
 226
 227 Start a long-running server listening with encryption on port 10810,
 228 and whitelist clients with a specific X.509 certificate to connect to
 229 a 1 megabyte subset of a raw file, using the export name 'subset':
 230
 231 ::
 232
 233   qemu-nbd \
 234     --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \
 235     --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\
 236               O=Example Org,,L=London,,ST=London,,C=GB' \
 237     --tls-creds tls0 --tls-authz auth0 \
 238     -t -x subset -p 10810 \
 239     --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw
 240
 241 Serve a read-only copy of a guest image over a Unix socket with as
 242 many as 5 simultaneous readers, with a persistent process forked as a
 243 daemon:
 244
 245 ::
 246
 247   qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \
 248     --read-only --format=qcow2 file.qcow2
 249
 250 Expose the guest-visible contents of a qcow2 file via a block device
 251 /dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for
 252 partitions found within), then disconnect the device when done.
 253 Access to bind ``qemu-nbd`` to a /dev/nbd device generally requires root
 254 privileges, and may also require the execution of ``modprobe nbd``
 255 to enable the kernel NBD client module.  *CAUTION*: Do not use
 256 this method to mount filesystems from an untrusted guest image - a
 257 malicious guest may have prepared the image to attempt to trigger
 258 kernel bugs in partition probing or file system mounting.
 259
 260 ::
 261
 262   qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2
 263   qemu-nbd -d /dev/nbd0
 264
 265 Query a remote server to see details about what export(s) it is
 266 serving on port 10809, and authenticating via PSK:
 267
 268 ::
 269
 270   qemu-nbd \
 271     --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \
 272     --tls-creds tls0 -L -b remote.example.com
 273
 274 See also
 275 --------
 276
 277 :manpage:`qemu(1)`, :manpage:`qemu-img(1)`