Adding an Atomic EXCHANGE_RANGE Operation to NFSv4.2

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 10 October 2026.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

With the Network File System version 4.2 (NFSv4.2), atomic updates to a file are not guaranteed. A single WRITE operation might span multiple data blocks; another client doing a READ might then encounter a partial WRITE. In addition, multiple WRITE operations, even within the same compound, may not be atomically applied to a file. In some implementations, multiple WRITE operations within the same compound may appear to be applied atomically, but this behavior is implementation-specific and not guaranteed by the protocol.¶

This document introduces the EXCHANGE_RANGE operation, which is OPTIONAL to implement, to NFSv4.2. EXCHANGE_RANGE atomically exchanges a range of content between two files. A client can easily determine whether or not a server supports the EXCHANGE_RANGE operation by examining the return code of the operation. If the server does not support the EXCHANGE_RANGE operation, the server returns NFS4ERR_NOTSUPP.¶

Using the process described in [RFC8178], the revisions in this document extend NFSv4.2 [RFC7862]. They are built on top of the external data representation (XDR) [RFC4506] generated from [RFC7863].¶

2. Definitions

The definitions of the following terms are referenced as follows:¶

• change_info4 (Section 3.3.3 of [RFC8881])¶

• CLONE (Section 15.13 of [RFC7862])¶

• clone_blksize (Section 12.2.1 of [RFC7862])¶

• NFS4ERR_NOTSUPP (Section 15.1.1.5 of [RFC8881])¶

• READ (Section 18.22 of [RFC8881])¶

• WRITE (Section 18.32 of [RFC8881])¶

3. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

4. Use Cases

The EXCHANGE_RANGE operation addresses a class of problems that cannot be solved without loss of atomicity by existing NFSv4.2 operations. This section motivates the operation by contrasting it with a hypothetical one-way transfer primitive and then presenting five concrete use cases.¶

Consider an operation called XFER_RANGE that atomically copies data from a source range to a destination range -- essentially CLONE (Section 15.13 of [RFC7862]) with an atomicity guarantee. XFER_RANGE would be a useful primitive in its own right for cases where one-way data movement is all that is needed. EXCHANGE_RANGE differs from it in one critical respect: EXCHANGE_RANGE atomically swaps the contents of both ranges. Neither range is "the source" and neither is "the destination" -- both hold meaningful data before the operation and both hold meaningful data after. While the protocol distinguishes SAVED_FH and CURRENT_FH for access control purposes, the semantics of the operation treat both ranges symmetrically. The following examples illustrate when the distinction matters.¶

The use cases below share a common requirement: both ranges contain valid data before the operation, and both must remain valid after the operation, with no externally visible intermediate state. A sequence of one-way operations (e.g., CLONE, WRITE, or a hypothetical XFER_RANGE) cannot provide this guarantee, as they either destroy one side of the data or introduce a window in which observers may see partially updated state.¶

A/B deployment:

A server pre-computes version 2 of a dataset into fileB while version 1 remains live in fileA. At the moment of go-live, the operator wants to atomically swap which file is current. XFER_RANGE(B->A) overwrites fileA and destroys version 1. XFER_RANGE(A->B) does the same in the other direction. Neither preserves both versions. EXCHANGE_RANGE atomically swaps the two, leaving version 1 intact in fileB for inspection or rollback. This example applies when the two versions reside in fixed locations or ranges that cannot be renamed or redirected atomically (e.g., shared file layouts or range-based consumers).¶

Checkpoint and restore:

A process maintains a live range and a checkpoint range. A checkpoint is performed by EXCHANGE_RANGE(live, checkpoint): the checkpoint range now holds the saved state and the live range holds what was the checkpoint. A restore is performed by the identical call. The self-inverse property means the mechanism for save and restore are the same operation. XFER_RANGE requires two distinct one-way operations and cannot guarantee that a restore returns exactly what was saved without additional bookkeeping.¶

Circular log rotation:

Segment 0 is being read by consumers; segment 1 has been filled by a writer and is ready to become the new read segment. Both segments hold valuable data -- neither is scratch space. EXCHANGE_RANGE atomically swaps their roles. XFER_RANGE(1->0) destroys segment 0's content before readers have finished with it. In systems with multiple independent readers, coordination is not feasible, and readers must never observe a partially rotated state.¶

Erasure coding stripe rebuild:

During a pNFS Flex Files ([I-D.haynes-nfsv4-flexfiles-v2]) reconstruction, a data server has rebuilt a stripe from parity into a staging buffer. Both the live stripe and the staging buffer exist and are valid. EXCHANGE_RANGE atomically promotes the staging buffer to live and moves the old live data into the staging buffer, where it remains available for integrity verification or rollback if the new stripe fails a subsequent check. XFER_RANGE would overwrite the live stripe before that verification can occur. This avoids both the need to copy data and any window in which parity and data are inconsistent.¶

Atomic file update via clone-then-swap:

