1QEMU-NBD(8)                          QEMU                          QEMU-NBD(8)
2
3
4

NAME

6       qemu-nbd - QEMU Disk Network Block Device Server
7

SYNOPSIS

9       qemu-nbd [OPTION]... filename
10
11       qemu-nbd -L [OPTION]...
12
13       qemu-nbd -d dev
14

DESCRIPTION

16       Export a QEMU disk image using the NBD protocol.
17
18       Other uses:
19
20       • Bind a /dev/nbdX block device to a QEMU server (on Linux).
21
22       • As a client to query exports of a remote NBD server.
23

OPTIONS

25       filename  is a disk image filename, or a set of block driver options if
26       --image-opts is specified.
27
28       dev is an NBD device.
29
30       --object type,id=ID,...
31              Define a new instance of the type object class identified by ID.
32              See  the  qemu(1) manual page for full details of the properties
33              supported. The common object types that it makes sense to define
34              are  the secret object, which is used to supply passwords and/or
35              encryption keys, and the tls-creds object, which is used to sup‐
36              ply TLS credentials for the qemu-nbd server or client.
37
38       -p, --port=PORT
39              TCP  port  to  listen  on as a server, or connect to as a client
40              (default 10809).
41
42       -o, --offset=OFFSET
43              The offset into the image.
44
45       -b, --bind=IFACE
46              The interface to bind to as a server, or connect to as a  client
47              (default 0.0.0.0).
48
49       -k, --socket=PATH
50              Use a unix socket with path PATH.
51
52       --image-opts
53              Treat  filename  as  a  set of image options, instead of a plain
54              filename. If this flag is specified, the -f flag should  not  be
55              used, instead the format= option should be set.
56
57       -f, --format=FMT
58              Force  the  use  of  the  block driver for format FMT instead of
59              auto-detecting.
60
61       -r, --read-only
62              Export the disk as read-only.
63
64       -A, --allocation-depth
65              Expose  allocation  depth  information  via   the   qemu:alloca‐
66              tion-depth      metadata      context     accessible     through
67              NBD_OPT_SET_META_CONTEXT.
68
69       -B, --bitmap=NAME
70              If filename has a qcow2 persistent bitmap NAME, expose that bit‐
71              map  via  the qemu:dirty-bitmap:NAME metadata context accessible
72              through NBD_OPT_SET_META_CONTEXT.
73
74       -s, --snapshot
75              Use filename as an external snapshot, create  a  temporary  file
76              with  backing_file=filename, redirect the write to the temporary
77              one.
78
79       -l, --load-snapshot=SNAPSHOT_PARAM
80              Load an internal snapshot inside filename and export  it  as  an
81              read-only     device,    SNAPSHOT_PARAM    format    is    snap‐
82              shot.id=[ID],snapshot.name=[NAME] or [ID_OR_NAME]
83
84       --cache=CACHE
85              The cache mode to be used with the file. Valid values are: none,
86              writeback  (the  default),  writethrough, directsync and unsafe.
87              See the documentation of the emulator's -drive cache=...  option
88              for more info.
89
90       -n, --nocache
91              Equivalent to --cache=none.
92
93       --aio=AIO
94              Set the asynchronous I/O mode between threads (the default), na‐
95              tive (Linux only), and io_uring (Linux 5.1+).
96
97       --discard=DISCARD
98              Control whether discard (also known as trim or  unmap)  requests
99              are  ignored  or passed to the filesystem. DISCARD is one of ig‐
100              nore (or off), unmap (or on).  The default is ignore.
101
102       --detect-zeroes=DETECT_ZEROES
103              Control the automatic conversion of plain zero writes by the  OS
104              to driver-specific optimized zero write commands.  DETECT_ZEROES
105              is one of off, on, or unmap.  unmap converts a zero write to  an
106              unmap operation and can only be used if DISCARD is set to unmap.
107              The default is off.
108
109       -c, --connect=DEV
110              Connect filename to NBD device DEV (Linux only).
111
112       -d, --disconnect
113              Disconnect the device DEV (Linux only).
114
115       -e, --shared=NUM
116              Allow up to NUM clients to share the device (default 1),  0  for
117              unlimited.
118
119       -t, --persistent
120              Don't exit on the last connection.
121
122       -x, --export-name=NAME
123              Set  the  NBD  volume  export  name  (default  of  a zero-length
124              string).
125
126       -D, --description=DESCRIPTION
127              Set the NBD  volume  export  description,  as  a  human-readable
128              string.
129
130       -L, --list
131              Connect  as  a client and list all details about the exports ex‐
132              posed by a remote NBD server.  This enables list  mode,  and  is
133              incompatible with options that change behavior related to a spe‐
134              cific export (such as --export-name, --offset, ...).
135
136       --tls-creds=ID
137              Enable mandatory TLS encryption for the server by setting the ID
138              of  the  TLS  credentials  object  previously  created  with the
139              --object option; or provide the credentials needed for  connect‐
140              ing as a client in list mode.
141
142       --tls-hostname=hostname
143              When  validating an x509 certificate received over a TLS connec‐
144              tion, the hostname that the NBD client used to connect  will  be
145              checked  against information in the server provided certificate.
146              Sometimes it might be required to override the hostname used  to
147              perform  this  check.  For example, if the NBD client is using a
148              tunnel from localhost to  connect  to  the  remote  server,  the
149              --tls-hostname  option  should be used to set the officially ex‐
150              pected hostname of the remote NBD server. This can also be  used
151              if  accessing  NBD over a UNIX socket where there is no inherent
152              hostname available. This is only permitted when acting as a  NBD
153              client with the --list option.
154
155       --fork Fork  off the server process and exit the parent once the server
156              is running.
157
158       --pid-file=PATH
159              Store the server's process ID in the given file.
160
161       --tls-authz=ID
162              Specify the ID of a qauthz object previously  created  with  the
163              --object option. This will be used to authorize connecting users
164              against their x509 distinguished name.
165
166       -v, --verbose
167              Display extra debugging information.
168
169       -h, --help
170              Display this help and exit.
171
172       -V, --version
173              Display version information and exit.
174
175       -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
176              Specify tracing options.
177
178              [enable=]PATTERN
179                 Immediately enable events matching PATTERN (either event name
180                 or  a  globbing  pattern).   This option is only available if
181                 QEMU has been compiled with the simple, log or ftrace tracing
182                 backend.  To specify multiple events or patterns, specify the
183                 -trace option multiple times.
184
185                 Use -trace help to print a list of names of trace points.
186
187              events=FILE
188                 Immediately enable events listed in FILE.  The file must con‐
189                 tain  one event name (as listed in the trace-events-all file)
190                 per line; globbing patterns are accepted too.  This option is
191                 only available if QEMU has been compiled with the simple, log
192                 or ftrace tracing backend.
193
194              file=FILE
195                 Log output traces to FILE.  This option is only available  if
196                 QEMU has been compiled with the simple tracing backend.
197

