# QEMU NBD protocol support

QEMU supports the NBD protocol, and has an internal NBD client (see `block/nbd.c`), an internal NBD server (see `blockdev-nbd.c`), and an external NBD server tool (see `qemu-nbd.c`). The common code is placed in `nbd/*`.

The NBD protocol is specified here: https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md

The following paragraphs describe some specific properties of NBD protocol realization in QEMU.

## Metadata namespaces

QEMU supports the `base:allocation` metadata context as defined in the NBD protocol specification, and also defines an additional metadata namespace `qemu`.

## `qemu` namespace

The `qemu` namespace currently contains two available metadata context types. The first is related to exposing the contents of a dirty bitmap alongside the associated disk contents. That metadata context is named with the following form:

    qemu:dirty-bitmap:<dirty-bitmap-export-name>

Each dirty-bitmap metadata context defines only one flag for extents in reply for `NBD_CMD_BLOCK_STATUS`:

bit 0:

  `NBD_STATE_DIRTY`, set when the extent is “dirty”

The second is related to exposing the source of various extents within the image, with a single metadata context named:

    qemu:allocation-depth

In the allocation depth context, the entire 32-bit value represents a depth of which layer in a thin-provisioned backing chain provided the data (0 for unallocated, 1 for the active layer, 2 for the first backing layer, and so forth).

For `NBD_OPT_LIST_META_CONTEXT` the following queries are supported in addition to the specific `qemu:allocation-depth` and `qemu:dirty-bitmap:<dirty-bitmap-export-name>`:

`qemu:`

  returns list of all available metadata contexts in the namespace

`qemu:dirty-bitmap:`

  returns list of all available dirty-bitmap metadata contexts

## Features by version

The following list documents which qemu version first implemented various features (both as a server exposing the feature, and as a client taking advantage of the feature when present), to make it easier to plan for cross-version interoperability. Note that in several cases, the initial release containing a feature may require additional patches from the corresponding stable branch to fix bugs in the operation of that feature.

2.6

  `NBD_OPT_STARTTLS` with TLS X.509 Certificates

2.8

  `NBD_CMD_WRITE_ZEROES`

2.10

  `NBD_OPT_GO`, `NBD_INFO_BLOCK`

2.11

  `NBD_OPT_STRUCTURED_REPLY`

2.12

  `NBD_CMD_BLOCK_STATUS` for `base:allocation`

3.0

  `NBD_OPT_STARTTLS` with TLS Pre-Shared Keys (PSK), `NBD_CMD_BLOCK_STATUS` for `qemu:dirty-bitmap:`, `NBD_CMD_CACHE`

4.2

  `NBD_FLAG_CAN_MULTI_CONN` for shareable read-only exports, `NBD_CMD_FLAG_FAST_ZERO`

5.2

  `NBD_CMD_BLOCK_STATUS` for `qemu:allocation-depth`

7.1

  `NBD_FLAG_CAN_MULTI_CONN` for shareable writable exports

8.2

  `NBD_OPT_EXTENDED_HEADERS`, `NBD_FLAG_BLOCK_STATUS_PAYLOAD`