How NFSv4 Guarantees Consistent File Locks Across Clients

File Locks

File locks are a basic feature of file systems, allowing applications to control concurrent access. NFS, the standard network file system for Unix‑like systems, has supported file locks natively since NFSv4. NFS has three versions: NFSv2, NFSv3, and NFSv4.

Stateful Design in NFSv4

NFSv4 introduced state, enabling the server to maintain lock state, eliminating the need for the separate NLM protocol used in NFSv3.

Application Interface

Applications manage NFS file locks via the fcntl() or flock() system calls. The diagram below shows the call sequence when a NAS mounts NFSv4 and acquires a lock.

EOS Principle

File lock operations are non‑idempotent; retries and failover can cause inconsistent lock views. NFSv4 uses a sequence‑id (SeqId) mechanism to ensure each lock operation is executed at most once. For each open/lock state, the client and server maintain independent seqids. The client increments its seqid for state‑changing operations and sends it to the server. The server compares the received seqid (R) with its stored seqid (L):

If R == L + 1, the request is valid and processed normally.

If R == L, the request is a retry; the server returns the cached reply.

Otherwise the request is illegal and rejected.

Exception Handling

To keep lock views consistent, the client must cooperate with the server. Two dimensions are involved: SunRPC design and NFS protocol behavior.

SunRPC Design

SunRPC uses a 32‑bit xid to identify each RPC. Retries reuse the same xid, allowing the server to detect duplicate requests via a duplicate‑request cache (DRC). The client initializes xid with a random value, and the server validates additional request metadata. The client may retry indefinitely until a response is received; mounting options “soft” and “hard” control retry behavior, with “hard” being the default for NAS.

Signal Interruption

If a lock acquisition RPC is interrupted by a signal, the client may not know that the lock was granted on the server, leading to inconsistent views. The NFSv4 lock acquisition path calls _nfs4_do_setlk(), which eventually invokes nfs4_wait_for_completion_rpc_task(). A negative return indicates a signal interruption, and the client records this in struct nfs4_lockdata. The lock‑release callback nfs4_lock_release() detects the interruption and calls nfs4_do_unlck() to release any possibly granted lock, while deliberately not freeing the seqid to prevent new lock operations during correction.

static int _nfs4_do_setlk(struct nfs4_state *state, int cmd, struct file_lock *fl, int recovery_type) {
    ...
    task = rpc_run_task(&task_setup_data);
    if (IS_ERR(task))
        return PTR_ERR(task);
    ret = nfs4_wait_for_completion_rpc_task(task);
    if (ret == 0) {
        ret = data->rpc_status;
        if (ret)
            nfs4_handle_setlk_error(data->server, data->lsp,
                data->arg.new_lock_owner, ret);
        else
            data->cancelled = 1;
    }
    ...
}

Summary

File locks are fundamental to shared file systems. NFSv4.0 introduces mechanisms such as stateful protocols, SeqId checks, and SunRPC designs to achieve lock‑view consistency, though future NFS versions will continue to evolve.