1===================================== 2QEMU Disk Network Block Device Server 3===================================== 4 5Synopsis 6-------- 7 8**qemu-nbd** [*OPTION*]... *filename* 9 10**qemu-nbd** -L [*OPTION*]... 11 12**qemu-nbd** -d *dev* 13 14Description 15----------- 16 17Export a QEMU disk image using the NBD protocol. 18 19Other 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 24Options 25------- 26 27.. program:: qemu-nbd 28 29*filename* is a disk image filename, or a set of block 30driver 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 215Examples 216-------- 217 218Start a server listening on port 10809 that exposes only the 219guest-visible contents of a qcow2 file, with no TLS encryption, and 220with the default export name (an empty string). The command is 221one-shot, and will block until the first successful client 222disconnects: 223 224:: 225 226 qemu-nbd -f qcow2 file.qcow2 227 228Start a long-running server listening with encryption on port 10810, 229and whitelist clients with a specific X.509 certificate to connect to 230a 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 242Serve a read-only copy of a guest image over a Unix socket with as 243many as 5 simultaneous readers, with a persistent process forked as a 244daemon: 245 246:: 247 248 qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \ 249 --read-only --format=qcow2 file.qcow2 250 251Expose the guest-visible contents of a qcow2 file via a block device 252/dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for 253partitions found within), then disconnect the device when done. 254Access to bind ``qemu-nbd`` to a /dev/nbd device generally requires root 255privileges, and may also require the execution of ``modprobe nbd`` 256to enable the kernel NBD client module. *CAUTION*: Do not use 257this method to mount filesystems from an untrusted guest image - a 258malicious guest may have prepared the image to attempt to trigger 259kernel 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 266Query a remote server to see details about what export(s) it is 267serving 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 275See also 276-------- 277 278:manpage:`qemu(1)`, :manpage:`qemu-img(1)` 279