export.txt

   1 Export
   2 ^^^^^^
   3 [[obd-export]]
   4 An 'obd_export' structure for a given target is created on a server
   5 for each client that connects to that target. The exports for all the
   6 clients for a given target are managed together. The export represents
   7 the connection state between the client and target as well as the
   8 current state of any ongoing activity. Thus each pending request will
   9 have a reference to the export. The export is discarded if the
  10 connection goes away, but only after all the references to it have
  11 been cleaned up. Some state information for each export is also
  12 maintained on disk. In the event of a server failure and recovery,
  13 the server can read the export data from disk to allow the client
  14 to reconnect and participate in recovery, otherwise a client without
  15 any export data will not be allowed to participate in recovery.
  16
  17 ----
  18 struct obd_export {
  19         struct portals_handle     exp_handle;
  20         struct obd_uuid           exp_client_uuid;
  21         struct obd_connect_data   exp_connect_data;
  22 };
  23 ----
  24
  25 //////////////////////////////////////////////////////////////////////
  26 ////vvvv
  27 This is the full obd_export.
  28
  29 struct obd_export {
  30         struct portals_handle     exp_handle;
  31         atomic_t   exp_refcount;
  32         atomic_t   exp_rpc_count;
  33         atomic_t   exp_cb_count;
  34         atomic_t   exp_replay_count;
  35         atomic_t   exp_locks_count;
  36         struct obd_uuid           exp_client_uuid;
  37         cfs_list_t exp_obd_chain;
  38         cfs_hlist_node_t      exp_uuid_hash;
  39         cfs_hlist_node_t      exp_nid_hash;
  40         cfs_list_t            exp_obd_chain_timed;
  41         struct obd_device    *exp_obd;
  42         struct obd_import    *exp_imp_reverse;
  43         struct nid_stat      *exp_nid_stats;
  44         struct ptlrpc_connection *exp_connection;
  45         __u32       exp_conn_cnt;
  46         cfs_hash_t *exp_lock_hash;
  47         cfs_hash_t *exp_flock_hash;
  48         cfs_list_t  exp_outstanding_replies;
  49         cfs_list_t  exp_uncommitted_replies;
  50         spinlock_t  exp_uncommitted_replies_lock;
  51         __u64       exp_last_committed;
  52         cfs_time_t  exp_last_request_time;
  53         cfs_list_t  exp_req_replay_queue;
  54         spinlock_t  exp_lock;
  55         struct obd_connect_data   exp_connect_data;
  56         enum obd_option       exp_flags;
  57         unsigned long
  58                 exp_failed:1,
  59                 exp_in_recovery:1,
  60                 exp_disconnected:1,
  61                 exp_connecting:1,
  62                 exp_delayed:1,
  63                 exp_vbr_failed:1,
  64                 exp_req_replay_needed:1,
  65                 exp_lock_replay_needed:1,
  66                 exp_need_sync:1,
  67                 exp_flvr_changed:1,
  68                 exp_flvr_adapt:1,
  69                 exp_libclient:1,
  70                 exp_need_mne_swab:1;
  71         enum lustre_sec_part      exp_sp_peer;
  72         struct sptlrpc_flavor     exp_flvr;
  73         struct sptlrpc_flavor     exp_flvr_old[2];
  74         cfs_time_t exp_flvr_expire[2];
  75         spinlock_t exp_rpc_lock;
  76         cfs_list_t exp_hp_rpcs;
  77         cfs_list_t exp_reg_rpcs;
  78         cfs_list_t exp_bl_list;
  79         spinlock_t exp_bl_list_lock;
  80         union {
  81                 struct tg_export_data     eu_target_data;
  82                 struct mdt_export_data    eu_mdt_data;
  83                 struct filter_export_data eu_filter_data;
  84                 struct ec_export_data     eu_ec_data;
  85                 struct mgs_export_data    eu_mgs_data;
  86         } u;
  87         struct nodemap      *exp_nodemap;
  88 };
  89 ////^^^^
  90 //////////////////////////////////////////////////////////////////////
  91
  92 The 'exp_handle' holds the cookie that the server generates at
  93 *_CONNECT time to uniquely identify this connection from the client.
  94 This cookie is also sent back to the client in the reply and is
  95 then stored in the client's import.
  96
  97 //////////////////////////////////////////////////////////////////////
  98 ////vvvv
  99 The 'exp_refcount' gets incremented whenever some aspect of the export
 100 is "in use". The arrival of an otherwise unprocessed message for this
 101 target will increment the refcount. A reference by an LDLM lock that
 102 gets taken will increment the refcount. Callback invocations and
 103 replay also lead to incrementing the 'ref_count'. The next four fields
 104 - 'exp_rpc_count', exp_cb_count', and 'exp_replay_count', and
 105 'exp_locks_count' - all subcategorize the 'exp_refcount'. The
 106 reference counter keeps the export alive while there are any users of
 107 that export. The reference counter is also used for debug
 108 purposes. Similarly, the 'exp_locks_list' and 'exp_locks_list_guard'
 109 are further debug info that list the actual locks accounted for in
 110 'exp_locks_count'.
 111 ////^^^^
 112 //////////////////////////////////////////////////////////////////////
 113
 114 The 'exp_client_uuid' holds the UUID of the client connected to this
 115 export.  This UUID is randomly generated by the client and the same
 116 UUID is used by the client for connecting to all servers, so that
 117 the servers may identify the client amongst themselves if necessary.
 118
 119 //////////////////////////////////////////////////////////////////////
 120 ////vvvv
 121 The server maintains all the exports for a given target on a circular
 122 list. Each export's place on that list is maintained in the
 123 'exp_obd_chain'. A common activity is to look up the export based on
 124 the UUID or the nid of the client, and the 'exp_uuid_hash' and
 125 'exp_nid_hash' fields maintain this export's place in hashes
 126 constructed for that purpose.
 127
 128 Exports are also maintained on a list sorted by the last time the
 129 corresponding client was heard from. The 'exp_obd_chain_timed' field
 130 maintains the export's place on that list. When a message arrives from
 131 the client the time is "now" so the export gets put at the end of the
 132 list. Since it is circular, the next export is then the oldest. If it
 133 has not been heard of within its timeout interval that export is
 134 marked for later eviction.
 135
 136 The 'exp_obd' points to the 'obd_device' structure for the device that
 137 is the target of this export.
 138
 139 In the event of an LDLM call-back the export needs to have a the ability to
 140 initiate messages back to the client. The 'exp_imp_reverse' provides a
 141 "reverse" import that manages this capability.
 142
 143 The '/proc' stats for the export (and the target) get updated via the
 144 'exp_nid_stats'.
 145
 146 The 'exp_connection' points to the connection information for this
 147 export. This is the information about the actual networking pathway(s)
 148 that get used for communication.
 149
 150 The 'exp_conn_cnt' notes the connection count value from the client at
 151 the time of the connection. In the event that more than one connection
 152 request is issued before the connection is established then the
 153 'exp_conn_cnt' will list the highest value. If a previous connection
 154 attempt (with a lower value) arrives later it may be safely
 155 discarded. Every request lists its connection count, so non-connection
 156 requests with lower connection count values can also be discarded.
 157 Note that this does not count how many times the client has connected
 158 to the target. If a client is evicted the export is deleted once it
 159 has been cleaned up and its 'exp_ref_count' reduced to zero. A new
 160 connection from the client will get a new export.
 161
 162 The 'exp_lock_hash' provides access to the locks granted to the
 163 corresponding client for this target. If a lock cannot be granted it
 164 is discarded. A file system lock ("flock") is also implemented through
 165 the LDLM lock system, but not all LDLM locks are flocks. The ones that
 166 are flocks are gathered in a hash 'exp_flock_hash'. This supports
 167 deadlock detection.
 168
 169 For those requests that initiate file system modifying transactions
 170 the request and its attendant locks need to be preserved until either
 171 a) the client acknowleges recieving the reply, or b) the transaction
 172 has been committed locally. This ensures a request can be replayed in
 173 the event of a failure. The LDLM lock is being kept until one of these
 174 event occurs to prevent any other modifications of the same object.
 175 The reply is kept on the 'exp_outstanding_replies' list until the LNet
 176 layer notifies the server that the reply has been acknowledged. A reply
 177 is kept on the 'exp_uncommitted_replies' list until the transaction
 178 (if any) has been committed.
 179
 180 The 'exp_last_committed' value keeps the transaction number of the
 181 last committed transaction. Every reply to a client includes this
 182 value as a means of early-as-possible notification of transactions that
 183 have been committed.
 184
 185 The 'exp_last_request_time' is self explanatory.
 186
 187 During reply a request that is waiting for reply is maintained on the
 188 list 'exp_req_replay_queue'.
 189
 190 The 'exp_lock' spin-lock is used for access control to the exports
 191 flags, as well as the 'exp_outstanding_replies' list and the revers
 192 import, if any.
 193 ////^^^^
 194 //////////////////////////////////////////////////////////////////////
 195
 196 The 'exp_connect_data' refers to an 'obd_connect_data' structure for
 197 the connection established between this target and the client this
 198 export refers to.  The 'exp_connect_data' describes the mutually
 199 supported features that were negotiated between the client and server
 200 at connect time.  See also the corresponding entry in the import and
 201 in the connect messages passed between the hosts.
 202
 203 //////////////////////////////////////////////////////////////////////
 204 ////vvvv
 205 The 'exp_flags' field encodes three directives as follows:
 206 ----
 207 enum obd_option {
 208         OBD_OPT_FORCE =         0x0001,
 209         OBD_OPT_FAILOVER =      0x0002,
 210         OBD_OPT_ABORT_RECOV =   0x0004,
 211 };
 212 ----
 213 fixme: Are the set for some exports and a condition of their
 214 existence? or do they reflect a transient state the export is passing
 215 through?
 216
 217 The 'exp_failed' flag gets set whenever the target has failed for any
 218 reason or the export is otherwise due to be cleaned up. Once set it
 219 will not be unset in this export. Any subsequent connection between
 220 the client and the target would be governed by a new export.
 221
 222 After a failure export data is retrieved from disk and the exports
 223 recreated. Exports created in this way will have their
 224 'exp_in_recovery' flag set. Once any outstanding requests and locks
 225 have been recovered for the client, then the export is recovered and
 226 'exp_in_recovery' can be cleared. When all the client exports for a
 227 given target have been recovered then the target is considered
 228 recovered, and when all targets have been recovered the server is
 229 considered recovered.
 230
 231 A *_DISCONNECT message from the client will set the 'exp_disconnected'
 232 flag, as will any sort of failure of the target. Once set the export
 233 will be cleaned up and deleted.
 234
 235 When a *_CONNECT message arrives the 'exp_connecting' flag is set. If
 236 for some reason a second *_CONNECT request arrives from the client it can
 237 be discarded when this flag is set.
 238
 239 The 'exp_delayed' flag is no longer used. In older code it indicated
 240 that recovery had not completed in a timely fashion, but that a tardy
 241 recovery would still be possible, since there were no dependencies on
 242 the export.
 243
 244 The 'exp_vbr_failed' flag indicates a failure during the recovery
 245 process. See <<recovery>> for a more detailed discussion of recovery
 246 and transaction replay. For a file system modifying request, the
 247 server composes its reply including the 'pb_pre_versions' entries in
 248 'ptlrpc_body', which indicate the most recent updates to the
 249 object. The client updates the request with the 'pb_transno' and
 250 'pb_pre_versions' from the reply, and keeps that request until the
 251 target signals that the transaction has been committed to disk. If the
 252 client times-out without that confirmation then it will 'replay' the
 253 request, which now includes the 'pb_pre_versions' information. During
 254 a replay the target checks that the object has the same version as
 255 'pb_pre_versions' in replay. If this check fails then the object can't
 256 be restored in the same state as it was in before failure. Usually that
 257 happens if the recovery process fails for the connection between some
 258 other client and this target, so part of change needed for this client
 259 wasn't restored. At that point the 'exp_vbr_failed' flag is set
 260 to indicate version based recovery failed. This will lead to the client
 261 being evicted and this export being cleaned up and deleted.
 262
 263 At the start of recovery both the 'exp_req_replay_needed' and
 264 'exp_lock_replay_needed' flags are set. As request replay is completed
 265 the 'exp_req_replay_needed' flag is cleared. As lock replay is
 266 completed the 'exp_lock_replay_needed' flag is cleared. Once both are
 267 cleared the 'exp_in_recovery' flag can be cleared.
 268
 269 The 'exp_need_sync' supports an optimization. At mount time it is
 270 likely that every client (potentially thousands) will create an export
 271 and that export will need to be saved to disk synchronously. This can
 272 lead to an unusually high and poorly performing interaction with the
 273 disk. When the export is created the 'exp_need_sync' flag is set and
 274 the actual writing to disk is delayed. As transactions arrive from
 275 clients (in a much less coordinated fashion) the 'exp_need_sync' flag
 276 indicates a need to have the export data on disk before proceeding
 277 with a new transaction, so as it is next updated the transaction is
 278 done synchronously to commit all changes on disk. At that point the
 279 flag is cleared (except see below).
 280
 281 In DNE (phase I) the export for an MDT managing the connection from
 282 another MDT will want to always keep the 'exp_need_sync' flag set. For
 283 that special case such an export sets the 'exp_keep_sync', which then
 284 prevents the 'exp_need_sync' flag from ever being cleared. This will
 285 no longer be needed in DNE Phase II.
 286
 287 The 'exp_flvr_changed' and 'exp_flvr_adapt' flags along with
 288 'exp_sp_peer', 'exp_flvr', 'exp_flvr_old', and 'exp_flvr_expire'
 289 fields are all used to manage the security settings for the
 290 connection. Security is discussed in the <<security>> section. (fixme:
 291 or will be.)
 292
 293 The 'exp_libclient' flag indicates that the export is for a client
 294 based on "liblustre". This allows for simplified handling on the
 295 server. (fixme: how is processing simplified? It sounds like I may
 296 need a whole special section on liblustre.)
 297
 298 The 'exp_need_mne_swab' flag indicates the presence of an old bug that
 299 affected one special case of failed swabbing. It is not part of
 300 current processing.
 301
 302 As RPCs arrive they are first subjected to triage. Each request is
 303 placed on the 'exp_hp_rpcs' list and examined to see if it is high
 304 priority (PING, truncate, bulk I/O). If it is not high priority then
 305 it is moved to the 'exp_reg_prcs' list. The 'exp_rpc_lock' protects
 306 both lists from concurrent access.
 307
 308 All arriving LDLM requests get put on the 'exp_bl_list' and access to
 309 that list is controlled via the 'exp_bl_list_lock'.
 310
 311 The union provides for target specific data. The 'eu_target_data' is
 312 for a common core of fields for a generic target. The others are
 313 specific to particular target types: 'eu_mdt_data' for MDTs,
 314 'eu_filter_data' for OSTs, 'eu_ec_data' for an "echo client" (fixme:
 315 describe what an echo client is somewhere), and 'eu_mgs_data' is for
 316 an MGS.
 317
 318 The 'exp_bl_lock_at' field supports adaptive timeouts which will be
 319 discussed separately. (fixme: so discuss it somewhere.)
 320 ////^^^^
 321 //////////////////////////////////////////////////////////////////////