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 :option:`--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. 143 144.. option:: -t, --persistent 145 146 Don't exit on the last connection. 147 148.. option:: -x, --export-name=NAME 149 150 Set the NBD volume export name (default of a zero-length string). 151 152.. option:: -D, --description=DESCRIPTION 153 154 Set the NBD volume export description, as a human-readable 155 string. 156 157.. option:: -L, --list 158 159 Connect as a client and list all details about the exports exposed by 160 a remote NBD server. This enables list mode, and is incompatible 161 with options that change behavior related to a specific export (such as 162 :option:`--export-name`, :option:`--offset`, ...). 163 164.. option:: --tls-creds=ID 165 166 Enable mandatory TLS encryption for the server by setting the ID 167 of the TLS credentials object previously created with the 168 :option:`--object` option; or provide the credentials needed for 169 connecting as a client in list mode. 170 171.. option:: --tls-hostname=hostname 172 173 When validating an x509 certificate received over a TLS connection, 174 the hostname that the NBD client used to connect will be checked 175 against information in the server provided certificate. Sometimes 176 it might be required to override the hostname used to perform this 177 check. For example, if the NBD client is using a tunnel from localhost 178 to connect to the remote server, the :option:`--tls-hostname` option should 179 be used to set the officially expected hostname of the remote NBD 180 server. This can also be used if accessing NBD over a UNIX socket 181 where there is no inherent hostname available. This is only permitted 182 when acting as a NBD client with the :option:`--list` option. 183 184.. option:: --fork 185 186 Fork off the server process and exit the parent once the server is running. 187 188.. option:: --pid-file=PATH 189 190 Store the server's process ID in the given file. 191 192.. option:: --tls-authz=ID 193 194 Specify the ID of a qauthz object previously created with the 195 :option:`--object` option. This will be used to authorize connecting users 196 against their x509 distinguished name. 197 198.. option:: -v, --verbose 199 200 Display extra debugging information. This option also keeps the original 201 *STDERR* stream open if the ``qemu-nbd`` process is daemonized due to 202 other options like :option:`--fork` or :option:`-c`. 203 204.. option:: -h, --help 205 206 Display this help and exit. 207 208.. option:: -V, --version 209 210 Display version information and exit. 211 212.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] 213 214 .. include:: ../qemu-option-trace.rst.inc 215 216Examples 217-------- 218 219Start a server listening on port 10809 that exposes only the 220guest-visible contents of a qcow2 file, with no TLS encryption, and 221with the default export name (an empty string). The command is 222one-shot, and will block until the first successful client 223disconnects: 224 225:: 226 227 qemu-nbd -f qcow2 file.qcow2 228 229Start a long-running server listening with encryption on port 10810, 230and allow clients with a specific X.509 certificate to connect to 231a 1 megabyte subset of a raw file, using the export name 'subset': 232 233:: 234 235 qemu-nbd \ 236 --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \ 237 --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\ 238 O=Example Org,,L=London,,ST=London,,C=GB' \ 239 --tls-creds tls0 --tls-authz auth0 \ 240 -t -x subset -p 10810 \ 241 --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw 242 243Serve a read-only copy of a guest image over a Unix socket with as 244many as 5 simultaneous readers, with a persistent process forked as a 245daemon: 246 247:: 248 249 qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \ 250 --read-only --format=qcow2 file.qcow2 251 252Expose the guest-visible contents of a qcow2 file via a block device 253/dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for 254partitions found within), then disconnect the device when done. 255Access to bind ``qemu-nbd`` to a /dev/nbd device generally requires root 256privileges, and may also require the execution of ``modprobe nbd`` 257to enable the kernel NBD client module. *CAUTION*: Do not use 258this method to mount filesystems from an untrusted guest image - a 259malicious guest may have prepared the image to attempt to trigger 260kernel bugs in partition probing or file system mounting. 261 262:: 263 264 qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2 265 qemu-nbd -d /dev/nbd0 266 267Query a remote server to see details about what export(s) it is 268serving on port 10809, and authenticating via PSK: 269 270:: 271 272 qemu-nbd \ 273 --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \ 274 --tls-creds tls0 -L -b remote.example.com 275 276See also 277-------- 278 279:manpage:`qemu(1)`, :manpage:`qemu-img(1)` 280