This is the case where XFER_RANGE would be sufficient, and it is worth stating clearly. A client CLONEs a source file to a temporary working copy, modifies the copy, and then wants to atomically publish the result. XFER_RANGE(temp->source) accomplishes this: the temporary file is discarded and source is updated atomically. EXCHANGE_RANGE handles this case as well, and adds one benefit: after the swap, the temporary file holds the previous content of source, providing a no-cost rollback path -- invoke EXCHANGE_RANGE again and the original state is restored. An implementation that does not need rollback can simply discard the old content; one that does need it gets it without additional operations.¶

A composition of existing operations (e.g., CLONE followed by WRITE, or two XFER_RANGE operations) cannot provide the same guarantees as EXCHANGE_RANGE. Such compositions either:¶

• destroy one side of the data, or¶

• expose an intermediate state to other clients, or¶

• require external coordination not available at the protocol level.¶

EXCHANGE_RANGE provides these guarantees as a single atomic operation.¶

5. Operation 81: EXCHANGE_RANGE - Exchange a range of a file into another file

 /// const OP_EXCHANGE_RANGE = 81;
 ///
 /// struct EXCHANGE_RANGE4args {
 ///         /* SAVED_FH: source file */
 ///         /* CURRENT_FH: destination file */
 ///         stateid4        era_src_stateid;
 ///         stateid4        era_dst_stateid;
 ///         offset4         era_src_offset;
 ///         offset4         era_dst_offset;
 ///         length4         era_count;
 /// };

 /// struct EXCHANGE_RANGE4resok {
 ///         change_info4    err_src_cinfo;
 ///         change_info4    err_dst_cinfo;
 /// };
 ///
 /// union EXCHANGE_RANGE4res switch (nfsstat4 err_status) {
 ///  case NFS4_OK:
 ///          EXCHANGE_RANGE4resok err_resok4;
 ///  default:
 ///          void;
 /// };

 /// /* In nfs_argop4: */
 /// case OP_EXCHANGE_RANGE:
 ///         EXCHANGE_RANGE4args opexchange_range;
 ///
 /// /* In nfs_resop4: */
 /// case OP_EXCHANGE_RANGE:
 ///         EXCHANGE_RANGE4res opexchange_range;

6. Operations and Their Valid Errors

The operations and their valid errors are presented in Section 6, Paragraph 2. All error codes not defined in this document are defined in Section 15 of [RFC8881] and Section 11 of [RFC7862].¶

If the destination file has active pNFS layouts that prevent atomic modification of the target range, the server MAY return an appropriate pNFS-related error.¶

7. Extraction of XDR

This document contains the external data representation (XDR) [RFC4506] description of the EXCHANGE_RANGE operation. The XDR description is presented in a manner that facilitates easy extraction into a ready-to-compile format. To extract the machine-readable XDR description, use the following shell script:¶

#!/bin/sh
grep '^ *///' $* | sed 's?^ */// ??' | sed 's?^ *///$??'

For example, if the script is named 'extract.sh' and this document is named 'exchange_range.txt', execute the following command:¶

sh extract.sh < exchange_range.txt > exchange_range_prot.x

This script removes leading blank spaces and the sentinel sequence '///' from each line. XDR descriptions with the sentinel sequence are embedded throughout the document.¶

Note that the XDR code contained in this document depends on types from the NFSv4.2 nfs4_prot.x file (generated from [RFC7863]). This includes both nfs types that end with a 4, such as offset4, length4, etc., as well as more generic types such as uint32_t and uint64_t.¶

While the XDR can be appended to that from [RFC7863], the code snippets should be placed in their appropriate sections within the existing XDR.¶

8. Security Considerations

The EXCHANGE_RANGE operation is subject to the same security considerations as other NFSv4.2 operations that modify file data.¶

The caller MUST have appropriate access to both the source file (read access) and the destination file (write access). Servers MUST enforce authorization checks on both filehandles before performing the exchange.¶

Within a session, the SEQUENCE mechanism (Section 18.46 of [RFC8881]) prevents duplicate execution via the slot identifier and sequenceid. After a server reboot, previously issued stateids are invalidated, preventing replay of prior operations across reboots.¶

Because EXCHANGE_RANGE is its own inverse, a double execution returns both files to their original state. A client checking only the final value of the change attribute cannot distinguish zero executions from two executions, since both cases leave the files in their original state while the change attribute may have been incremented an even number of times. The change_info4 values returned in err_src_cinfo and err_dst_cinfo enable precise confirmation: a client MUST record the change attribute of both files before the first attempt and compare cinfo_before from the response against that recorded value to confirm a single net execution. Comparing only cinfo_after is insufficient for this purpose.¶

9. IANA Considerations

This document has no IANA actions.¶

10. References

Acknowledgments

Christoph Helwig brought the XFS exchange range implementation ([XFS-EXCHANGE-RANGE]) to the author's attention, which prompted this document.¶

Darrick Wong, David Noveck, Pali Rohar, Rick Macklem, and Christoph Helwig helped review the document.¶

Chris Inacio, Brian Pawlowski, and Gorry Fairhurst helped guide this process.¶

Author's Address