| Peter Maydell | 8dac93a | 2024-08-09 17:37:54 +0100 | [diff] [blame] | 1 | QEMU NBD protocol support |
| 2 | ========================= |
| 3 | |
| 4 | QEMU 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 |
| 6 | external NBD server tool (see ``qemu-nbd.c``). The common code is placed |
| 7 | in ``nbd/*``. |
| 8 | |
| 9 | The NBD protocol is specified here: |
| 10 | https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md |
| 11 | |
| 12 | The following paragraphs describe some specific properties of NBD |
| 13 | protocol realization in QEMU. |
| 14 | |
| 15 | Metadata namespaces |
| 16 | ------------------- |
| 17 | |
| 18 | QEMU supports the ``base:allocation`` metadata context as defined in the |
| 19 | NBD protocol specification, and also defines an additional metadata |
| 20 | namespace ``qemu``. |
| 21 | |
| 22 | ``qemu`` namespace |
| 23 | ------------------ |
| 24 | |
| 25 | The ``qemu`` namespace currently contains two available metadata context |
| 26 | types. The first is related to exposing the contents of a dirty |
| 27 | bitmap alongside the associated disk contents. That metadata context |
| 28 | is named with the following form:: |
| 29 | |
| 30 | qemu:dirty-bitmap:<dirty-bitmap-export-name> |
| 31 | |
| 32 | Each dirty-bitmap metadata context defines only one flag for extents |
| 33 | in reply for ``NBD_CMD_BLOCK_STATUS``: |
| 34 | |
| 35 | bit 0: |
| 36 | ``NBD_STATE_DIRTY``, set when the extent is "dirty" |
| 37 | |
| 38 | The second is related to exposing the source of various extents within |
| 39 | the image, with a single metadata context named:: |
| 40 | |
| 41 | qemu:allocation-depth |
| 42 | |
| 43 | In the allocation depth context, the entire 32-bit value represents a |
| 44 | depth of which layer in a thin-provisioned backing chain provided the |
| 45 | data (0 for unallocated, 1 for the active layer, 2 for the first |
| 46 | backing layer, and so forth). |
| 47 | |
| 48 | For ``NBD_OPT_LIST_META_CONTEXT`` the following queries are supported |
| 49 | in 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 | |
| 57 | Features by version |
| 58 | ------------------- |
| 59 | |
| 60 | The following list documents which qemu version first implemented |
| 61 | various features (both as a server exposing the feature, and as a |
| 62 | client taking advantage of the feature when present), to make it |
| 63 | easier to plan for cross-version interoperability. Note that in |
| 64 | several cases, the initial release containing a feature may require |
| 65 | additional patches from the corresponding stable branch to fix bugs in |
| 66 | the operation of that feature. |
| 67 | |
| 68 | 2.6 |
| 69 | ``NBD_OPT_STARTTLS`` with TLS X.509 Certificates |
| 70 | 2.8 |
| 71 | ``NBD_CMD_WRITE_ZEROES`` |
| 72 | 2.10 |
| 73 | ``NBD_OPT_GO``, ``NBD_INFO_BLOCK`` |
| 74 | 2.11 |
| 75 | ``NBD_OPT_STRUCTURED_REPLY`` |
| 76 | 2.12 |
| 77 | ``NBD_CMD_BLOCK_STATUS`` for ``base:allocation`` |
| 78 | 3.0 |
| 79 | ``NBD_OPT_STARTTLS`` with TLS Pre-Shared Keys (PSK), |
| 80 | ``NBD_CMD_BLOCK_STATUS`` for ``qemu:dirty-bitmap:``, ``NBD_CMD_CACHE`` |
| 81 | 4.2 |
| 82 | ``NBD_FLAG_CAN_MULTI_CONN`` for shareable read-only exports, |
| 83 | ``NBD_CMD_FLAG_FAST_ZERO`` |
| 84 | 5.2 |
| 85 | ``NBD_CMD_BLOCK_STATUS`` for ``qemu:allocation-depth`` |
| 86 | 7.1 |
| 87 | ``NBD_FLAG_CAN_MULTI_CONN`` for shareable writable exports |
| 88 | 8.2 |
| 89 | ``NBD_OPT_EXTENDED_HEADERS``, ``NBD_FLAG_BLOCK_STATUS_PAYLOAD`` |
