1 =====================================
2 QEMU Disk Network Block Device Server
3 =====================================
8 **qemu-nbd** [*OPTION*]... *filename*
10 **qemu-nbd** -L [*OPTION*]...
17 Export a QEMU disk image using the NBD protocol.
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.
29 *filename* is a disk image filename, or a set of block
30 driver options if :option:`--image-opts` is specified.
32 *dev* is an NBD device.
34 .. option:: --object type,id=ID,...
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.
43 .. option:: -p, --port=PORT
45 TCP port to listen on as a server, or connect to as a client
48 .. option:: -o, --offset=OFFSET
50 The offset into the image.
52 .. option:: -b, --bind=IFACE
54 The interface to bind to as a server, or connect to as a client
55 (default ``0.0.0.0``).
57 .. option:: -k, --socket=PATH
59 Use a unix socket with path *PATH*.
61 .. option:: --image-opts
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.
67 .. option:: -f, --format=FMT
69 Force the use of the block driver for format *FMT* instead of
72 .. option:: -r, --read-only
74 Export the disk as read-only.
76 .. option:: -A, --allocation-depth
78 Expose allocation depth information via the
79 ``qemu:allocation-depth`` metadata context accessible through
80 NBD_OPT_SET_META_CONTEXT.
82 .. option:: -B, --bitmap=NAME
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.
88 .. option:: -s, --snapshot
90 Use *filename* as an external snapshot, create a temporary
91 file with ``backing_file=``\ *filename*, redirect the write to
94 .. option:: -l, --load-snapshot=SNAPSHOT_PARAM
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]``
100 .. option:: --cache=CACHE
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.
107 .. option:: -n, --nocache
109 Equivalent to :option:`--cache=none`.
111 .. option:: --aio=AIO
113 Set the asynchronous I/O mode between ``threads`` (the default),
114 ``native`` (Linux only), and ``io_uring`` (Linux 5.1+).
116 .. option:: --discard=DISCARD
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
123 .. option:: --detect-zeroes=DETECT_ZEROES
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``.
131 .. option:: -c, --connect=DEV
133 Connect *filename* to NBD device *DEV* (Linux only).
135 .. option:: -d, --disconnect
137 Disconnect the device *DEV* (Linux only).
139 .. option:: -e, --shared=NUM
141 Allow up to *NUM* clients to share the device (default
142 ``1``), 0 for unlimited. Safe for readers, but for now,
143 consistency is not guaranteed between multiple writers.
145 .. option:: -t, --persistent
147 Don't exit on the last connection.
149 .. option:: -x, --export-name=NAME
151 Set the NBD volume export name (default of a zero-length string).
153 .. option:: -D, --description=DESCRIPTION
155 Set the NBD volume export description, as a human-readable
158 .. option:: -L, --list
160 Connect as a client and list all details about the exports exposed by
161 a remote NBD server. This enables list mode, and is incompatible
162 with options that change behavior related to a specific export (such as
163 :option:`--export-name`, :option:`--offset`, ...).
165 .. option:: --tls-creds=ID
167 Enable mandatory TLS encryption for the server by setting the ID
168 of the TLS credentials object previously created with the
169 :option:`--object` option; or provide the credentials needed for
170 connecting as a client in list mode.
172 .. option:: --tls-hostname=hostname
174 When validating an x509 certificate received over a TLS connection,
175 the hostname that the NBD client used to connect will be checked
176 against information in the server provided certificate. Sometimes
177 it might be required to override the hostname used to perform this
178 check. For example, if the NBD client is using a tunnel from localhost
179 to connect to the remote server, the :option:`--tls-hostname` option should
180 be used to set the officially expected hostname of the remote NBD
181 server. This can also be used if accessing NBD over a UNIX socket
182 where there is no inherent hostname available. This is only permitted
183 when acting as a NBD client with the :option:`--list` option.
187 Fork off the server process and exit the parent once the server is running.
189 .. option:: --pid-file=PATH
191 Store the server's process ID in the given file.
193 .. option:: --tls-authz=ID
195 Specify the ID of a qauthz object previously created with the
196 :option:`--object` option. This will be used to authorize connecting users
197 against their x509 distinguished name.
199 .. option:: -v, --verbose
201 Display extra debugging information.
203 .. option:: -h, --help
205 Display this help and exit.
207 .. option:: -V, --version
209 Display version information and exit.
211 .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
213 .. include:: ../qemu-option-trace.rst.inc
218 Start a server listening on port 10809 that exposes only the
219 guest-visible contents of a qcow2 file, with no TLS encryption, and
220 with the default export name (an empty string). The command is
221 one-shot, and will block until the first successful client
226 qemu-nbd -f qcow2 file.qcow2
228 Start a long-running server listening with encryption on port 10810,
229 and whitelist clients with a specific X.509 certificate to connect to
230 a 1 megabyte subset of a raw file, using the export name 'subset':
235 --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \
236 --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\
237 O=Example Org,,L=London,,ST=London,,C=GB' \
238 --tls-creds tls0 --tls-authz auth0 \
239 -t -x subset -p 10810 \
240 --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw
242 Serve a read-only copy of a guest image over a Unix socket with as
243 many as 5 simultaneous readers, with a persistent process forked as a
248 qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \
249 --read-only --format=qcow2 file.qcow2
251 Expose the guest-visible contents of a qcow2 file via a block device
252 /dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for
253 partitions found within), then disconnect the device when done.
254 Access to bind ``qemu-nbd`` to a /dev/nbd device generally requires root
255 privileges, and may also require the execution of ``modprobe nbd``
256 to enable the kernel NBD client module. *CAUTION*: Do not use
257 this method to mount filesystems from an untrusted guest image - a
258 malicious guest may have prepared the image to attempt to trigger
259 kernel bugs in partition probing or file system mounting.
263 qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2
264 qemu-nbd -d /dev/nbd0
266 Query a remote server to see details about what export(s) it is
267 serving on port 10809, and authenticating via PSK:
272 --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \
273 --tls-creds tls0 -L -b remote.example.com
278 :manpage:`qemu(1)`, :manpage:`qemu-img(1)`