← Back to branch summary

~ubuntu-branches/ubuntu/saucy/nbd/saucy

« back to all changes in this revision

Viewing changes to doc/proto.txt

  • Committer: Package Import Robot
  • Author(s): Vibhav Pant
  • Date: 2012-06-17 07:29:43 UTC
  • mfrom: (21.1.36 sid)
  • Revision ID: package-import@ubuntu.com-20120617072943-0t0jyq1i029jz59l
Tags: 1:3.1.1-1ubuntu1
https://launchpad.net/bugs/1014184
* Merge from Debian unstable. (LP: #1014184) Remaining changes:
  - Drop /etc/modprobe.d/nbd-client; the kernel default is already
    appropriate. Ubuntu-specific change.
    + Modify debian/nbd-client.dirs
    + Remove debian/nbd-client.modprobe

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/proto.txt
107
107
 
108
108
S: "NBDMAGIC" (as in the old style handshake)
109
109
S: 0x49484156454F5054 (note different magic number)
110
 
S: 16 bits of zero (reserved for future use)
 
110
S: 16 bits of zero (bits 1-15 reserved for future use; bit 0 in use to
 
111
   signal fixed newstyle (see below))
111
112
C: 32 bits of zero (reserved for future use)
112
113
 
113
114
This completes the initial phase of negotiation; the client and server
123
124
 
124
125
C: 0x49484156454F5054 (note same new-style handshake's magic number)
125
126
C: 32 bits denoting the chosen option (NBD_OPT_EXPORT_NAME is the only
126
 
   possible value currently)
 
127
   possible value in this version of the protocol)
127
128
C: unsigned 32 bit length of option data
128
129
C: (any data needed for the chosen option)
129
 
S: (any response as needed and defined by the chosen option; currently
130
 
   this does not happen).
131
130
 
132
131
The presence of the option length in every option allows the server
133
132
to skip any options presented by the client that it does not
156
155
will have to reply with a flag field of its own before the extra flags
157
156
are sent. This is not yet implemented.
158
157
 
 
158
Fixed 'new' style handshake
 
159
---------------------------
 
160
 
 
161
Unfortunately, due to a mistake on my end, the server would immediately
 
162
close the connection when it saw an option it did not understand, rather
 
163
than signalling this fact to the client, which would've allowed it to
 
164
retry; and replies from the server were not structured either, which
 
165
meant that if the server were to send something the client did not
 
166
understand, it would have to abort negotiation as well.
 
167
 
 
168
To fix these two issues, the handshake has been extended once more:
 
169
 
 
170
- The server will set bit 0 of its first set of reserved flags, to
 
171
  signal that it supports this version of the protocol.
 
172
- The client should reply with bit 0 set in its reserved field too,
 
173
  though its side of the protocol does not change incompatibly.
 
174
- The client may now send other options to the server as appropriate, in
 
175
  the generic format for sending an option as described above.
 
176
- The server will reply to any option apart from NBD_OPT_EXPORT_NAME
 
177
  with reply packets in the following format:
 
178
 
 
179
S: 64 bits, 0x3e889045565a9 (magic number for replies)
 
180
S: 32 bits, the option as sent by the client to which this is a reply
 
181
   packet.
 
182
S: 32 bits, denoting reply type (e.g., NBD_REP_ACK to denote successful
 
183
   completion, or NBD_REP_ERR_UNSUP to denote use of an option not known
 
184
   by this server
 
185
S: 32 bits, length of the reply. This may be zero for some replies, in
 
186
   which case the next field is not sent
 
187
S: any data as required by the reply (e.g., an export name in the case
 
188
   of NBD_REP_SERVER
 
189
 
 
190
As there is no unique number for client requests, clients who want to
 
191
differentiate between answers to two instances of the same option during
 
192
any negotiation must make sure they've seen the answer to an outstanding
 
193
request before sending the next one of the same type.
 
194
 
 
195
Values
 
196
------
 
197
 
 
198
This section describes the meaning of constants (other than magic
 
199
numbers) in the protocol handshake.
 
200
 
159
201
Flag bits
160
 
---------
161
 
 
162
 
bit 0 - NBD_FLAG_HAS_FLAGS
163
 
should always be 1
164
 
 
165
 
bit 1 - NBD_FLAG_READ_ONLY
166
 
should be set to 1 if the export is read-only
167
 
 
168
 
bit 2 - NBD_FLAG_SEND_FLUSH
169
 
should be set to 1 if the server supports NBD_CMD_FLUSH commands
170
 
 
171
 
bit 3 - NBD_FLAG_SEND_FUA
172
 
should be set to 1 if the server supports the NBD_CMD_FLAG_FUA flag
173
 
 
174
 
bit 4 - NBD_FLAG_ROTATIONAL
175
 
should be set to 1 to let the client schedule I/O accesses as for a
176
 
rotational medium
177
 
 
178
 
bit 5 - NBD_FLAG_SEND_TRIM
179
 
should be set to 1 if the server supports NBD_CMD_TRIM commands
180
 
 
 
202
- - - - -
 
203
 
 
204
* Per-export (16 bits, sent after option haggling, or immediately after
 
205
  the global flag field in oldstyle negotiation):
 
206
 
 
207
  bit 0 - NBD_FLAG_HAS_FLAGS
 
208
  should always be 1
 
209
 
 
210
  bit 1 - NBD_FLAG_READ_ONLY
 
211
  should be set to 1 if the export is read-only
 
212
 
 
213
  bit 2 - NBD_FLAG_SEND_FLUSH
 
214
  should be set to 1 if the server supports NBD_CMD_FLUSH commands
 
215
 
 
216
  bit 3 - NBD_FLAG_SEND_FUA
 
217
  should be set to 1 if the server supports the NBD_CMD_FLAG_FUA flag
 
218
 
 
219
  bit 4 - NBD_FLAG_ROTATIONAL
 
220
  should be set to 1 to let the client schedule I/O accesses as for a
 
221
  rotational medium
 
222
 
 
223
  bit 5 - NBD_FLAG_SEND_TRIM
 
224
  should be set to 1 if the server supports NBD_CMD_TRIM commands
 
225
 
 
226
* Global flag bits (16 bits, after initial connection):
 
227
 
 
228
  bit 0 - NBD_FLAG_FIXED_NEWSTYLE
 
229
  should be set by servers that support the fixed newstyle protocol
 
230
 
 
231
* Client (after initial connection and after receiving flags from
 
232
  server):
 
233
 
 
234
  bit 0 - NBD_FLAG_C_FIXED_NEWSTYLE
 
235
  Should be set by clients that support the fixed newstyle protocol.
 
236
  Servers may choose to honour fixed newstyle from clients that didn't
 
237
  set this bit, but relying on this isn't recommended.
 
238
 
 
239
Option types
 
240
- - - - - - -
 
241
 
 
242
* NBD_OPT_EXPORT_NAME (1)
 
243
  Choose the export which the client would like to use, and end option
 
244
  haggling. Data: name of the export, free-form UTF8 text (subject to
 
245
  limitations by server implementation). If the chosen export does not
 
246
  exist, the server closes the connection.
 
247
 
 
248
* NBD_OPT_LIST (2)
 
249
  Returns a number of NBD_REP_SERVER replies, one for each export,
 
250
  followed by an NBD_REP_ACK.
 
251
 
 
252
* NBD_OPT_ABORT (3)
 
253
  Abort negotiation and close the connection. Optional.
 
254
 
 
255
Reply types
 
256
- - - - - -
 
257
 
 
258
* NBD_REP_ACK (1)
 
259
  Will be sent by the server when it accepts the option, or when sending
 
260
  data related to the option (in the case of NBD_OPT_LIST) has finished.
 
261
  No data.
 
262
 
 
263
* NBD_REP_SERVER (2)
 
264
  A description of an export. Data:
 
265
  - 32 bits, length of name
 
266
  - Name of the export, as expected by NBD_OPT_EXPORT_NAME
 
267
  - If length of name < (length of reply as sent in the reply packet
 
268
    header - 4), then the rest of the data contains some undefined
 
269
    implementation-specific details about the export. This is not
 
270
    currently implemented, but future versions of nbd-server may send
 
271
    along some details about the export. If the client did not
 
272
    explicitly request otherwise, these details are defined to be UTF-8
 
273
    encoded data suitable for direct display to a human being.
 
274
 
 
275
There are a number of error reply types, all of which are denoted by
 
276
having bit 31 set. All error replies may have some data set, in which
 
277
case that data is an error message suitable for display to the user.
 
278
 
 
279
* NBD_REP_ERR_UNSUP (2^31 + 1)
 
280
  The option sent by the client is unknown by this server
 
281
  implementation (e.g., because the server is too old, or from another
 
282
  source).
 
283
 
 
284
* NBD_REP_ERR_POLICY (2^31 + 2)
 
285
  The option sent by the client is known by this server and
 
286
  syntactically valid, but server-side policy forbids the server to
 
287
  allow the option (e.g., the client sent NBD_OPT_LIST but server
 
288
  configuration has that disabled)
 
289
 
 
290
* NBD_REP_ERR_INVALID (2^31 + 3)
 
291
  The option sent by the client is know by this server, but was
 
292
  determined by the server to be syntactically invalid. For instance,
 
293
  the client sent an NBD_OPT_LIST with nonzero data length.
 
294
 
 
295
* NBD_REP_ERR_PLATFORM (2^31 + 4)
 
296
  The option sent by the client is not supported on the platform on
 
297
  which the server is running. Not currently used.