doc/proto.txt

   1 The NBD protocol
   2 ================
   3
   4 The NBD protocol has two phases: the handshake (in which the connection
   5 is established, an exported NBD device is negotiated between the client
   6 and the server, and protocol options are negotiated), and the data
   7 pushing phase (in which the client and server are communicating between
   8 eachother).
   9
  10 On the client side under Linux, the handshake is implemented in
  11 userspace, while the data pushing phase is implemented in kernel space.
  12 To get from the handshake to the data pushing phase, the client performs
  13
  14 ioctl(nbd, NBD_SET_SOCK, sock)
  15 ioctl(nbd, NBD_DO_IT)
  16
  17 with 'nbd' in the above ioctl being a file descriptor for an open
  18 /dev/nbdX device node, and 'sock' being the socket to the server. The
  19 second of the two above ioctls does not return until the client
  20 disconnects.
  21
  22 Note that there are other ioctls available, that are used by the client
  23 to communicate the options to the kernel which were negotiated with the
  24 server during the handshake.
  25
  26 There are two message types in the data pushing phase: the request, and
  27 the response.
  28
  29 There are four request types in the data pushing phase: NBD_CMD_READ,
  30 NBD_CMD_WRITE, NBD_CMD_DISC (disconnect), and NBD_CMD_FLUSH.
  31
  32 The request is sent by the client; the response by the server. A request
  33 header consists a 32 bit magic number (magic), a 32 bit field denoting
  34 the request type (see below; 'type'), a 64 bit handle ('handle'), a 64
  35 bit data offset ('from'), and a 32 bit length ('len'). In case of a
  36 write request, the header is immediately followed by 'len' bytes of
  37 data. In the case of NBD_CMD_FLUSH, the offset and length should
  38 be zero (meaning "flush entire device"); other values are reserved
  39 for future use (e.g. for flushing specific areas without a write).
  40
  41 The reply contains three fields: a 32 bit magic number ('magic'), a 32
  42 bit error code ('error'; 0, unless an error occurred in which case it is
  43 the errno of the error on the server side), and the same 64 bit handle
  44 that the corresponding request had in its 'handle' field. In case the
  45 reply is sent in response to a read request and the error field is 0
  46 (zero), the reply header is immediately followed by request.len bytes of
  47 data.
  48
  49 In case of a disconnect request, the server will immediately close the
  50 connection. Requests are currently handled synchronously; when (not if)
  51 we change that to asynchronous handling, handling the disconnect request
  52 will probably be postponed until there are no other outstanding
  53 requests.
  54
  55 A flush request will not be sent unless NBD_FLAG_SEND_FLUSH is set,
  56 and indicates the backing file should be fdatasync()'d to disk.
  57
  58 The top 16 bits of the request are flags. NBD_CMD_FLAG_FUA implies
  59 a force unit access, and can currently only be usefully combined
  60 with NBD_CMD_WRITE. This is implementing using sync_file_range
  61 if present, else by fdatasync() of that file (note not all files
  62 in a multifile environment). NBD_CMD_FLAG_FUA will not be set
  63 unless NBD_FLAG_SEND_FUA is set.
  64
  65 There are two versions of the negotiation: the 'old' style (nbd <=
  66 2.9.16) and the 'new' style (nbd >= 2.9.17, though due to a bug it does
  67 not work with anything below 2.9.18). What follows is a description of
  68 both cases (in the below description, the label 'C:' is used for
  69 messages sent by the client, whereas 'S:' is used for messages sent by
  70 the server). "quoted text" is for literal character data, '0xdeadbeaf'
  71 is used for literal hex numbers (which are always sent in network byte
  72 order), and (brackets) are used for comments. Anything else is a
  73 description of the data that is sent.
  74
  75 'old' style handshake
  76 ---------------------
  77 S: "NBDMAGIC" (the INIT_PASSWD in the code)
  78 S: 0x00420281861253 (cliserv_magic, a magic number)
  79 S: size of the export in bytes, 64 bit unsigned int
  80 S: flags, 4 bytes (may have the NBD_FLAG_READ_ONLY flag set if the
  81    export is read-only; the rest is reserved)
  82 S: 124 bytes of zeroes (registered for future use, yes this is
  83    excessive).
  84
  85 As can be seen, this isn't exactly a negotiation; it's just the server
  86 sending a bunch of data to the client. If the client is unhappy with
  87 what he receives, he's supposed to disconnect and not look back.
  88
  89 The fact that the size of the export was specified before the flags were
  90 sent, made it impossible for the protocol to be changed in a
  91 backwards-compatible manner to allow for named exports without ugliness.
  92 As a result, the old style negotiation is now no longer developed, and
  93 only still supported for backwards compatibility.
  94
  95 'new' style handshake
  96 ---------------------
  97
  98 A client who wants to use the new style negotiation MUST connect on the
  99 IANA-reserved port for NBD, 10809. The server may listen on other ports
 100 as well, but it will use the old style handshake on those. The server
 101 will refuse to allow old-style negotiations on the new-style port.
 102
 103 S: "NBDMAGIC" (as in the old style handshake)
 104 S: 0x49484156454F5054 (note different magic number)
 105 S: 16 bits of zero (reserved for future use)
 106 C: 32 bits of zero (reserved for future use)
 107
 108 This completes the initial phase of negotiation; the client and server
 109 now both know they understand the first version of the new-style
 110 handshake, with no options. What follows is a repeating group of
 111 options. Currently only one option can be set (the name of the export to
 112 be used), and it is not optional; but future protocol extensions may add
 113 other options that may or may not be optional. Once extra protocol
 114 options have been added, the order in which these options are set will
 115 not be significant.
 116
 117 The generic format of setting an option is as follows:
 118
 119 C: 0x49484156454F5054 (note same new-style handshake's magic number)
 120 C: 32 bits denoting the chosen option (NBD_OPT_EXPORT_NAME is the only
 121    possible value currently)
 122 C: unsigned 32 bit length of option data
 123 C: (any data needed for the chosen option)
 124 S: (any response as needed and defined by the chosen option; currently
 125    this does not happen).
 126
 127 The presence of the option length in every option allows the server
 128 to skip any options presented by the client that it does not
 129 understand.
 130
 131 The data needed for the NBD_OPT_EXPORT_NAME option is:
 132
 133 C: name of the export (character string of length as specified,
 134    not terminated by any NUL bytes or similar)
 135
 136 Once all options are set, the server replies with information about the
 137 used export:
 138
 139 S: size of the export in bytes, 64 bit unsigned int
 140 S: flags (16 bits unsigned int, may contain NBD_FLAG_READ_ONLY if the
 141    export is read-only)
 142 S: 124 bytes of zeroes (forgot to remove that, oops)
 143
 144 The reason that the flags field is 16 bits large and not 32 as in the
 145 old style of the protocol is that there are now 16 bits of per-export
 146 flags, and 16 bits of per-server flags. Concatenated together, this
 147 results in 32 bits, which allows for using a common set of macros for
 148 both; indeed, the code masks away the upper or lower bits of a 32 bit
 149 "flags" field when performing the new-style handshake. If we ever run
 150 out of flags, the server will set the most significant flag bit,
 151 signalling that an extra flag field will follow, to which the client
 152 will have to reply with a flag field of its own before the extra flags
 153 are sent. This is not yet implemented.