EXAMPLES

199       Start a server listening on port 10809 that exposes only the guest-vis‐
200       ible contents of a qcow2 file, with no TLS encryption, and with the de‐
201       fault  export name (an empty string). The command is one-shot, and will
202       block until the first successful client disconnects:
203
204          qemu-nbd -f qcow2 file.qcow2
205
206       Start a long-running server listening with encryption  on  port  10810,
207       and  allow  clients with a specific X.509 certificate to connect to a 1
208       megabyte subset of a raw file, using the export name 'subset':
209
210          qemu-nbd \
211            --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \
212            --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\
213                      O=Example Org,,L=London,,ST=London,,C=GB' \
214            --tls-creds tls0 --tls-authz auth0 \
215            -t -x subset -p 10810 \
216            --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw
217
218       Serve a read-only copy of a guest image over a Unix socket with as many
219       as  5  simultaneous readers, with a persistent process forked as a dae‐
220       mon:
221
222          qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \
223            --read-only --format=qcow2 file.qcow2
224
225       Expose the guest-visible contents of a qcow2 file via  a  block  device
226       /dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for partitions
227       found within), then disconnect the device when done.   Access  to  bind
228       qemu-nbd  to  a /dev/nbd device generally requires root privileges, and
229       may also require the execution of modprobe nbd to enable the kernel NBD
230       client  module.   CAUTION:  Do not use this method to mount filesystems
231       from an untrusted guest image - a malicious guest may have prepared the
232       image  to  attempt  to trigger kernel bugs in partition probing or file
233       system mounting.
234
235          qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2
236          qemu-nbd -d /dev/nbd0
237
238       Query a remote server to see details about what export(s) it is serving
239       on port 10809, and authenticating via PSK:
240
241          qemu-nbd \
242            --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \
243            --tls-creds tls0 -L -b remote.example.com
244

SEE ALSO

246       qemu(1), qemu-img(1)
247

AUTHOR

249       Anthony Liguori <anthony@codemonkey.ws>
250
252       2023, The QEMU Project Developers
253
254
255
256
2577.2.6                            Sep 26, 2023                      QEMU-NBD(8)
Impressum