obd_connect_data.txt

   1 OBD Connect Data
   2 ^^^^^^^^^^^^^^^^
   3 [[obd-connect-data]]
   4
   5 An 'obd_connect_data' structure accompanies every connect operation in
   6 both the request message and in the reply message.
   7
   8 ----
   9 struct obd_connect_data {
  10     __u64 ocd_connect_flags;
  11     __u32 ocd_version;      /* OBD_CONNECT_VERSION */
  12     __u32 ocd_grant;        /* OBD_CONNECT_GRANT */
  13     __u32 ocd_index;        /* OBD_CONNECT_INDEX */
  14     __u32 ocd_brw_size;     /* OBD_CONNECT_BRW_SIZE */
  15     __u64 ocd_ibits_known;  /* OBD_CONNECT_IBITS */
  16     __u8  ocd_blocksize;    /* OBD_CONNECT_GRANT_PARAM */
  17     __u8  ocd_inodespace;   /* OBD_CONNECT_GRANT_PARAM */
  18     __u16 ocd_grant_extent; /* OBD_CONNECT_GRANT_PARAM */
  19     __u32 ocd_unused;
  20     __u64 ocd_transno;      /* OBD_CONNECT_TRANSNO */
  21     __u32 ocd_group;        /* OBD_CONNECT_MDS */
  22     __u32 ocd_cksum_types;  /* OBD_CONNECT_CKSUM */
  23     __u32 ocd_max_easize;   /* OBD_CONNECT_MAX_EASIZE */
  24     __u32 ocd_instance;
  25     __u64 ocd_maxbytes;     /* OBD_CONNECT_MAXBYTES */
  26     __u64 padding1;
  27     __u64 padding2;
  28     __u64 padding3;
  29     __u64 padding4;
  30     __u64 padding5;
  31     __u64 padding6;
  32     __u64 padding7;
  33     __u64 padding8;
  34     __u64 padding9;
  35     __u64 paddingA;
  36     __u64 paddingB;
  37     __u64 paddingC;
  38     __u64 paddingD;
  39     __u64 paddingE;
  40     __u64 paddingF;
  41 };
  42 ----
  43
  44 The 'ocd_connect_flags' field encodes the connect flags giving the
  45 capabilities of a connection between client and target. Several of
  46 those flags (noted in comments above and the discussion below)
  47 actually control whether the remaining fields of 'obd_connect_data'
  48 get used. The [[connect-flags]] flags are:
  49
  50 ----
  51 #define OBD_CONNECT_RDONLY                0x1ULL /*client has read-only access*/
  52 #define OBD_CONNECT_INDEX                 0x2ULL /*connect specific LOV idx */
  53 #define OBD_CONNECT_MDS                   0x4ULL /*connect from MDT to OST */
  54 #define OBD_CONNECT_GRANT                 0x8ULL /*OSC gets grant at connect */
  55 #define OBD_CONNECT_SRVLOCK              0x10ULL /*server takes locks for cli */
  56 #define OBD_CONNECT_VERSION              0x20ULL /*Lustre versions in ocd */
  57 #define OBD_CONNECT_REQPORTAL            0x40ULL /*Separate non-IO req portal */
  58 #define OBD_CONNECT_ACL                  0x80ULL /*access control lists */
  59 #define OBD_CONNECT_XATTR               0x100ULL /*client use extended attr */
  60 #define OBD_CONNECT_CROW                0x200ULL /*MDS+OST create obj on write*/
  61 #define OBD_CONNECT_TRUNCLOCK           0x400ULL /*locks on server for punch */
  62 #define OBD_CONNECT_TRANSNO             0x800ULL /*replay sends init transno */
  63 #define OBD_CONNECT_IBITS              0x1000ULL /*support for inodebits locks*/
  64 #define OBD_CONNECT_JOIN               0x2000ULL /*files can be concatenated.
  65                                                   *We do not support JOIN FILE
  66                                                   *anymore, reserve this flags
  67                                                   *just for preventing such bit
  68                                                   *to be reused.*/
  69 #define OBD_CONNECT_ATTRFID            0x4000ULL /*Server can GetAttr By Fid*/
  70 #define OBD_CONNECT_NODEVOH            0x8000ULL /*No open hndl on specl nodes*/
  71 #define OBD_CONNECT_RMT_CLIENT        0x10000ULL /*Remote client */
  72 #define OBD_CONNECT_RMT_CLIENT_FORCE  0x20000ULL /*Remote client by force */
  73 #define OBD_CONNECT_BRW_SIZE          0x40000ULL /*Max bytes per rpc */
  74 #define OBD_CONNECT_QUOTA64           0x80000ULL /*Not used since 2.4 */
  75 #define OBD_CONNECT_MDS_CAPA         0x100000ULL /*MDS capability */
  76 #define OBD_CONNECT_OSS_CAPA         0x200000ULL /*OSS capability */
  77 #define OBD_CONNECT_CANCELSET        0x400000ULL /*Early batched cancels. */
  78 #define OBD_CONNECT_SOM              0x800000ULL /*Size on MDS */
  79 #define OBD_CONNECT_AT              0x1000000ULL /*client uses AT */
  80 #define OBD_CONNECT_LRU_RESIZE      0x2000000ULL /*LRU resize feature. */
  81 #define OBD_CONNECT_MDS_MDS         0x4000000ULL /*MDS-MDS connection */
  82 #define OBD_CONNECT_REAL            0x8000000ULL /*real connection */
  83 #define OBD_CONNECT_CHANGE_QS      0x10000000ULL /*Not used since 2.4 */
  84 #define OBD_CONNECT_CKSUM          0x20000000ULL /*support several cksum algos*/
  85 #define OBD_CONNECT_FID            0x40000000ULL /*FID is supported by server */
  86 #define OBD_CONNECT_VBR            0x80000000ULL /*version based recovery */
  87 #define OBD_CONNECT_LOV_V3        0x100000000ULL /*client supports LOV v3 EA */
  88 #define OBD_CONNECT_GRANT_SHRINK  0x200000000ULL /* support grant shrink */
  89 #define OBD_CONNECT_SKIP_ORPHAN   0x400000000ULL /* don't reuse orphan objids */
  90 #define OBD_CONNECT_MAX_EASIZE    0x800000000ULL /* preserved for large EA */
  91 #define OBD_CONNECT_FULL20       0x1000000000ULL /* it is 2.0 client */
  92 #define OBD_CONNECT_LAYOUTLOCK   0x2000000000ULL /* client uses layout lock */
  93 #define OBD_CONNECT_64BITHASH    0x4000000000ULL /* client supports 64-bits
  94                                                   * directory hash */
  95 #define OBD_CONNECT_MAXBYTES     0x8000000000ULL /* max stripe size */
  96 #define OBD_CONNECT_IMP_RECOV   0x10000000000ULL /* imp recovery support */
  97 #define OBD_CONNECT_JOBSTATS    0x20000000000ULL /* jobid in ptlrpc_body */
  98 #define OBD_CONNECT_UMASK       0x40000000000ULL /* create uses client umask */
  99 #define OBD_CONNECT_EINPROGRESS 0x80000000000ULL /* client handles -EINPROGRESS
 100                                                   * RPC error properly */
 101 #define OBD_CONNECT_GRANT_PARAM 0x100000000000ULL/* extra grant params used for
 102                                                   * finer space reservation */
 103 #define OBD_CONNECT_FLOCK_OWNER 0x200000000000ULL /* for the fixed 1.8
 104                            * policy and 2.x server */
 105 #define OBD_CONNECT_LVB_TYPE    0x400000000000ULL /* variable type of LVB */
 106 #define OBD_CONNECT_NANOSEC_TIME 0x800000000000ULL /* nanosecond timestamps */
 107 #define OBD_CONNECT_LIGHTWEIGHT 0x1000000000000ULL/* lightweight connection */
 108 #define OBD_CONNECT_SHORTIO     0x2000000000000ULL/* short io */
 109 #define OBD_CONNECT_PINGLESS    0x4000000000000ULL/* pings not required */
 110 #define OBD_CONNECT_FLOCK_DEAD    0x8000000000000ULL/* deadlock detection */
 111 #define OBD_CONNECT_DISP_STRIPE 0x10000000000000ULL/* create stripe disposition*/
 112 #define OBD_CONNECT_OPEN_BY_FID    0x20000000000000ULL /* open by fid won't pack
 113                                name in request */
 114 ----
 115
 116 Each flag corresponds to a particular capability that the client and
 117 target together will honor. A client will send a message including
 118 some subset of these capabilities during a connection request to a
 119 specific target. It tells the server what capabilities it has. The
 120 server then replies with the subset of those capabilities it agrees to
 121 honor (for the given target).
 122
 123 If the OBD_CONNECT_VERSION flag is set then the 'ocd_version' field is
 124 honored. The 'ocd_version' gives an encoding of the Lustre
 125 version. For example, Version 2.7.32 would be hexadecimal number
 126 0x02073200.
 127
 128 If the OBD_CONNECT_GRANT flag is set then the 'ocd_grant' field is
 129 honored. The 'ocd_grant' value in a reply (to a connection request)
 130 sets the client's grant.
 131
 132 If the OBD_CONNECT_INDEX flag is set then the 'ocd_index' field is
 133 honored. The 'ocd_index' value is set in a reply to a connection
 134 request. It holds the LOV index of the target.
 135
 136 If the OBD_CONNECT_BRW_SIZE flag is set then the 'ocd_brw_size' field
 137 is honored. The 'ocd_brw_size' value sets the size of the maximum
 138 supported RPC. The client proposes a value in its connection request,
 139 and the server's reply will either agree or further limit the size.
 140
 141 If the OBD_CONNECT_IBITS flag is set then the 'ocd_ibits_known' field
 142 is honored. The 'ocd_ibits_known' value determines the handling of
 143 locks on inodes. See the discussion of inodes and extended attributes.
 144
 145 If the OBD_CONNECT_GRANT_PARAM flag is set then the 'ocd_blocksize',
 146 'ocd_inodespace', and 'ocd_grant_extent' fields are honored. A server
 147 reply uses the 'ocd_blocksize' value to inform the client of the log
 148 base two of the size in bytes of the backend file system's blocks.
 149
 150 A server reply uses the 'ocd_inodespace' value to inform the client of
 151 the log base two of the size of an inode.
 152
 153 Under some circumstances (for example when ZFS is the back end file
 154 system) there may be additional overhead in handling writes for each
 155 extent. The server uses the 'ocd_grant_extent' value to inform the
 156 client of the size in bytes consumed from its grant on the server when
 157 creating a new file. The client uses this value in calculating how
 158 much dirty write cache it has and whether it has reached the limit
 159 established by the target's grant.
 160
 161 If the OBD_CONNECT_TRANSNO flag is set then the 'ocd_transno' field is
 162 honored. A server uses the 'ocd_transno' value during recovery to
 163 inform the client of the transaction number at which it should begin
 164 replay.
 165
 166 If the OBD_CONNECT_MDS flag is set then the 'ocd_group' field is
 167 honored. When an MDT connects to an OST the 'ocd_group' field informs
 168 the OSS of the MDT's index. Objects on that OST for that MDT will be
 169 in a common namespace served by that MDT.
 170
 171 If the OBD_CONNECT_CKSUM flag is set then the 'ocd_cksum_types' field
 172 is honored. The client uses the 'ocd_checksum_types' field to propose
 173 to the server the client's available (presumably hardware assisted)
 174 checksum mechanisms. The server replies with the checksum types it has
 175 available. Finally, the client will employ the fastest of the agreed
 176 mechanisms.
 177
 178 If the OBD_CONNECT_MAX_EASIZE flag is set then the 'ocd_max_easize'
 179 field is honored. The server uses 'ocd_max_easize' to inform the
 180 client about the amount of space that can be allocated in each inode
 181 for extended attributes. The 'ocd_max_easize' specifically refers to
 182 the space used for striping information. This allows the client to
 183 determine the maximum layout size (and hence stripe count) that can be
 184 stored on the MDT.
 185
 186 The 'ocd_instance' field (alone) is not governed by an OBD_CONNECT_*
 187 flag. The MGS uses the 'ocd_instance' value in its reply to a
 188 connection request to inform the server and target of the "era" of its
 189 connection. The MGS initializes the era value for each server to zero
 190 and increments that value every time the target connects. This
 191 supports imperative recovery.
 192
 193 If the OBD_CONNECT_MAXBYTES flag is set then the 'ocd_maxbytes' field
 194 is honored. An OSS uses the 'ocd_maxbytes' value to inform the client
 195 of the maximum OST object size for this target.  A stripe on any OST
 196 for a multi-striped file cannot be larger than the minimum maxbytes
 197 value.
 198
 199 The additional space in the 'obd_connect_data' structure is unused and
 200 reserved for future use.
 201
 202 Other OBD_CONNECT_* flags have no corresponding field in
 203 obd_connect_data but still control client-server supported features.
 204
 205 If the OBD_CONNECT_RDONLY flag is set then the client is mounted in
 206 read-only mode and the server honors that by denying any modification
 207 from this client.
 208
 209 If the OBD_CONNECT_SRVLOCK flag is set then the client and server
 210 support lockless IO. The server will take locks for client IO requests
 211 with the OBD_BRW_SRVLOCK flag in the 'niobuf_remote' structure
 212 flags. This is used for Direct IO.  The client takes no LDLM lock and
 213 delegates locking to the server.
 214
 215 If the OBD_CONNECT_ACL flag is set then the server supports the ACL
 216 mount option for its filesystem. The client supports this mount option
 217 as well, in that case.
 218
 219 If the OBD_CONNECT_XATTR flag is set then the server supports user
 220 extended attributes. This is defined by the mount options of the
 221 servers of the backend file systems and is reflected on the client
 222 side by the same mount option but for the Lustre file system itself.
 223
 224 If the OBD_CONNECT_TRUNCLOCK flag is set then the client and the
 225 server support lockless truncate. This is realized in an OST_PUNCH RPC
 226 by setting the 'obdo' sturcture's 'o_flag' field to include the
 227 OBD_FL_SRVLOCK. In that circumstance the client takes no lock, and the
 228 server must take a lock on the resource.
 229
 230 If the OBD_CONNECT_ATTRFID flag is set then the server supports
 231 getattr requests by FID of file instead of name. This reduces
 232 unnecessary RPCs for DNE.
 233
 234 If the OBD_CONNECT_NODEVOH flag is set then the server provides no
 235 open handle for special inodes.
 236
 237 If the OBD_CONNECT_RMT_CLIENT is set then the client is set as
 238 'remote' with respect to the server. The client is considered as
 239 'local' if the user/group database on the client is identical to that
 240 on the server, otherwise the client is set as 'remote'. This
 241 terminology is part of Lustre Kerberos feature which is not supported
 242 now.
 243
 244 If the OBD_CONNECT_RMT_CLIENT_FORCE is set then client is set as
 245 remote client forcefully. If the server security level doesn't support
 246 remote clients then this client connect reply will return an -EACCESS
 247 error.
 248
 249 If the OBD_CONNECT_MDS_CAPA is set then MDS supports capability.
 250 Capabilities are part of Lustre Kerberos. The MDS prepares the
 251 capability when a file is opened and sends it to a client. A client
 252 has to present a capability when it wishes to perform an operation on
 253 that object.
 254
 255 If the OBD_CONNECT_OSS_CAPA is set then OSS supports capability.
 256 Capabilities are part of Lustre Kerberos. When the clients request the
 257 OSS to perform a modification operations on objects the capability
 258 authorizes these operations.
 259
 260 If the OBD_CONNECT_CANCELSET is set then early batched cancels are
 261 enabled.  The ELC (Early Lock Cancel) feature allows client locks to
 262 be cancelled prior the cancellation callback if it is clear that lock
 263 is not needed anymore, for example after rename, after removing file
 264 or directory, link, etc. This can reduce amount of RPCs significantly.
 265
 266 If the OBD_CONNECT_AT is set then client and server use Adaptive
 267 Timeout while request processing. Servers keep track of the RPCs
 268 processing time and report this information back to clients to
 269 estimate the time needed for future requests and set appropriate RPC
 270 timeouts.
 271
 272 If the OBD_CONNECT_LRU_RESIZE is set then the LRU self-adjusting is
 273 enabled.  This is set by the Lustre configurable option
 274 --enable-lru-resize, and is enabled by default.
 275
 276 If the OBD_CONNECT_FID is set then FID support is required by
 277 server. This compatibility flag was introduced in Lustre 2.0. All
 278 servers and clients are using FIDs nowadays. This flag is always set
 279 on server and used to filter out clients without FID support.
 280
 281 If the OBD_CONNECT_VBR is set then version based recovery is used on
 282 server.  The VBR uses an object version to track its changes on the
 283 server and to decide if the replay can be applied during recovery
 284 based on that version. This helps to complete recovery even if some
 285 clients were missed or evicted. That flag is always set on server
 286 since Lustre 1.8 and is used just to notify the server if client
 287 doesn't support VBR.
 288
 289 If the OBD_CONNECT_LOV_V3 is set then the client supports LOV vs
 290 EA. This type of the LOV extended attribute was introduced along with
 291 OST pools support and changed the internal structure of that EA. The
 292 OBD_CONNECT_LOV_V3 flag notifies a server if client doesn't support
 293 this type of LOV EA to handle requests from it properly.
 294
 295 If the OBD_CONNECT_GRANT_SHRINK is set then the client can release
 296 grant space when idle.
 297
 298 If the OBD_CONNECT_SKIP_ORPHAN is set then OST doesn't reuse orphan
 299 object ids after recovery. This connection flag is used between MDS
 300 and OST to agree about an object pre-creation policy after MDS
 301 recovery. If some of precreated objects weren't used but an MDT was
 302 restarted then an OST may re-use not used objects for new pre-create
 303 request or may not. The latter is preferred and is used by default
 304 nowadays.
 305
 306 If the OBD_CONNECT_FULL20 is set then the client is Lustre 2.x client.
 307 Clients that are using old 1.8 format protocol conventions are not
 308 allowed to connect. This flag should be set on all connections since
 309 2.0, it is no longer affects behaviour and will be disabled completely
 310 once Lustre interoperation with old clients is no longer needed.
 311
 312 If the OBD_CONNECT_LAYOUTLOCK is set then the client supports layout
 313 lock. The server will not grant a layout lock to the old clients
 314 having no such flag.
 315
 316 If the OBD_CONNECT_64BITHASH is set then the client supports 64-bit
 317 directory hash. The server will also use 64-bit hash mode while
 318 working with ldiskfs.
 319
 320 If the OBD_CONNECT_JOBSTATS is set then the client fills jobid in
 321 'ptlrpc_body' so server can provide extended statistics per jobid.
 322
 323 If the OBD_CONNECT_UMASK is set then create uses client umask. This is
 324 default flag for MDS but not for OST.
 325
 326 If the OBD_CONNECT_LVB_TYPE is set then the variable type of LVB is
 327 supported by a client. This flag was introduced along with DNE to
 328 recognize DNE-aware clients.
 329
 330 If the OBD_CONNECT_LIGHTWEIGHT is set then this connection is the
 331 'lightweight' one. A lightweight connection has no entry in last_rcvd
 332 file, so no recovery is possible, at the same time a lightweight
 333 connection can be set up while the target is in recovery, locks can
 334 still be acquired through this connection, although they won't be
 335 replayed. Such type of connection is used by services like quota
 336 manager, FLDB, etc.
 337
 338 If the OBD_CONNECT_PINGLESS is set then pings can be suppressed. If
 339 the client and server have this flag during connection and the ptlrpc
 340 module on server has the option "suppress_pings", then pings will be
 341 suppressed for this client.  There must be an external mechanism to
 342 notify the targets of client deaths, via the targets "evict_client"
 343 'procfs' entries. Pings can be disabled on OSTs only.
 344
 345 If the OBD_CONNECT_FLOCK_DEAD is set then the client support flock
 346 cancellation, which is used for the flock deadlock detection mechanism.
 347
 348 If the OBD_CONNECT_DISP_STRIPE is set then server returns a 'create
 349 stripe' disposition for open request from the client. This helps to
 350 optimize a recovery of open requests.
 351
 352 If the OBD_CONNECT_OPEN_BY_FID is set then an open by FID won't pack
 353 the name in a request. This is used by DNE.
 354
 355 If the OBD_CONNECT_MDS_MDS is set then the current connection is a
 356 MDS-MDS one. Such connections are distinguished because they provide
 357 more functionality specific to MDS-MDS interoperation.
 358
 359 If the OBD_CONNECT_IMP_RECOV is set then the Imperative Recovery is
 360 supported. Imperative recovery means the clients are notified
 361 explicitly when and where a failed target has restarted.
 362
 363 The OBD_CONNECT_REQPORTAL was used to specify that client may use
 364 OST_REQUEST_PORTAL for requests to don't interfere with IO portal,
 365 e.g. for MDS-OST interaction. Now it is default request portal for OSC
 366 and this flag does nothing though it is still set on client side
 367 during connection process.
 368
 369 The OBD_CONNECT_CROW flag was used for create-on-write functionality
 370 on OST, when data objects were created upon first write from the
 371 client. This wasn't implemented because of complex recovery problems.
 372
 373 The OBD_CONNECT_SOM flag was used to signal that MDS is capable to
 374 store file size in file attributes, so client may get it directly from
 375 MDS avoiding glimpse request to OSTs. This feature was implemented as
 376 demo feature and wasn't enabled by default. Finally it was disabled in
 377 Lustre 2.7 because it causes quite complex recovery cases to handle
 378 with relatevely small benefits.
 379
 380 The OBD_CONNECT_JOIN flag was used for the 'join files' feature, which
 381 allowed files to be concatenated. Lustre no longer supports that
 382 feature.
 383
 384 The OBD_CONNECT_QUOTA64 was used prior Lustre 2.4 for quota purposes,
 385 it is obsoleted due to new quota design.
 386
 387 The OBD_CONNECT_REAL is not real connection flag but used locally on
 388 client to distinguish real connection from local connections between
 389 layers.
 390
 391 The OBD_CONNECT_CHANGE_QS was used prior Lustre 2.4 for quota needs
 392 and it is obsoleted now due to new quota design.
 393
 394 If the OBD_CONNECT_EINPROGRESS is set then client handles -EINPROGRESS
 395 RPC error properly. The quota design requires that client must resend
 396 request with -EINPROGRESS error indefinitely, until successful
 397 completion or another error.  This flag is set on both client and
 398 server by default. Meanwhile this flag is not checked anywere, so does
 399 nothing.
 400
 401 If the OBD_CONNECT_FLOCK_OWNER is set then 1.8 clients has fixed flock
 402 policy and 2.x servers recognize them correctly. Meanwhile this flag
 403 is not checked anywhere, so does nothing.
 404
 405 If the OBD_CONNECT_NANOSEC_TIME is set then nanosecond timestamps are
 406 enabled.  This flag is not used nowadays, but reserved for future use.
 407
 408 If the OBD_CONNECT_SHORTIO is set then short IO feature is enabled on
 409 server.  The server will avoid bulk IO for small amount of data but
 410 data is incapsulated into ptlrpc request/reply. This flag is just
 411 reserved for future use and does nothing nowadays.