struct_obd_connect_data.txt

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