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:: -B, --bitmap=NAME 76 77 If *filename* has a qcow2 persistent bitmap *NAME*, expose 78 that bitmap via the ``qemu:dirty-bitmap:NAME`` context 79 accessible through NBD_OPT_SET_META_CONTEXT. 80 81.. option:: -s, --snapshot 82 83 Use *filename* as an external snapshot, create a temporary 84 file with ``backing_file=``\ *filename*, redirect the write to 85 the temporary one. 86 87.. option:: -l, --load-snapshot=SNAPSHOT_PARAM 88 89 Load an internal snapshot inside *filename* and export it 90 as an read-only device, SNAPSHOT_PARAM format is 91 ``snapshot.id=[ID],snapshot.name=[NAME]`` or ``[ID_OR_NAME]`` 92 93.. option:: --cache=CACHE 94 95 The cache mode to be used with the file. See the documentation of 96 the emulator's ``-drive cache=...`` option for allowed values. 97 98.. option:: -n, --nocache 99 100 Equivalent to :option:`--cache=none`. 101 102.. option:: --aio=AIO 103 104 Set the asynchronous I/O mode between ``threads`` (the default), 105 ``native`` (Linux only), and ``io_uring`` (Linux 5.1+). 106 107.. option:: --discard=DISCARD 108 109 Control whether ``discard`` (also known as ``trim`` or ``unmap``) 110 requests are ignored or passed to the filesystem. *DISCARD* is one of 111 ``ignore`` (or ``off``), ``unmap`` (or ``on``). The default is 112 ``ignore``. 113 114.. option:: --detect-zeroes=DETECT_ZEROES 115 116 Control the automatic conversion of plain zero writes by the OS to 117 driver-specific optimized zero write commands. *DETECT_ZEROES* is one of 118 ``off``, ``on``, or ``unmap``. ``unmap`` 119 converts a zero write to an unmap operation and can only be used if 120 *DISCARD* is set to ``unmap``. The default is ``off``. 121 122.. option:: -c, --connect=DEV 123 124 Connect *filename* to NBD device *DEV* (Linux only). 125 126.. option:: -d, --disconnect 127 128 Disconnect the device *DEV* (Linux only). 129 130.. option:: -e, --shared=NUM 131 132 Allow up to *NUM* clients to share the device (default 133 ``1``). Safe for readers, but for now, consistency is not 134 guaranteed between multiple writers. 135 136.. option:: -t, --persistent 137 138 Don't exit on the last connection. 139 140.. option:: -x, --export-name=NAME 141 142 Set the NBD volume export name (default of a zero-length string). 143 144.. option:: -D, --description=DESCRIPTION 145 146 Set the NBD volume export description, as a human-readable 147 string. 148 149.. option:: -L, --list 150 151 Connect as a client and list all details about the exports exposed by 152 a remote NBD server. This enables list mode, and is incompatible 153 with options that change behavior related to a specific export (such as 154 :option:`--export-name`, :option:`--offset`, ...). 155 156.. option:: --tls-creds=ID 157 158 Enable mandatory TLS encryption for the server by setting the ID 159 of the TLS credentials object previously created with the --object 160 option; or provide the credentials needed for connecting as a client 161 in list mode. 162 163.. option:: --fork 164 165 Fork off the server process and exit the parent once the server is running. 166 167.. option:: --pid-file=PATH 168 169 Store the server's process ID in the given file. 170 171.. option:: --tls-authz=ID 172 173 Specify the ID of a qauthz object previously created with the 174 :option:`--object` option. This will be used to authorize connecting users 175 against their x509 distinguished name. 176 177.. option:: -v, --verbose 178 179 Display extra debugging information. 180 181.. option:: -h, --help 182 183 Display this help and exit. 184 185.. option:: -V, --version 186 187 Display version information and exit. 188 189.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] 190 191 .. include:: ../qemu-option-trace.rst.inc 192 193Examples 194-------- 195 196Start a server listening on port 10809 that exposes only the 197guest-visible contents of a qcow2 file, with no TLS encryption, and 198with the default export name (an empty string). The command is 199one-shot, and will block until the first successful client 200disconnects: 201 202:: 203 204 qemu-nbd -f qcow2 file.qcow2 205 206Start a long-running server listening with encryption on port 10810, 207and whitelist clients with a specific X.509 certificate to connect to 208a 1 megabyte subset of a raw file, using the export name 'subset': 209 210:: 211 212 qemu-nbd \ 213 --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \ 214 --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\ 215 O=Example Org,,L=London,,ST=London,,C=GB' \ 216 --tls-creds tls0 --tls-authz auth0 \ 217 -t -x subset -p 10810 \ 218 --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw 219 220Serve a read-only copy of a guest image over a Unix socket with as 221many as 5 simultaneous readers, with a persistent process forked as a 222daemon: 223 224:: 225 226 qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \ 227 --read-only --format=qcow2 file.qcow2 228 229Expose the guest-visible contents of a qcow2 file via a block device 230/dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for 231partitions found within), then disconnect the device when done. 232Access to bind qemu-nbd to an /dev/nbd device generally requires root 233privileges, and may also require the execution of ``modprobe nbd`` 234to enable the kernel NBD client module. *CAUTION*: Do not use 235this method to mount filesystems from an untrusted guest image - a 236malicious guest may have prepared the image to attempt to trigger 237kernel bugs in partition probing or file system mounting. 238 239:: 240 241 qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2 242 qemu-nbd -d /dev/nbd0 243 244Query a remote server to see details about what export(s) it is 245serving on port 10809, and authenticating via PSK: 246 247:: 248 249 qemu-nbd \ 250 --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \ 251 --tls-creds tls0 -L -b remote.example.com 252 253See also 254-------- 255 256:manpage:`qemu(1)`, :manpage:`qemu-img(1)` 257