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:: --fork
 173
 174   Fork off the server process and exit the parent once the server is running.
 175
 176 .. option:: --pid-file=PATH
 177
 178   Store the server's process ID in the given file.
 179
 180 .. option:: --tls-authz=ID
 181
 182   Specify the ID of a qauthz object previously created with the
 183   :option:`--object` option. This will be used to authorize connecting users
 184   against their x509 distinguished name.
 185
 186 .. option:: -v, --verbose
 187
 188   Display extra debugging information.
 189
 190 .. option:: -h, --help
 191
 192   Display this help and exit.
 193
 194 .. option:: -V, --version
 195
 196   Display version information and exit.
 197
 198 .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
 199
 200   .. include:: ../qemu-option-trace.rst.inc
 201
 202 Examples
 203 --------
 204
 205 Start a server listening on port 10809 that exposes only the
 206 guest-visible contents of a qcow2 file, with no TLS encryption, and
 207 with the default export name (an empty string). The command is
 208 one-shot, and will block until the first successful client
 209 disconnects:
 210
 211 ::
 212
 213   qemu-nbd -f qcow2 file.qcow2
 214
 215 Start a long-running server listening with encryption on port 10810,
 216 and whitelist clients with a specific X.509 certificate to connect to
 217 a 1 megabyte subset of a raw file, using the export name 'subset':
 218
 219 ::
 220
 221   qemu-nbd \
 222     --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \
 223     --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\
 224               O=Example Org,,L=London,,ST=London,,C=GB' \
 225     --tls-creds tls0 --tls-authz auth0 \
 226     -t -x subset -p 10810 \
 227     --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw
 228
 229 Serve a read-only copy of a guest image over a Unix socket with as
 230 many as 5 simultaneous readers, with a persistent process forked as a
 231 daemon:
 232
 233 ::
 234
 235   qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \
 236     --read-only --format=qcow2 file.qcow2
 237
 238 Expose the guest-visible contents of a qcow2 file via a block device
 239 /dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for
 240 partitions found within), then disconnect the device when done.
 241 Access to bind ``qemu-nbd`` to a /dev/nbd device generally requires root
 242 privileges, and may also require the execution of ``modprobe nbd``
 243 to enable the kernel NBD client module.  *CAUTION*: Do not use
 244 this method to mount filesystems from an untrusted guest image - a
 245 malicious guest may have prepared the image to attempt to trigger
 246 kernel bugs in partition probing or file system mounting.
 247
 248 ::
 249
 250   qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2
 251   qemu-nbd -d /dev/nbd0
 252
 253 Query a remote server to see details about what export(s) it is
 254 serving on port 10809, and authenticating via PSK:
 255
 256 ::
 257
 258   qemu-nbd \
 259     --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \
 260     --tls-creds tls0 -L -b remote.example.com
 261
 262 See also
 263 --------
 264
 265 :manpage:`qemu(1)`, :manpage:`qemu-img(1)`