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