docs/tools/qemu-nbd.rst

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