1 /* 2 * Copyright Red Hat 3 * Copyright (C) 2005 Anthony Liguori <anthony@codemonkey.ws> 4 * 5 * Network Block Device 6 * 7 * This program is free software; you can redistribute it and/or modify 8 * it under the terms of the GNU General Public License as published by 9 * the Free Software Foundation; under version 2 of the License. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, see <http://www.gnu.org/licenses/>. 18 */ 19 20 #ifndef NBD_H 21 #define NBD_H 22 23 #include "block/export.h" 24 #include "io/channel-socket.h" 25 #include "crypto/tlscreds.h" 26 #include "qapi/error.h" 27 #include "qemu/bswap.h" 28 29 typedef struct NBDExport NBDExport; 30 typedef struct NBDClient NBDClient; 31 typedef struct NBDClientConnection NBDClientConnection; 32 typedef struct NBDMetaContexts NBDMetaContexts; 33 34 extern const BlockExportDriver blk_exp_nbd; 35 36 /* Handshake phase structs - this struct is passed on the wire */ 37 38 typedef struct NBDOption { 39 uint64_t magic; /* NBD_OPTS_MAGIC */ 40 uint32_t option; /* NBD_OPT_* */ 41 uint32_t length; 42 } QEMU_PACKED NBDOption; 43 44 typedef struct NBDOptionReply { 45 uint64_t magic; /* NBD_REP_MAGIC */ 46 uint32_t option; /* NBD_OPT_* */ 47 uint32_t type; /* NBD_REP_* */ 48 uint32_t length; 49 } QEMU_PACKED NBDOptionReply; 50 51 typedef struct NBDOptionReplyMetaContext { 52 NBDOptionReply h; /* h.type = NBD_REP_META_CONTEXT, h.length > 4 */ 53 uint32_t context_id; 54 /* metadata context name follows */ 55 } QEMU_PACKED NBDOptionReplyMetaContext; 56 57 /* Track results of negotiation */ 58 typedef enum NBDMode { 59 /* Keep this list in a continuum of increasing features. */ 60 NBD_MODE_OLDSTYLE, /* server lacks newstyle negotiation */ 61 NBD_MODE_EXPORT_NAME, /* newstyle but only OPT_EXPORT_NAME safe */ 62 NBD_MODE_SIMPLE, /* newstyle but only simple replies */ 63 NBD_MODE_STRUCTURED, /* newstyle, structured replies enabled */ 64 NBD_MODE_EXTENDED, /* newstyle, extended headers enabled */ 65 } NBDMode; 66 67 /* Transmission phase structs */ 68 69 /* 70 * Note: NBDRequest is _NOT_ the same as the network representation of an NBD 71 * request! 72 */ 73 typedef struct NBDRequest { 74 uint64_t cookie; 75 uint64_t from; /* Offset touched by the command */ 76 uint64_t len; /* Effect length; 32 bit limit without extended headers */ 77 uint16_t flags; /* NBD_CMD_FLAG_* */ 78 uint16_t type; /* NBD_CMD_* */ 79 NBDMode mode; /* Determines which network representation to use */ 80 } NBDRequest; 81 82 typedef struct NBDSimpleReply { 83 uint32_t magic; /* NBD_SIMPLE_REPLY_MAGIC */ 84 uint32_t error; 85 uint64_t cookie; 86 } QEMU_PACKED NBDSimpleReply; 87 88 /* Header of all structured replies */ 89 typedef struct NBDStructuredReplyChunk { 90 uint32_t magic; /* NBD_STRUCTURED_REPLY_MAGIC */ 91 uint16_t flags; /* combination of NBD_REPLY_FLAG_* */ 92 uint16_t type; /* NBD_REPLY_TYPE_* */ 93 uint64_t cookie; /* request handle */ 94 uint32_t length; /* length of payload */ 95 } QEMU_PACKED NBDStructuredReplyChunk; 96 97 typedef struct NBDExtendedReplyChunk { 98 uint32_t magic; /* NBD_EXTENDED_REPLY_MAGIC */ 99 uint16_t flags; /* combination of NBD_REPLY_FLAG_* */ 100 uint16_t type; /* NBD_REPLY_TYPE_* */ 101 uint64_t cookie; /* request handle */ 102 uint64_t offset; /* request offset */ 103 uint64_t length; /* length of payload */ 104 } QEMU_PACKED NBDExtendedReplyChunk; 105 106 typedef union NBDReply { 107 NBDSimpleReply simple; 108 NBDStructuredReplyChunk structured; 109 NBDExtendedReplyChunk extended; 110 struct { 111 /* 112 * @magic and @cookie fields have the same offset and size in all 113 * forms of replies, so let them be accessible without ".simple.", 114 * ".structured.", or ".extended." specifications. 115 */ 116 uint32_t magic; 117 uint32_t _skip; 118 uint64_t cookie; 119 }; 120 } NBDReply; 121 QEMU_BUILD_BUG_ON(offsetof(NBDReply, simple.cookie) != 122 offsetof(NBDReply, cookie)); 123 QEMU_BUILD_BUG_ON(offsetof(NBDReply, structured.cookie) != 124 offsetof(NBDReply, cookie)); 125 QEMU_BUILD_BUG_ON(offsetof(NBDReply, extended.cookie) != 126 offsetof(NBDReply, cookie)); 127 128 /* Header of chunk for NBD_REPLY_TYPE_OFFSET_DATA */ 129 typedef struct NBDStructuredReadData { 130 /* header's .length >= 9 */ 131 uint64_t offset; 132 /* At least one byte of data payload follows, calculated from h.length */ 133 } QEMU_PACKED NBDStructuredReadData; 134 135 /* Complete chunk for NBD_REPLY_TYPE_OFFSET_HOLE */ 136 typedef struct NBDStructuredReadHole { 137 /* header's length == 12 */ 138 uint64_t offset; 139 uint32_t length; 140 } QEMU_PACKED NBDStructuredReadHole; 141 142 /* Header of all NBD_REPLY_TYPE_ERROR* errors */ 143 typedef struct NBDStructuredError { 144 /* header's length >= 6 */ 145 uint32_t error; 146 uint16_t message_length; 147 } QEMU_PACKED NBDStructuredError; 148 149 /* Header of NBD_REPLY_TYPE_BLOCK_STATUS */ 150 typedef struct NBDStructuredMeta { 151 /* header's length >= 12 (at least one extent) */ 152 uint32_t context_id; 153 /* NBDExtent32 extents[] follows, array length implied by header */ 154 } QEMU_PACKED NBDStructuredMeta; 155 156 /* Extent array element for NBD_REPLY_TYPE_BLOCK_STATUS */ 157 typedef struct NBDExtent32 { 158 uint32_t length; 159 uint32_t flags; /* NBD_STATE_* */ 160 } QEMU_PACKED NBDExtent32; 161 162 /* Header of NBD_REPLY_TYPE_BLOCK_STATUS_EXT */ 163 typedef struct NBDExtendedMeta { 164 /* header's length >= 24 (at least one extent) */ 165 uint32_t context_id; 166 uint32_t count; /* header length must be count * 16 + 8 */ 167 /* NBDExtent64 extents[count] follows */ 168 } QEMU_PACKED NBDExtendedMeta; 169 170 /* Extent array element for NBD_REPLY_TYPE_BLOCK_STATUS_EXT */ 171 typedef struct NBDExtent64 { 172 uint64_t length; 173 uint64_t flags; /* NBD_STATE_* */ 174 } QEMU_PACKED NBDExtent64; 175 176 /* Client payload for limiting NBD_CMD_BLOCK_STATUS reply */ 177 typedef struct NBDBlockStatusPayload { 178 uint64_t effect_length; 179 /* uint32_t ids[] follows, array length implied by header */ 180 } QEMU_PACKED NBDBlockStatusPayload; 181 182 /* Transmission (export) flags: sent from server to client during handshake, 183 but describe what will happen during transmission */ 184 enum { 185 NBD_FLAG_HAS_FLAGS_BIT = 0, /* Flags are there */ 186 NBD_FLAG_READ_ONLY_BIT = 1, /* Device is read-only */ 187 NBD_FLAG_SEND_FLUSH_BIT = 2, /* Send FLUSH */ 188 NBD_FLAG_SEND_FUA_BIT = 3, /* Send FUA (Force Unit Access) */ 189 NBD_FLAG_ROTATIONAL_BIT = 4, /* Use elevator algorithm - 190 rotational media */ 191 NBD_FLAG_SEND_TRIM_BIT = 5, /* Send TRIM (discard) */ 192 NBD_FLAG_SEND_WRITE_ZEROES_BIT = 6, /* Send WRITE_ZEROES */ 193 NBD_FLAG_SEND_DF_BIT = 7, /* Send DF (Do not Fragment) */ 194 NBD_FLAG_CAN_MULTI_CONN_BIT = 8, /* Multi-client cache consistent */ 195 NBD_FLAG_SEND_RESIZE_BIT = 9, /* Send resize */ 196 NBD_FLAG_SEND_CACHE_BIT = 10, /* Send CACHE (prefetch) */ 197 NBD_FLAG_SEND_FAST_ZERO_BIT = 11, /* FAST_ZERO flag for WRITE_ZEROES */ 198 NBD_FLAG_BLOCK_STAT_PAYLOAD_BIT = 12, /* PAYLOAD flag for BLOCK_STATUS */ 199 }; 200 201 #define NBD_FLAG_HAS_FLAGS (1 << NBD_FLAG_HAS_FLAGS_BIT) 202 #define NBD_FLAG_READ_ONLY (1 << NBD_FLAG_READ_ONLY_BIT) 203 #define NBD_FLAG_SEND_FLUSH (1 << NBD_FLAG_SEND_FLUSH_BIT) 204 #define NBD_FLAG_SEND_FUA (1 << NBD_FLAG_SEND_FUA_BIT) 205 #define NBD_FLAG_ROTATIONAL (1 << NBD_FLAG_ROTATIONAL_BIT) 206 #define NBD_FLAG_SEND_TRIM (1 << NBD_FLAG_SEND_TRIM_BIT) 207 #define NBD_FLAG_SEND_WRITE_ZEROES (1 << NBD_FLAG_SEND_WRITE_ZEROES_BIT) 208 #define NBD_FLAG_SEND_DF (1 << NBD_FLAG_SEND_DF_BIT) 209 #define NBD_FLAG_CAN_MULTI_CONN (1 << NBD_FLAG_CAN_MULTI_CONN_BIT) 210 #define NBD_FLAG_SEND_RESIZE (1 << NBD_FLAG_SEND_RESIZE_BIT) 211 #define NBD_FLAG_SEND_CACHE (1 << NBD_FLAG_SEND_CACHE_BIT) 212 #define NBD_FLAG_SEND_FAST_ZERO (1 << NBD_FLAG_SEND_FAST_ZERO_BIT) 213 #define NBD_FLAG_BLOCK_STAT_PAYLOAD (1 << NBD_FLAG_BLOCK_STAT_PAYLOAD_BIT) 214 215 /* New-style handshake (global) flags, sent from server to client, and 216 control what will happen during handshake phase. */ 217 #define NBD_FLAG_FIXED_NEWSTYLE (1 << 0) /* Fixed newstyle protocol. */ 218 #define NBD_FLAG_NO_ZEROES (1 << 1) /* End handshake without zeroes. */ 219 220 /* New-style client flags, sent from client to server to control what happens 221 during handshake phase. */ 222 #define NBD_FLAG_C_FIXED_NEWSTYLE (1 << 0) /* Fixed newstyle protocol. */ 223 #define NBD_FLAG_C_NO_ZEROES (1 << 1) /* End handshake without zeroes. */ 224 225 /* Option requests. */ 226 #define NBD_OPT_EXPORT_NAME (1) 227 #define NBD_OPT_ABORT (2) 228 #define NBD_OPT_LIST (3) 229 /* #define NBD_OPT_PEEK_EXPORT (4) not in use */ 230 #define NBD_OPT_STARTTLS (5) 231 #define NBD_OPT_INFO (6) 232 #define NBD_OPT_GO (7) 233 #define NBD_OPT_STRUCTURED_REPLY (8) 234 #define NBD_OPT_LIST_META_CONTEXT (9) 235 #define NBD_OPT_SET_META_CONTEXT (10) 236 #define NBD_OPT_EXTENDED_HEADERS (11) 237 238 /* Option reply types. */ 239 #define NBD_REP_ERR(value) ((UINT32_C(1) << 31) | (value)) 240 241 #define NBD_REP_ACK (1) /* Data sending finished. */ 242 #define NBD_REP_SERVER (2) /* Export description. */ 243 #define NBD_REP_INFO (3) /* NBD_OPT_INFO/GO. */ 244 #define NBD_REP_META_CONTEXT (4) /* NBD_OPT_{LIST,SET}_META_CONTEXT */ 245 246 #define NBD_REP_ERR_UNSUP NBD_REP_ERR(1) /* Unknown option */ 247 #define NBD_REP_ERR_POLICY NBD_REP_ERR(2) /* Server denied */ 248 #define NBD_REP_ERR_INVALID NBD_REP_ERR(3) /* Invalid length */ 249 #define NBD_REP_ERR_PLATFORM NBD_REP_ERR(4) /* Not compiled in */ 250 #define NBD_REP_ERR_TLS_REQD NBD_REP_ERR(5) /* TLS required */ 251 #define NBD_REP_ERR_UNKNOWN NBD_REP_ERR(6) /* Export unknown */ 252 #define NBD_REP_ERR_SHUTDOWN NBD_REP_ERR(7) /* Server shutting down */ 253 #define NBD_REP_ERR_BLOCK_SIZE_REQD NBD_REP_ERR(8) /* Need INFO_BLOCK_SIZE */ 254 #define NBD_REP_ERR_TOO_BIG NBD_REP_ERR(9) /* Payload size overflow */ 255 #define NBD_REP_ERR_EXT_HEADER_REQD NBD_REP_ERR(10) /* Need extended headers */ 256 257 /* Info types, used during NBD_REP_INFO */ 258 #define NBD_INFO_EXPORT 0 259 #define NBD_INFO_NAME 1 260 #define NBD_INFO_DESCRIPTION 2 261 #define NBD_INFO_BLOCK_SIZE 3 262 263 /* Request flags, sent from client to server during transmission phase */ 264 #define NBD_CMD_FLAG_FUA (1 << 0) /* 'force unit access' during write */ 265 #define NBD_CMD_FLAG_NO_HOLE (1 << 1) /* don't punch hole on zero run */ 266 #define NBD_CMD_FLAG_DF (1 << 2) /* don't fragment structured read */ 267 #define NBD_CMD_FLAG_REQ_ONE (1 << 3) \ 268 /* only one extent in BLOCK_STATUS reply chunk */ 269 #define NBD_CMD_FLAG_FAST_ZERO (1 << 4) /* fail if WRITE_ZEROES is not fast */ 270 #define NBD_CMD_FLAG_PAYLOAD_LEN (1 << 5) \ 271 /* length describes payload, not effect; only with ext header */ 272 273 /* Supported request types */ 274 enum { 275 NBD_CMD_READ = 0, 276 NBD_CMD_WRITE = 1, 277 NBD_CMD_DISC = 2, 278 NBD_CMD_FLUSH = 3, 279 NBD_CMD_TRIM = 4, 280 NBD_CMD_CACHE = 5, 281 NBD_CMD_WRITE_ZEROES = 6, 282 NBD_CMD_BLOCK_STATUS = 7, 283 }; 284 285 #define NBD_DEFAULT_PORT 10809 286 287 /* Maximum size of a single READ/WRITE data buffer */ 288 #define NBD_MAX_BUFFER_SIZE (32 * 1024 * 1024) 289 290 /* 291 * Maximum size of a protocol string (export name, metadata context name, 292 * etc.). Use malloc rather than stack allocation for storage of a 293 * string. 294 */ 295 #define NBD_MAX_STRING_SIZE 4096 296 297 /* Two types of request structures, a given client will only use 1 */ 298 #define NBD_REQUEST_MAGIC 0x25609513 299 #define NBD_EXTENDED_REQUEST_MAGIC 0x21e41c71 300 301 /* 302 * Three types of reply structures, but what a client expects depends 303 * on NBD_OPT_STRUCTURED_REPLY and NBD_OPT_EXTENDED_HEADERS. 304 */ 305 #define NBD_SIMPLE_REPLY_MAGIC 0x67446698 306 #define NBD_STRUCTURED_REPLY_MAGIC 0x668e33ef 307 #define NBD_EXTENDED_REPLY_MAGIC 0x6e8a278c 308 309 /* Chunk reply flags (for structured and extended replies) */ 310 #define NBD_REPLY_FLAG_DONE (1 << 0) /* This reply-chunk is last */ 311 312 /* Chunk reply types */ 313 #define NBD_REPLY_ERR(value) ((1 << 15) | (value)) 314 315 #define NBD_REPLY_TYPE_NONE 0 316 #define NBD_REPLY_TYPE_OFFSET_DATA 1 317 #define NBD_REPLY_TYPE_OFFSET_HOLE 2 318 #define NBD_REPLY_TYPE_BLOCK_STATUS 5 319 #define NBD_REPLY_TYPE_BLOCK_STATUS_EXT 6 320 #define NBD_REPLY_TYPE_ERROR NBD_REPLY_ERR(1) 321 #define NBD_REPLY_TYPE_ERROR_OFFSET NBD_REPLY_ERR(2) 322 323 /* Extent flags for base:allocation in NBD_REPLY_TYPE_BLOCK_STATUS */ 324 #define NBD_STATE_HOLE (1 << 0) 325 #define NBD_STATE_ZERO (1 << 1) 326 327 /* Extent flags for qemu:dirty-bitmap in NBD_REPLY_TYPE_BLOCK_STATUS */ 328 #define NBD_STATE_DIRTY (1 << 0) 329 330 /* No flags needed for qemu:allocation-depth in NBD_REPLY_TYPE_BLOCK_STATUS */ 331 332 static inline bool nbd_reply_type_is_error(int type) 333 { 334 return type & (1 << 15); 335 } 336 337 /* NBD errors are based on errno numbers, so there is a 1:1 mapping, 338 * but only a limited set of errno values is specified in the protocol. 339 * Everything else is squashed to EINVAL. 340 */ 341 #define NBD_SUCCESS 0 342 #define NBD_EPERM 1 343 #define NBD_EIO 5 344 #define NBD_ENOMEM 12 345 #define NBD_EINVAL 22 346 #define NBD_ENOSPC 28 347 #define NBD_EOVERFLOW 75 348 #define NBD_ENOTSUP 95 349 #define NBD_ESHUTDOWN 108 350 351 /* Details collected by NBD_OPT_EXPORT_NAME and NBD_OPT_GO */ 352 typedef struct NBDExportInfo { 353 /* Set by client before nbd_receive_negotiate() */ 354 bool request_sizes; 355 char *x_dirty_bitmap; 356 357 /* Set by client before nbd_receive_negotiate(), or by server results 358 * during nbd_receive_export_list() */ 359 char *name; /* must be non-NULL */ 360 361 /* In-out fields, set by client before nbd_receive_negotiate() and 362 * updated by server results during nbd_receive_negotiate() */ 363 NBDMode mode; /* input maximum mode tolerated; output actual mode chosen */ 364 bool base_allocation; /* base:allocation context for NBD_CMD_BLOCK_STATUS */ 365 366 /* Set by server results during nbd_receive_negotiate() and 367 * nbd_receive_export_list() */ 368 uint64_t size; 369 uint16_t flags; 370 uint32_t min_block; 371 uint32_t opt_block; 372 uint32_t max_block; 373 374 uint32_t context_id; 375 376 /* Set by server results during nbd_receive_export_list() */ 377 char *description; 378 int n_contexts; 379 char **contexts; 380 } NBDExportInfo; 381 382 int nbd_receive_negotiate(QIOChannel *ioc, QCryptoTLSCreds *tlscreds, 383 const char *hostname, QIOChannel **outioc, 384 NBDExportInfo *info, Error **errp); 385 void nbd_free_export_list(NBDExportInfo *info, int count); 386 int nbd_receive_export_list(QIOChannel *ioc, QCryptoTLSCreds *tlscreds, 387 const char *hostname, NBDExportInfo **info, 388 Error **errp); 389 int nbd_init(int fd, QIOChannelSocket *sioc, NBDExportInfo *info, 390 Error **errp); 391 int nbd_send_request(QIOChannel *ioc, NBDRequest *request); 392 int coroutine_fn nbd_receive_reply(BlockDriverState *bs, QIOChannel *ioc, 393 NBDReply *reply, NBDMode mode, 394 Error **errp); 395 int nbd_client(int fd); 396 int nbd_disconnect(int fd); 397 int nbd_errno_to_system_errno(int err); 398 399 void nbd_export_set_on_eject_blk(BlockExport *exp, BlockBackend *blk); 400 401 AioContext *nbd_export_aio_context(NBDExport *exp); 402 NBDExport *nbd_export_find(const char *name); 403 404 void nbd_client_new(QIOChannelSocket *sioc, 405 QCryptoTLSCreds *tlscreds, 406 const char *tlsauthz, 407 void (*close_fn)(NBDClient *, bool)); 408 void nbd_client_get(NBDClient *client); 409 void nbd_client_put(NBDClient *client); 410 411 void nbd_server_is_qemu_nbd(int max_connections); 412 bool nbd_server_is_running(void); 413 int nbd_server_max_connections(void); 414 void nbd_server_start(SocketAddress *addr, const char *tls_creds, 415 const char *tls_authz, uint32_t max_connections, 416 Error **errp); 417 void nbd_server_start_options(NbdServerOptions *arg, Error **errp); 418 419 /* nbd_read 420 * Reads @size bytes from @ioc. Returns 0 on success. 421 */ 422 static inline int nbd_read(QIOChannel *ioc, void *buffer, size_t size, 423 const char *desc, Error **errp) 424 { 425 ERRP_GUARD(); 426 int ret = qio_channel_read_all(ioc, buffer, size, errp) < 0 ? -EIO : 0; 427 428 if (ret < 0) { 429 if (desc) { 430 error_prepend(errp, "Failed to read %s: ", desc); 431 } 432 return ret; 433 } 434 435 return 0; 436 } 437 438 #define DEF_NBD_READ_N(bits) \ 439 static inline int nbd_read##bits(QIOChannel *ioc, \ 440 uint##bits##_t *val, \ 441 const char *desc, Error **errp) \ 442 { \ 443 int ret = nbd_read(ioc, val, sizeof(*val), desc, errp); \ 444 if (ret < 0) { \ 445 return ret; \ 446 } \ 447 *val = be##bits##_to_cpu(*val); \ 448 return 0; \ 449 } 450 451 DEF_NBD_READ_N(16) /* Defines nbd_read16(). */ 452 DEF_NBD_READ_N(32) /* Defines nbd_read32(). */ 453 DEF_NBD_READ_N(64) /* Defines nbd_read64(). */ 454 455 #undef DEF_NBD_READ_N 456 457 static inline bool nbd_reply_is_simple(NBDReply *reply) 458 { 459 return reply->magic == NBD_SIMPLE_REPLY_MAGIC; 460 } 461 462 static inline bool nbd_reply_is_structured(NBDReply *reply) 463 { 464 return reply->magic == NBD_STRUCTURED_REPLY_MAGIC; 465 } 466 467 const char *nbd_reply_type_lookup(uint16_t type); 468 const char *nbd_opt_lookup(uint32_t opt); 469 const char *nbd_rep_lookup(uint32_t rep); 470 const char *nbd_info_lookup(uint16_t info); 471 const char *nbd_cmd_lookup(uint16_t info); 472 const char *nbd_err_lookup(int err); 473 const char *nbd_mode_lookup(NBDMode mode); 474 475 /* nbd/client-connection.c */ 476 void nbd_client_connection_enable_retry(NBDClientConnection *conn); 477 478 NBDClientConnection *nbd_client_connection_new(const SocketAddress *saddr, 479 bool do_negotiation, 480 const char *export_name, 481 const char *x_dirty_bitmap, 482 QCryptoTLSCreds *tlscreds, 483 const char *tlshostname); 484 void nbd_client_connection_release(NBDClientConnection *conn); 485 486 QIOChannel *coroutine_fn 487 nbd_co_establish_connection(NBDClientConnection *conn, NBDExportInfo *info, 488 bool blocking, Error **errp); 489 490 void nbd_co_establish_connection_cancel(NBDClientConnection *conn); 491 492 #endif 493