xref: /openbmc/qemu/docs/interop/nbd.rst (revision 8dac93a8)
1QEMU NBD protocol support
2=========================
3
4QEMU supports the NBD protocol, and has an internal NBD client (see
5``block/nbd.c``), an internal NBD server (see ``blockdev-nbd.c``), and an
6external NBD server tool (see ``qemu-nbd.c``). The common code is placed
7in ``nbd/*``.
8
9The NBD protocol is specified here:
10https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
11
12The following paragraphs describe some specific properties of NBD
13protocol realization in QEMU.
14
15Metadata namespaces
16-------------------
17
18QEMU supports the ``base:allocation`` metadata context as defined in the
19NBD protocol specification, and also defines an additional metadata
20namespace ``qemu``.
21
22``qemu`` namespace
23------------------
24
25The ``qemu`` namespace currently contains two available metadata context
26types.  The first is related to exposing the contents of a dirty
27bitmap alongside the associated disk contents.  That metadata context
28is named with the following form::
29
30    qemu:dirty-bitmap:<dirty-bitmap-export-name>
31
32Each dirty-bitmap metadata context defines only one flag for extents
33in reply for ``NBD_CMD_BLOCK_STATUS``:
34
35bit 0:
36  ``NBD_STATE_DIRTY``, set when the extent is "dirty"
37
38The second is related to exposing the source of various extents within
39the image, with a single metadata context named::
40
41    qemu:allocation-depth
42
43In the allocation depth context, the entire 32-bit value represents a
44depth of which layer in a thin-provisioned backing chain provided the
45data (0 for unallocated, 1 for the active layer, 2 for the first
46backing layer, and so forth).
47
48For ``NBD_OPT_LIST_META_CONTEXT`` the following queries are supported
49in addition to the specific ``qemu:allocation-depth`` and
50``qemu:dirty-bitmap:<dirty-bitmap-export-name>``:
51
52``qemu:``
53  returns list of all available metadata contexts in the namespace
54``qemu:dirty-bitmap:``
55  returns list of all available dirty-bitmap metadata contexts
56
57Features by version
58-------------------
59
60The following list documents which qemu version first implemented
61various features (both as a server exposing the feature, and as a
62client taking advantage of the feature when present), to make it
63easier to plan for cross-version interoperability.  Note that in
64several cases, the initial release containing a feature may require
65additional patches from the corresponding stable branch to fix bugs in
66the operation of that feature.
67
682.6
69  ``NBD_OPT_STARTTLS`` with TLS X.509 Certificates
702.8
71  ``NBD_CMD_WRITE_ZEROES``
722.10
73  ``NBD_OPT_GO``, ``NBD_INFO_BLOCK``
742.11
75  ``NBD_OPT_STRUCTURED_REPLY``
762.12
77  ``NBD_CMD_BLOCK_STATUS`` for ``base:allocation``
783.0
79  ``NBD_OPT_STARTTLS`` with TLS Pre-Shared Keys (PSK),
80  ``NBD_CMD_BLOCK_STATUS`` for ``qemu:dirty-bitmap:``, ``NBD_CMD_CACHE``
814.2
82  ``NBD_FLAG_CAN_MULTI_CONN`` for shareable read-only exports,
83  ``NBD_CMD_FLAG_FAST_ZERO``
845.2
85  ``NBD_CMD_BLOCK_STATUS`` for ``qemu:allocation-depth``
867.1
87  ``NBD_FLAG_CAN_MULTI_CONN`` for shareable writable exports
888.2
89  ``NBD_OPT_EXTENDED_HEADERS``, ``NBD_FLAG_BLOCK_STATUS_PAYLOAD``
90