6. Anhang II: Sperrverwaltungsprotokoll (Appendix II: Lock manager protocol)
6.0 Appendix II: Lock manager protocol
Because the NFS version 2 protocol as well as the NFS version 3 protocol is stateless, an additional Network Lock Manager (NLM) protocol is required to support locking of NFS-mounted files. The NLM version 3 protocol, which is used with the NFS version 2 protocol, is documented in [X/OpenNFS].
Some of the changes in the NFS version 3 protocol require a new version of the NLM protocol. This new protocol is the NLM version 4 protocol. The following table summarizes the correspondence between versions of the NFS protocol and NLM protocol.
NFS and NLM protocol compatibility
+---------+---------+ | NFS | NLM | | Version | Version | +===================+ | 2 | 1,3 | +---------+---------+ | 3 | 4 | +---------+---------+
This appendix only discusses the differences between the NLM version 3 protocol and the NLM version 4 protocol. As in the NFS version 3 protocol, almost all the names in the NLM version 4 protocol have been changed to include a version number. This appendix does not discuss changes that consist solely of a name change.
6.1 RPC Information
6.1.1 Authentication
The NLM service uses AUTH_NONE in the NULL procedure. AUTH_UNIX, AUTH_SHORT, AUTH_DES, and AUTH_KERB are used for all other procedures. Other authentication types may be supported in the future.
6.1.2 Constants
These are the RPC constants needed to call the NLM service. They are given in decimal.
PROGRAM 100021 VERSION 4
6.1.3 Transport Address
The NLM service is normally supported over the TCP and UDP protocols. The rpcbind daemon should be queried for the correct transport address.
6.1.4 Basic Data Types
uint64
`typedef unsigned hyper uint64;
int64
`typedef hyper int64;
uint32
`typedef unsigned long uint32;
int32
`typedef long int32;
These types are new for the NLM version 4 protocol. They are the same as in the NFS version 3 protocol.
nlm4_stats
enum nlm4_stats {
NLM4_GRANTED = 0,
NLM4_DENIED = 1,
NLM4_DENIED_NOLOCKS = 2,
NLM4_BLOCKED = 3,
NLM4_DENIED_GRACE_PERIOD = 4,
NLM4_DEADLCK = 5,
NLM4_ROFS = 6,
NLM4_STALE_FH = 7,
NLM4_FBIG = 8,
NLM4_FAILED = 9
};
Nlm4_stats indicates the success or failure of a call. This version contains several new error codes, so that clients can provide more precise failure information to applications.
NLM4_GRANTED The call completed successfully.
NLM4_DENIED The call failed. For attempts to set a lock, this status implies that if the client retries the call later, it may
succeed.
NLM4_DENIED_NOLOCKS The call failed because the server could not allocate the necessary resources.
NLM4_BLOCKED Indicates that a blocking request cannot be granted immediately. The server will issue an NLMPROC4_GRANTED callback to the client when the lock is granted.
NLM4_DENIED_GRACE_PERIOD The call failed because the server is reestablishing old locks after a reboot and is not yet ready to resume normal service.
NLM4_DEADLCK The request could not be granted and blocking would cause a deadlock.
NLM4_ROFS The call failed because the remote file system is read-only. For example, some server implementations might not support exclusive locks on read-only file systems.
NLM4_STALE_FH The call failed because it uses an invalid file handle. This can happen if the file has been removed or if access to the file has been revoked on the server.
NLM4_FBIG The call failed because it specified a length or offset that exceeds the range supported by the server.
NLM4_FAILED The call failed for some reason not already listed. The client should take this status as a strong hint not to retry the request.
nlm4_holder
struct nlm4_holder {
bool exclusive;
int32 svid;
netobj oh;
uint64 l_offset;
uint64 l_len;
};
This structure indicates the holder of a lock. The exclusive field tells whether the holder has an exclusive lock or a shared lock. The svid field identifies the process that is holding the lock. The oh field is an opaque object that identifies the host or process that is holding the lock. The l_len and l_offset fields identify the region that is locked. The only difference between the NLM version 3 protocol and the NLM version 4 protocol is that in the NLM version 3 protocol, the l_len and l_offset fields are 32 bits wide, while they are 64 bits wide in the NLM version 4 protocol.
nlm4_lock
struct nlm4_lock {
string caller_name<LM_MAXSTRLEN>;
netobj fh;
netobj oh;
int32 svid;
uint64 l_offset;
uint64 l_len;
};
This structure describes a lock request. The caller_name field identifies the host that is making the request. The fh field identifies the file to lock. The oh field is an opaque object that identifies the host or process that is making the request, and the svid field identifies the process that is making the request. The l_offset and l_len fields identify the region of the file that the lock controls. A l_len of 0 means "to end of file".
There are two differences between the NLM version 3 protocol and the NLM version 4 protocol versions of this structure. First, in the NLM version 3 protocol, the length and offset are 32 bits wide, while they are 64 bits wide in the NLM version 4 protocol. Second, in the NLM version 3 protocol, the file handle is a fixed-length NFS version 2 protocol file handle, which is encoded as a byte count followed by a byte array. In the NFS version 3 protocol, the file handle is already variable-length, so it is copied directly into the fh field. That is, the first four bytes of the fh field are the same as the byte count in an NFS version 3 protocol nfs_fh3. The rest of the fh field contains the byte array from the NFS version 3 protocol nfs_fh3.
nlm4_share
struct nlm4_share {
string caller_name<LM_MAXSTRLEN>;
netobj fh;
netobj oh;
fsh4_mode mode;
fsh4_access access;
};
This structure is used to support DOS file sharing. The caller_name field identifies the host making the request. The fh field identifies the file to be operated on. The oh field is an opaque object that identifies the host or process that is making the request. The mode and access fields specify the file-sharing and access modes. The encoding of fh is a byte count, followed by the file handle byte array. See the description of nlm4_lock for more details.
6.2 NLM Procedures
The procedures in the NLM version 4 protocol are semantically the same as those in the NLM version 3 protocol. The only semantic difference is the addition of a NULL procedure that can be used to test for server responsiveness. The procedure names with _MSG and _RES suffixes denote asynchronous messages; for these the void response implies no reply. A syntactic change is that the procedures were renamed to avoid name conflicts with the values of nlm4_stats. Thus the procedure definition is as follows.
version NLM4_VERS {
void
NLMPROC4_NULL(void) = 0;
nlm4_testres NLMPROC4_TEST(nlm4_testargs) = 1;
nlm4_res NLMPROC4_LOCK(nlm4_lockargs) = 2;
nlm4_res NLMPROC4_CANCEL(nlm4_cancargs) = 3;
nlm4_res NLMPROC4_UNLOCK(nlm4_unlockargs) = 4;
nlm4_res
NLMPROC4_GRANTED(nlm4_testargs) = 5;
void
NLMPROC4_TEST_MSG(nlm4_testargs) = 6;
void
NLMPROC4_LOCK_MSG(nlm4_lockargs) = 7;
void
NLMPROC4_CANCEL_MSG(nlm4_cancargs) = 8;
void
NLMPROC4_UNLOCK_MSG(nlm4_unlockargs) = 9;
void
NLMPROC4_GRANTED_MSG(nlm4_testargs) = 10;
void
NLMPROC4_TEST_RES(nlm4_testres) = 11;
void
NLMPROC4_LOCK_RES(nlm4_res) = 12;
void
NLMPROC4_CANCEL_RES(nlm4_res) = 13;
void
NLMPROC4_UNLOCK_RES(nlm4_res) = 14;
void
NLMPROC4_GRANTED_RES(nlm4_res) = 15;
nlm4_shareres
NLMPROC4_SHARE(nlm4_shareargs) = 20;
nlm4_shareres
NLMPROC4_UNSHARE(nlm4_shareargs) = 21;
nlm4_res
NLMPROC4_NM_LOCK(nlm4_lockargs) = 22;
void
NLMPROC4_FREE_ALL(nlm4_notify) = 23;
} = 4;
6.2.0 Procedure 0: NULL - Do nothing
SYNOPSIS
void NLMPROC4_NULL(void) = 0;
DESCRIPTION
The NULL procedure does no work. It is made available in all RPC services to allow server response testing and timing.
IMPLEMENTATION
It is important that this procedure do no work at all so that it can be used to measure the overhead of processing a service request. By convention, the NULL procedure should never require any authentication.
ERRORS
It is possible that some server implementations may return RPC errors based on security and authentication requirements.
6.3 Implementation issues
6.3.1 64-bit offsets and lengths
Some NFS version 3 protocol servers can only support requests where the file offset or length fits in 32 or fewer bits. For these servers, the lock manager will have the same restriction. If such a lock manager receives a request that it cannot handle (because the offset or length uses more than 32 bits), it should return the error, NLM4_FBIG.
6.3.2 File handles
The change in the file handle format from the NFS version 2 protocol to the NFS version 3 protocol complicates the lock manager. First, the lock manager needs some way to tell when an NFS version 2 protocol file handle refers to the same file as an NFS version 3 protocol file handle. (This is assuming that the lock manager supports both NLM version 3 protocol clients and NLM version 4 protocol clients.) Second, if the lock manager runs the file handle through a hashing function, the hashing function may need
to be retuned to work with NFS version 3 protocol file handles as well as NFS version 2 protocol file handles.