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