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