1QEMU Disk Network Block Device Server 2===================================== 3 4Synopsis 5-------- 6 7**qemu-nbd** [*OPTION*]... *filename* 8 9**qemu-nbd** -L [*OPTION*]... 10 11**qemu-nbd** -d *dev* 12 13Description 14----------- 15 16Export a QEMU disk image using the NBD protocol. 17 18Other 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 23Options 24------- 25 26.. program:: qemu-nbd 27 28*filename* is a disk image filename, or a set of block 29driver 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``). Safe for readers, but for now, consistency is not 140 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 199Examples 200-------- 201 202Start a server listening on port 10809 that exposes only the 203guest-visible contents of a qcow2 file, with no TLS encryption, and 204with the default export name (an empty string). The command is 205one-shot, and will block until the first successful client 206disconnects: 207 208:: 209 210 qemu-nbd -f qcow2 file.qcow2 211 212Start a long-running server listening with encryption on port 10810, 213and whitelist clients with a specific X.509 certificate to connect to 214a 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 226Serve a read-only copy of a guest image over a Unix socket with as 227many as 5 simultaneous readers, with a persistent process forked as a 228daemon: 229 230:: 231 232 qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \ 233 --read-only --format=qcow2 file.qcow2 234 235Expose the guest-visible contents of a qcow2 file via a block device 236/dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for 237partitions found within), then disconnect the device when done. 238Access to bind qemu-nbd to an /dev/nbd device generally requires root 239privileges, and may also require the execution of ``modprobe nbd`` 240to enable the kernel NBD client module. *CAUTION*: Do not use 241this method to mount filesystems from an untrusted guest image - a 242malicious guest may have prepared the image to attempt to trigger 243kernel 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 250Query a remote server to see details about what export(s) it is 251serving 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 259See also 260-------- 261 262:manpage:`qemu(1)`, :manpage:`qemu-img(1)` 263