-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi List,
Based on recent feedback, I'm proposing to split byte-range locking from delegation (Delegation should return here in future, as an updated extension draft.) Other changes include: * 64-bit Uniq attribute * Opaque Txid and Token attributes added for future use * Discussion of expected assert-extend lock interactions, periodically and across server restarts * Improved language in a number of areas (we hope) Regards, Matt - -- Matt Benjamin The Linux Box 206 South Fifth Ave. Suite 150 Ann Arbor, MI 48104 http://linuxbox.com tel. 734-761-4689 fax. 734-769-8938 cel. 734-216-5309 -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.7 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFJedxfJiSUUSaRdSURCJK+AJ9dIwhEp1ChWN61v5k0EGazwsW4SwCdH0Xa d5YrsHPvkA09wbRQ2Z7Xhrw= =G8Nz -----END PGP SIGNATURE-----
AFS Byte-Range Locking Matt Benjamin <[email protected]> 01/22/2009 Status of this Memo This document specifies a standards track protocol extension for the OpenAFS community, and requests discussion and suggestions for improvements. Key Words The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in Internet Engineering Task Force RFC 2119. Abstract The AFS-3 protocol supports file locks, but only on whole files, only in advisory mode, and using an inefficient protocol. Efficient support for byte-range file locking, together with the stronger semantics with which they are associated, are required to improve the suitability of AFS as a LAN file-sharing protocol for both Unix and Windows clients. Applications on the Windows platform, in particular (e.g., Microsoft Office), actually require byte-range locking to function correctly. Emulation in the client has alleviated most serious problems, albeit, with reduced semantics. We propose protocol enhancements facilitating server-coordinated byte-range locks, atomic lock up/down-grade support, improved semantics for files under byte-range lock control, protocol support for wait-on-lock with fairness, and mandatory lock enforcement for clients on request. The delegation proposal, included within this document in previous drafts, has been split out into a separate proposal, based on feedback from reviewers.Table of Contents Status of this Memo Key Words Abstract 1 AFS-3 File Locking 2 Byte-Range Locking Interfaces 2.1 Dependencies 2.2 Backward Compatibility 2.3 Concepts 2.3.1 General 2.3.2 Lock Management 2.3.3 Deferred Locks 2.3.4 Server Restarts 2.4 Constants 2.4.1 Lock Flags AFSLock_Flag_Mand AFS_LockFlagWait 2.4.2 Lock Status AFSLock_Flag_Extend AFSLock_Flag_Discard 2.4.3 Extended Callback Constants 2.4.4 Extended Callback Extra Flags AFSCB_Lock_Flag_All 2.4.5 Callback Result Constants AFSCB_Cancel_ExtendLocks AFSCB_Cancel_RevokeLocks AFSCB_Flag_ExtendLocks AFSCB_Flag_RevokeLocks 2.5 Data Types 2.5.1 AFSByteRangeLock Fid Type Owner Uniq Offset Length ExpirationTime Txid Token 2.5.2 AFSByteRangeLockSeq 2.5.3 AFSLockFlagsSeq 2.5.4 HostIdentifierSeq 2.5.5 AFSCB_ResultData Redefinition AFSCB_Result_ReturnLocks AFSCB_Result_ResponseDeferred 2.6 Procedures 2.6.1 SetByteRangeLock Notes Error Codes EACCES EWOULDBLOCK EDEADLK EINVAL ENOLCK 2.6.2 ReleaseByteRangeLock Notes Error Codes EINVAL 2.6.3 UpgradeByteRangeLock Error Codes EINVAL EWOULBLOCK EDEADLK 2.6.4 DowngradeByteRangeLock Notes Error Codes EINVAL 2.6.5 AssertExtendLocks Error Codes EACCES 2.6.6 CancelByteRangeLock 2.7 Windows & Unix Lock Semantics 2.7.1 Byte-Range Locking 2.7.2 Read/Write vs. Shared/Exclusive 2.7.3 Atomic Lock Open 2.8 Mandatory Enforcement 2.8.1 Governing Ideas 2.8.2 Enforcement Rules 3 Appendix A: XDR Grammar (afsint.xg) 4 Appendix A: XDR Grammar (afscbint.xg) 1 AFS-3 File Locking While AFS-3 does support file locking, it permits locking of whole-files only, and provides this support inefficiently. AFS clients can take locks on any file object, with the granularity of an entire file, using the RXAFS_SetLock procedure, and release them with the RXAFS_ReleaseLock procedure. AFS uses a poll-based locking model. AFS file locks, once issued, are considered to persist only for 5 minutes, unless extended by the requesting client using the RXAFS_ExtendLock procedure. This simplifies the AFS file server, but complicates clients and wastes network capacity. The OpenAFS file server implementaion, based on the original Transarc AFS file server, tracks locks directly in its on-disk volume structures. Considering the 5-minute duration asserted for file locks, the reason for this decision is clearly not to support lock persistence for long periods, although it may have been intended to allow locks to persist through server restarts (or crashes). The disk package tracks lock type (LockRead or LockWrite), numbers of clients holding locks, and a timestamp. Lock ownership, which in many cases may be reliably inferred, is not recorded. Hence, a broken or malicious client might release locks it never set (i.e., locks set by other clients). The AFS protocol also does not permit atomic lock upgrades (or downgrades). 2 Byte-Range Locking Interfaces 2.1 Dependencies The byte-range lock feature depends on support for extended callback notifications and extended host tracking support in client and server. 2.2 Backward Compatibility AFS clients and servers will indicate their support for byte-range locking through new client and file server capability flags: const CLIENT_CAPABILITY_BYTE_RANGE_LOCK = 0x0008; const VICED_CAPABILITY_BYTE_RANGE_LOCK = 0x0010; 2.3 Concepts 2.3.1 General An AFS file server is responsible to coordinate byte-range locking requests and, optionally, enforce mandatory locking semantics relative to file operations, initiated at different clients. By contrast with the traditional AFS file locking protocol, the proposed byte-range locking protocol makes an attempt to associate locks with a unique subject, specifically, a ViceID and unique identifier which could correspond to a unique session or process executing on the client machine. Clients (cache-manager processes not co-located in memory) request and release byte-range locks through a pair of interfaces (RequestByteRangeLock, ReleaseByteRangeLock) similar to those provided by the traditional AFS locking implementation. The same lock types (read and write, in general regarded as âsharedâ or â exclusiveâ) locks are defined as in traditional AFS locking. Additional arguments and flags are provided to permit selection of desired lock ranges, intention to âwaitâ on the lock (i.e., willing to accept a deferred issue of the lock at such time as the file server can grant the lock, if it cannot be granted immediately), and desired special semantics--currently, the client may request mandatory enforcement. Clients already holding a read or write lock on a range may atomically upgrade or downgrade the lock to the orthogonal type, i.e., they need not release a lock of one type before requesting the other type, avoiding the race condition present in the traditional AFS locking protocol. Byte-range locks are permanently associated with an owner, the client which requested the lock. A lock may not be released by a client which never owned it. A file server may revoke locks granted to any client, for any reason. The file server may also request clients to re-assert their interest in outstanding locks, at any time--in particular, if a client holding locks has not been heard from for a long period (e.g., 10 minutes). Provision is made for re-establishment of state after server restarts or other service interruptions. Administrative users may under various circumstances have need to identify the owner and state of locks on a locked file, and to revoke file locks administratively. This proposal includes RPCs allowing administrative users to perform these operations, and suggests exposure through new AFS pioctls and the fs command. 2.3.2 Lock Management Lock management in the proposed interface is completely redefined relative to the file locking in AFS-3. Concepts are borrowed from AFS cache management, including the callback concept. A byte-range lock may be regarded as a special-purpose callback. A file server may use the ExtendedCallBack interface to request re-assertion of existing locks or revoke (cancel) locks completely. These indications re-use the existing AFSCB_Event_Cancel extended callback notification, adding new cancellation types defined below. 2.3.3 Deferred Locks Where possible, locks are granted immediately with the completion of the SetByteRangeLock request. A file server MAY, on explicit request and subject to client capability, agree to prospectively issue a lock to an interested client at a future time, when the requested lock becomes available. Such deferred locks constitute a promise to issue the lock with best-effort consideration of fairness. A new procedure in the client RPC interface (AsyncIssueByteRangeLock) is provided to effect asynchronous issue of a deferred lock to a waiting client. Deferred locks may themselves be canceled. 2.3.4 Server Restarts When a byte-range locking capable client receives one of the InitCallBackState RPCs from a byte-range locking capable file server, it must assume that any byte-range locks it held prior to receipt must be re-asserted or bulk-released at the file server, using the server's AssertExtendLocks RPC. A conformant file server may, but need not, be prepared to validate locks previously issued to clients, across server restarts. Certainly, it is not expected that all issued locks be committed to stable storage, so the server's ability to do so is presumed to be limited. In future revisions, the Token attribute of AFSByteRangeLock may allow file servers to reliably recognize locks they issued in these circumstances, using cryptographic or other mechanisms. 2.4 Constants 2.4.1 Lock Flags The following flag constants are defined for use in the Flags member of the AFSByteRangeLock structure and equivalently in the Flags argument of the SetByteRangeLock procedure, with the same semantics: const AFSLock_Flag_Mand = 1; /* req. enforcement */ const AFSLock_Flag_Wait = 2; /* req. async wait on lock */ AFSLock_Flag_Mand Requests mandatory enforcement when sent with a SetByteRangeLock request or in a deferred AFSByteRangeLock instance. Asserts mandatory enforcement in an AFSByteRangeLock instance. AFS_LockFlagWait Requests deferred lock if immediate lock cannot be granted when sent with a SetByteRangeLock request. Indicates deferred lock in an AFSByteRangeLock instance. The SetByteRangeLock procedure may return locks in this state, subject to client capability and if so requested in the Flags argument. 2.4.2 Lock Status The following flag constants are provided to coordinate advanced lock-management operations: const AFSLock_Flag_Extend = 4; /* request extension, or server ack extended */ const AFSLock_Flag_Discard = 8; /* discard lock, or server ack discarded */ AFSLock_Flag_Extend Sent with AssertExtendLocks indicates request to assert/extend the corresponding lock. Returned from AssertExtendLocks in OutStatus array, indicates lock confirmation. AFSLock_Flag_Discard Sent with AssertExtendLocks indicates intention to discard the corresponding lock. Returned from AssertExtendLocks in OutStatus array, acknowleges lock discard. 2.4.3 Extended Callback Constants The following extended callback cancellation types and flags are provided, to facilitate lock management through the ExtendedCallback interface: const AFSCB_Cancel_ExtendLocks = 7; /* re-assert locks, or lose them */ const AFSCB_Cancel_RevokeLocks = 8; /* locks on Fid revoked */ These cancellation types are intended to be sent with notifications of the existing AFSCB_Event_Cancel type. 2.4.4 Extended Callback Extra Flags AFSCB_Lock_Flag_All Sent as the value of ExtraFlags when the notification type is AFSCB_Cancel_ExtendLocks or AFSCB_Cancel_RevokeLocks, the notification shall apply to all eligible objects, in which a 0 value has also been set for one or more of Volume, Fid, Uniq in the corresponding callback, with the following intepretation: ⢠If Volume is non-zero, and is published from the sending file server, while Fid and Uniq are 0, then all outstanding locks on files in the volume are requested to be re-asserted or revoked, depending on the value of the corresponding notification â If the notification type is AFSCB_Cancel_ExtendLocks, all corresponding locks are requested to be extended â If the notification type is AFSCB_Cancel_RevokeLocks, all corresponding locks are revoked ⢠If all of Volume, Fid, and Uniq are 0, then all outstanding locks on files published from this server are requested to be re-asserted or revoked, depending on the value of the corresponding notification â If the notification type is AFSCB_Cancel_ExtendLocks, all corresponding locks are requested to be extended â If the notification type is AFSCB_Cancel_RevokeLocks, all corresponding locks are revoked 2.4.5 Callback Result Constants The following constant is provided as a discriminator for the AFSCB_ResultData member of AFSCBExtendedCallbackResult allowing clients to indicate their intention to defer returning locks until a subsequent RPC, within the time limit provided by the server with the notification: const AFSCB_Result_ResponseDeferred = 2; The following constant is provided as a discriminator for the AFSCB_ResultData member of AFSCBExtendedCallbackResult allowing clients to indicate their intention to return locks in the CallBack_Result_Array OUT parameter: const AFSCB_Result_ReturnLocks = 3; AFSCB_Cancel_ExtendLocks When sent as the reason for cancellation in an ExtendedCallback notification, indicates the server requires re-assertion of all locks on FID using the file server's AssertExtendLocks procedure. The client MUST execute the procedure for all locks it asserts on FID prior to the ExpirationTime in the callback, else it MUST consider any locks it held on FID to be canceled. AFSCB_Cancel_RevokeLocks When sent as the reason for cancellation in an ExtendedCallback notification, indicates administrative cancellation of all locks on FID. const AFSCB_Flag_AssertLocks = 4; /* request ExtendLock */ const AFSCB_Flag_RevokeLocks = 8; /* locks cancelled */ AFSCB_Flag_ExtendLocks Has the same meaning and effect as AFSCB_Cancel_ExtendLocks, but may be sent with an arbitrary extended callback message. AFSCB_Flag_RevokeLocks Has the same meaning and effect as AFSCB_Cancel_RevokeLocks, but may be sent with an arbitrary extended callback message. 2.5 Data Types 2.5.1 AFSByteRangeLock The AFSByteRangeLock data type represents a byte-range lock issued by an AFS file server: struct AFSByteRangeLock { AFSFid Fid; afs_uint32 Type; afs_uint32 Owner; afs_uint64 Uniq; afs_uint32 Flags; afs_uint64 Offset; afs_uint64 Length; afs_uint64 ExpirationTime; AFSOpaque Txid; AFSOpaque Token; }; Fid The Fid on which the lock is held. Type The type of lock requested, LockRead or LockWrite. A byte-range read lock is a non-exclusive read assertion on the stated range, which may be shared by any number of readers and no writers. A byte-range lock is an exclusive write assertion on the stated range. Owner The ViceID in use by the client requesting the lock. Uniq Value uniquely identifying a session or process context at the client. The representation of Uniq is intended to be able to uniquely represent the most relevant process or thread context on modern platforms. Offset The distance in bytes from beginning-of-file to the start of the locked range. Length Length in bytes of the locked range. ExpirationTime AFSByteRangeLock instances may be regarded as a special-purpose callback. Instances persist until canceled, or until ExpirationTime is reached. Txid An arbitrary counted bytestring originating at the client with the original request granting a lock. Defined for this revision of the specification to have a maximum length of 0. Token An arbitrary counted bytestring originating at the server when the lock is issued. Defined for this revision of the specification to have a maximum length of 0. In future revisions it may be used to store an âirrefutableâ object which may be used to re-assert locks after server restart, or similar scenarios. 2.5.2 AFSByteRangeLockSeq A variable-length array of type AFSByteRangeLock used for bulk calls for asserting and locks. const AFS_LOCK_SEQ_MAX = 10000; typedef AFSByteRangeLock AFSByteRangeLockSeq <AFS_LOCK_SEQ_MAX>; 2.5.3 AFSLockFlagsSeq An array of flags used in parallel with AFSByteRangeLockSeq, above. const AFS_LOCK_SEQ_MAX = 10000; typedef afs_int32 AFSLockFlagsSeq <AFS_LOCK_SEQ_MAX>; 2.5.4 HostIdentifierSeq const AFS_LOCK_SEQ_MAX = 10000; typedef AFSLockHostIdentifierSeq <AFS_LOCK_SEQ_MAX>; An array of HostIdentifier structures used by the GetByteRangeLockStatus procedure to report client machines holding locks. 2.5.5 AFSCB_ResultData Redefinition The AFSCB_ResultData union defined in the Callback Extended Information draft is redefined (upward compatibly), as the following: union AFSCB_ResultData switch (afs_uint32 Result_Type) { case AFSCB_Result_NoResult: void; case AFSCB_Result_ResponseDeferred: void; case AFSCB_Result_ReturnLocks: AFSByteRangeLockSeq AssertedLocks_Array; }; AFSCB_Result_ReturnLocks The result is used to return (synchronously, in the ExtendedCallBack RPC) a list of byte-range locks being extended in response to an extended callback notification of type AFSCB_Flag_AssertLocks. AFSCB_Result_ResponseDeferred The result is used to indicate that the client will not assert or return locks synchronously in the ExtendedCallBack RPC (and will instead assert or return locks using the asychronous RPCs provided.) 2.6 Procedures 2.6.1 SetByteRangeLock Requests a lock of type Type on Fid, on the range [Offset, Offset+Length). Type must be one of LockRead or LockWrite. Owner shall be set to the ViceID corresponding to the requesting process or equivalent, or to 0 if this is not known. Uniq shall be set to a value uniquely identifying the requesting process or equivalent. On Unix-like systems, Uniq could be set to the PID of the requesting process. Txid shall be a counted bytestring corresponding to the AFSByteRangeLock attribute of the same name. Txid is defined at this revision to have length 0. proc SetByteRangeLock( IN AFSFid *Fid, afs_uint32 Type, afs_uint32 Flags, afs_uint32 Owner, afs_uint64 Uniq, afs_uint64 Offset, afs_uint64 Length, AFSOpaque Txid, OUT AFSByteRangeLock *Lock ) = 65601; Notes On successful return the file server has granted the requested lock, and Lock points to the server's asserted AFSByteRangeLock structure. If the client has requested and the server agrees to issue a deferred lock, Lock points to the server's asserted deferred AFSByteRangeLock structure. The client may safely determine if it has been granted a deferred lock by inspecting the value of Lock->Flags. The returned Lock structure MUST NOT differ from the request with respect to range, except in the case where the requested lock would overlap with a lock of the same type already held by the same client, in which case, the locks are merged and the merged range returned in Lock. The returned Lock structure MAY differ from request with respect to Flags. The value of the Flags argument may alter the semantics and/or processing of the call: ⢠if (Flags & AFSLock_Flag_Mand), file server is requested to provide mandatory locking semantics as defined below--if the file server is willing to provide mandatory enforcement, it MAY set the corresponding flag in Lock, and if so MUST restrict writes on the asserted range to the holding client for the duration of the lock ⢠if (Flags & AFSLock_Flag_Wait), file server is requested to issue a deferred lock if the requested lock may not be immediately granted--the file server MAY grant a deferred lock in response to this request, indicating its agreement by setting the corresponding flag in Lock. Lock is in this instance an indicator only of the deferred lock promise Error Codes EACCES The caller does not have the necessary rights. EWOULDBLOCK The server is unable to grant the request due to conflicting locks. If a deferred lock was requested, a Flags value of AFSLock_Flag_Wait indicates the deferred lock is granted. EDEADLK The server declines to grant the requested lock (or deferred lock) because granting it would cause a deadlock. EINVAL An illegal lock type was specified. ENOLCK The server has insufficient resources to grant the lock, or the requesting client or file has too many locks outstanding. (No specific limits are mandated or suggested by this document.) 2.6.2 ReleaseByteRangeLock Releases the byte-range lock represented in Lock, asserted to be held by the calling client. proc ReleaseByteRangeLock( IN AFSByteRangeLock *Lock ) = 65602; Notes When an AFS client intends to release a byte-range write lock, it MUST ensure that any changed data in the effected range has been sent to the file server with the appropriate StoreData RPC, and that the RPC completed successfully. This requirement is based on an implied assertion that holding a lock on some region of a file implies, invariantly, an up-to-date view on the locked region. Error Codes EINVAL The caller does not own the corresponding lock. 2.6.3 UpgradeByteRangeLock Upgrades the byte-range lock represented in Lock, asserted to be held by the calling client, from its current type (which should be LockRead) to LockWrite. The upgrade is executed atomically (no opportunity exists for another client to set a conflicting lock in the upgraded range while the upgrade is being executed). proc UpgradeByteRangeLock( IN AFSByteRangeLock *Lock, afs_uint32 Type ) = 65603; Error Codes EINVAL The caller does not own the corresponding lock or it is not of the correct type. EWOULBLOCK The lock could not be granted due to conflicting locks. EDEADLK The lock could not be granted because granting it, with deferral, would cause deadlock. 2.6.4 DowngradeByteRangeLock Downgrades the byte-range lock represented in Lock, asserted to be held by the calling client, from its current type (which should be LockWrite) to LockRead. The downgrade is executed atomically (no opportunity exists for another client to set a conflicting lock in the downgraded range while the downgrade is being executed). proc DowngradeByteRangeLock( IN AFSByteRangeLock *Lock, afs_uint32 Type ) = 65604; Notes When an AFS client intends to downgrade a byte-range write lock, it MUST ensure that any changed data in the effected range has been sent to the file server with the appropriate StoreData RPC, and that the RPC completed successfully. This requirement is based on an implied assertion that holding a lock on some region of a file implies, invariantly, an up-to-date view on the locked region. Error Codes EINVAL The caller does not own the corresponding lock or it is not of the correct type. 2.6.5 AssertExtendLocks A file server may, at any time, request a client to re-assert its interest in oustanding locks, or revoke those locks altogether. It is expected that clients not heard from for a long period (e.g., 10 minutes) would be requested to re-assert any outstanding locks they hold. To request re-assertion of outstanding locks, the file server may send the client an extended callback notification on the corresponding Fids of type AFSCB_Cancel_ExtendLocks, or it may set the flag AFSCB_Flag_ExtendLocks on a notification of another type it was already intending to send. On receipt of an AFSCB_Cancel_ExtendLocks or AFSCB_Flag_ExtendLocks notification through the extended callback interface, a client MUST either: ⢠return any locks it asserts in AssertedLocks_Array, the type of union AFSCB_ResultData for these calls â if the server rejects any locks asserted by the client, it will so notify client in a subsequent cancellation message ⢠set a result of AFSCB_Result_ResponseDeferred, and execute the AssertExtendLocks bulk call before the ExpirationTime in the AFSExtendedCallback structure sent with the callback Fid is the file for which locks are being extended. Flags contains indication of special semantics (e.g., mandatory enforcement) being asserted, if any. AssertedLocks_Array points to a variable length array of AFSByteRangeLock structures the client asserts to hold. At the completion of the call, the parallel array OutResult indicates the server's confirmation (or refusal) to extend each asserted lock--a value of (Flags & AFSLock_Flag_Extend_Ok) indicates confirmation. /* Assert locks on Fid, on request */ AssertExtendLocks( IN AFSFid Fid, afs_uint32 Flags, AFSByteRangeLockSeq *AssertedLocks_Array, OUT AFSLockFlagsSeq *OutResult ) = 65607; GetByteRangeLockStatus Diagnostic procedure provided to permit system administrators to identify client machines and software running on those clients that are currently holding locks on a file. Fid is the file to report on. The call returns parallel variable-length arrays of locks and their associated hosts. The procedure may only be executed by the AFS super user or members of the system:administrators group. proc GetByteRangeLockStatus( IN Fid, OUT AFSByteRangeLockSeq *AssertedLocks_Array, AFSLockHostIdentifierSeq *Clients_Array ) = 65605; Error Codes EACCES The caller does not have the necessary rights. 2.6.6 CancelByteRangeLock The CancelByteRangeLock procedure permits system administrators to revoke active locks that may be obstructing normal operations, perhaps due to a system or network problem. Fid is the file on which to revoke locks. If successful, all locks in range [Offset, Offset+Length) are canceled If a value of 0 is given for Offset and Length the range is taken to span the entire file. The procedure may only be executed by the AFS super user or members of the system:administrators group. proc CancelByteRangeLocks( IN Fid, afs_uint64 Offset, afs_uint64 Length ) = 65606; 2.7 Windows & Unix Lock Semantics Implementation of interoperable locking behavior presents challenges for a distributed file system like AFS, which must support clients on platforms which do not agree precisely on the semantics desirable or possible to enforce. 2.7.1 Byte-Range Locking As byte-range locking is effectively required for correct behavior of Windows applications, the OpenAFS for Windows client has been forced to implement a locally-enforced byte-range locking mechanism. In the Windows client today, local byte-range are shadowed by a whole-file lock in AFS. With the introduction of server-coordinated byte-range locking, the Windows client is expected to use server byte-range locks when possible. 2.7.2 Read/Write vs. Shared/Exclusive In the current OpenAFS for Windows client, shared (whole-file) locks are mapped to AFS read locks, and Windows exclusive (whole-file) locks are mapped to AFS write locks. This mapping applies equally for byte-range locks. 2.7.3 Atomic Lock Open Windows provides the ability to open and lock a file in a single operation, and key Windows applications such as Microsoft Office rely this behavior. Although this behavior has no direct equivalent in the AFS protocol (which does not provide an OPEN file operation) the correct behavior from the point of view of Windows applications is already emulated by the Windows client. 2.8 Mandatory Enforcement Mandatory enforcement of file locks is considered a requirement for Windows interoperation. The rules proposed here reflect some consideration and discussion of unique features in AFS, and also compromises made in competing systems intended to support mixed Windows and Unix clients, particularly NFSv4. 2.8.1 Governing Ideas ⢠Byte-range locks may be taken out on a file under the same circumstances under which a whole file might be taken out in traditional AFS ⢠Clients asserting advisory locks on a file by definition do not expect any special semantics from the file system; however, it seems logically reasonable that advisory and mandatory locks should interact equivalently as locks, and so where this document asserts that in a given scenario, a lock by a client A would conflict with a lock held by a client B, it is is not considered relevant whether either client's lock is advisory or mandatory ⢠The mechanism of lock enforcement is to fail the operation being attempted, a hint shall be sent in the return code of the reason for failure ⢠An operation which fails due to conflict with an existing lock fails completely ⢠Mandatory enforcement is taken to mean enforcement, generally, of write denial in any locked range, including by clients not observing any locking protocol ⢠Attempts to write outside any conflicting locked range on a file with at least one mandatory locked range, considering the view of locks on the file at the fileserver when the write request is processed, are considered valid (this is the documented behavior on Windows platforms) ⢠Since applications exist, particularly for the command line (e.g., tar) which know nothing about locks, and may have legitimate reason to read (though not write) data protected by mandatory locks, relaxed semantics are enforced for reads by clients reading outside any range they have themselves locked--such reads never conflict with lock enforcement--the view of data provided to such a client shall be whatever is available, conforming to regular AFS semantics ⢠Mandatory enforcement of a read or write lock is asserted to govern only the StoreData operation (by other clients), and not, e.g., the various directory change operations or FetchData[footnote: Mandatory read lock enforcement is silly, Eisler 2006. More importantly, it causes difficulties for the AFS cache consistency model. ] 2.8.2 Enforcement Rules ⢠If a client A has a mandatory lock of any type on a range R in a file F, then StoreData operations by any other client B which would alter data in any overlapping range or truncate F such as to reduce or eliminate R, the conflicting operation (initiated by B) fails 3 Appendix A: XDR Grammar (afsint.xg) const VICED_CAPABILITY_BYTE_RANGE_LOCK = 0x0010; const AFSLock_Flag_Mand = 1; /* req. enforcement */ const AFSLock_Flag_Wait = 2; /* req. wait on lock */ struct AFSByteRangeLock { AFSFid Fid; afs_uint32 Type; afs_uint32 Flags; afs_uint32 Owner; afs_uint64 Uniq; afs_uint64 Offset; afs_uint64 Length; afs_uint64 ExpirationTime; }; /* Request byte-range file lock */ proc SetByteRangeLock( IN AFSFid *Fid, afs_uint32 Type, afs_uint32 Flags, afs_uint32 Owner, afs_uint64 Uniq, afs_uint64 Offset, afs_uint64 Length, OUT AFSByteRangeLock *Lock ) = 65601; /* Release byte-range file lock */ proc ReleaseByteRangeLock( IN AFSByteRangeLock *Lock ) = 65602; /* Upgrade byte-range file lock (i.e., from Read to Write) */ proc UpgradeByteRangeLock( IN AFSByteRangeLock *Lock, afs_uint32 Type ) = 65603; /* Downgrade byte-range file lock (i.e., from Write to Read) */ proc DowngradeByteRangeLock( IN AFSByteRangeLock *Lock, afs_uint32 Type ) = 65604; /* Request lock status report (system:administrators) */ proc GetByteRangeLockStatus( IN Fid, OUT AFSByteRangeLockSeq *AssertedLocks_Array, AFSLockHostIdentifierSeq *Clients_Array ) = 65605; /* administratively cancel locks (system:administrators) */ proc CancelByteRangeLocks( IN Fid, afs_uint64 Offset, afs_uint64 Length ) = 65606; const AFS_LOCK_SEQ_MAX = 10000; typedef AFSByteRangeLock AFSByteRangeLockSeq <AFS_LOCK_SEQ_MAX>; typedef AFSLockFlagsSeq <AFS_LOCK_SEQ_MAX>; const AFSLock_Flag_Extend = 4; /* client request extend, server ack extended */ const AFSLock_Flag_Discard = 8; /* client request disard, server ack discarded */ /* Assert locks on Fid, on request */ AssertExtendLocks( IN AFSFid Fid, afs_uint32 Flags, AFSByteRangeLockSeq *AssertedLocks_Array, OUT AFSLockFlagsSeq *OutResult ) = 65607; 4 Appendix A: XDR Grammar (afscbint.xg) const CLIENT_CAPABILITY_BYTE_RANGE_LOCK = 0x0008; /* Byte-Range Locking Cancellation Types */ const AFSCB_Cancel_ExtendLocks = 7; /* re-assert locks, or lose them */ const AFSCB_Cancel_RevokeLocks = 8; /* locks on Fid revoked */ /* Cancellation Flags */ const AFSCB_Flag_AssertLocks = 4; /* request ExtendLock */ const AFSCB_Flag_RevokeLocks = 8; /* locks cancelled, sorry */ /* confirm issue of deferred lock requests */ proc AsyncIssueByteRangeLock( IN HostIdentifier *Server, AFSByteRangeLockSeq <AFS_LOCK_SEQ_MAX> ) = 65540;
_______________________________________________ AFS3-standardization mailing list [email protected] http://michigan-openafs-lists.central.org/mailman/listinfo/afs3-standardization
