qemu-nbd.rst (8400B)
1 ===================================== 2 QEMU Disk Network Block Device Server 3 ===================================== 4 5 Synopsis 6 -------- 7 8 **qemu-nbd** [*OPTION*]... *filename* 9 10 **qemu-nbd** -L [*OPTION*]... 11 12 **qemu-nbd** -d *dev* 13 14 Description 15 ----------- 16 17 Export a QEMU disk image using the NBD protocol. 18 19 Other 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 24 Options 25 ------- 26 27 .. program:: qemu-nbd 28 29 *filename* is a disk image filename, or a set of block 30 driver 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. 201 202 .. option:: -h, --help 203 204 Display this help and exit. 205 206 .. option:: -V, --version 207 208 Display version information and exit. 209 210 .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] 211 212 .. include:: ../qemu-option-trace.rst.inc 213 214 Examples 215 -------- 216 217 Start a server listening on port 10809 that exposes only the 218 guest-visible contents of a qcow2 file, with no TLS encryption, and 219 with the default export name (an empty string). The command is 220 one-shot, and will block until the first successful client 221 disconnects: 222 223 :: 224 225 qemu-nbd -f qcow2 file.qcow2 226 227 Start a long-running server listening with encryption on port 10810, 228 and allow clients with a specific X.509 certificate to connect to 229 a 1 megabyte subset of a raw file, using the export name 'subset': 230 231 :: 232 233 qemu-nbd \ 234 --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \ 235 --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\ 236 O=Example Org,,L=London,,ST=London,,C=GB' \ 237 --tls-creds tls0 --tls-authz auth0 \ 238 -t -x subset -p 10810 \ 239 --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw 240 241 Serve a read-only copy of a guest image over a Unix socket with as 242 many as 5 simultaneous readers, with a persistent process forked as a 243 daemon: 244 245 :: 246 247 qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \ 248 --read-only --format=qcow2 file.qcow2 249 250 Expose the guest-visible contents of a qcow2 file via a block device 251 /dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for 252 partitions found within), then disconnect the device when done. 253 Access to bind ``qemu-nbd`` to a /dev/nbd device generally requires root 254 privileges, and may also require the execution of ``modprobe nbd`` 255 to enable the kernel NBD client module. *CAUTION*: Do not use 256 this method to mount filesystems from an untrusted guest image - a 257 malicious guest may have prepared the image to attempt to trigger 258 kernel bugs in partition probing or file system mounting. 259 260 :: 261 262 qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2 263 qemu-nbd -d /dev/nbd0 264 265 Query a remote server to see details about what export(s) it is 266 serving on port 10809, and authenticating via PSK: 267 268 :: 269 270 qemu-nbd \ 271 --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \ 272 --tls-creds tls0 -L -b remote.example.com 273 274 See also 275 -------- 276 277 :manpage:`qemu(1)`, :manpage:`qemu-img(1)`