operation	code	XDR type	msg	section
Specify Initial Characteristics	1	optinfo_initxch	No	4.1
Request Characteristic Modification	2	optinfo_reqxch	No	4.2
Respond to Modification Request	3	optinfo_respxch	No	4.3
Report Updated Characteristics	4	optinfo_updxch	No	4.4

Support for all of the operations above is OPTIONAL. RPC-over-RDMA Version Two implementations that receive an operation that is not supported MUST respond with RDMA_ERROR message with an error code of RDMA_ERR_INVAL_OPTION as specified in [rpcrdmav2]

The only operation support requirements are as follows:

• Implementations which send ROPT_REQXCH messages must support ROPT_RESPXCH and ROPT_UPDXCH messages.
• Implementations which support ROPT_RESPXCH or ROPT_UPDXCH messages must also support ROPT_INITXCH messages.

4.1. ROPT_INITXCH: Specify Initial Characteristics

The ROPT_INITXCH message type allows an RPC-over-RDMA participant, whether client or server, to indicate to its partner relevant transport characteristics that the partner might need to be aware of.

<CODE BEGINS>

const uint32     ROPT_INITXCH = 1;

struct optinfo_initxch {
        xcharspec       optixch_start;
        xcharsubset     optixch_nochg;
};        
 
<CODE ENDS>
          

The message definition for this operation is as follows:

All relevant transport characteristics that the sender is aware of should be included in optixch_start. Since support of this request is OPTIONAL, and since each of the characteristics is OPTIONAL as well, the sender cannot assume that the receiver will necessarily take note of these characteristics and so the sender should be prepared for cases in which the partner continues to assume that the default value for a particular characteristic is still in effect.

The subset of transport characteristic specified by optixch_nochg is not expected to change during the lifetime of the connection.

Generally, a participant will send a ROPT_INITXCH message as the first message after a connection is established. Given that fact, the sender should make sure that the message can be received by partners who use the default Receive Buffer Size. The connection's initial receive buffer size is typically 1KB, but it depends on the initial connection state of the RPC-over-RDMA version in use. See [rpcrdmav2] for details.

Those receiving an ROPT_INITXCH may encounter characteristics that they do not support or are unaware of. In such cases, these characteristics are simply ignored without any error response being generated.

4.2. ROPT_REQXCH: Request Modification of Characteristics

The ROPT_REQXCH message type allows an RPC-over-RDMA participant, whether client or server, to request of its partner that relevant transport characteristics be changed.

The partner need not change the characteristics as requested by the sender but if it does support the message type, it will generate a ROPT_RESPXCH message, indicating the disposition of the request.

<CODE BEGINS>

const uint32     ROPT_REQXCH = 2;

struct optinfo_reqxch {
        xcharspec       optreqxch_want;
};        
 
<CODE ENDS>
          

The message definition for this operation is as follows:

The xcharspec optreqxch_want is a set of transport characteristics together with the desired values requested by the sender.

4.3. ROPT_RESPXCH: Respond to Request to Modify Transport Characteristics

The ROPT_RESPXCH message type allows an RPC-over-RDMA participant to respond to a request to change characteristics by its partner, indicating how the request was dealt with.

<CODE BEGINS>

const uint32     ROPT_RESPXCH = 3;

struct optinfo_respxch {
        xcharsubset     optrespxch_done;
        xcharsubset     optrespxch_rej;
        xcharsubset     optrespxch_pend;                        
};        
 
<CODE ENDS>
          

The message definition for this operation is as follows:

The rdma_xid field of this message must match that used in the ROPT_REQXCH message to which this message is responding.

The optrespxch_done field indicates which of the requested transport characteristic changes have been immediately effected. For each such characteristic, the receiver is entitled to conclude that the requested change has been made and that future transmissions may be made based on the new value.

The optrespxch_rej field indicates which of the requested transport characteristic changes have been rejected by the sender. This may be because of any of the following reasons:

• The particular characteristic specified is not known or supported by the receiver of the ROPT_REQXCH message.
• The implementation receiving the ROPT_REQXCH message does not support modification of this characteristic.
• The implementation receiving the ROPT_REQXCHG message has rejected the modification for another reason.

The optrespxch_pend field indicates which of the requested transport characteristic modifications remain pending, since they were neither rejected nor effected immediately. The receiver can expect the modification to be effected by a later ROPT_UPDXCH message, although there is no way to determine when this will happen. For each characteristic bit set in this field, one or more ROPT_UPXCH can be expected, the last of which will have optupdxch_pendclr flag set.

The subsets of characteristics specified by optrespxch_done, optrespxch_rej, optrespxch_pend should not overlap and, when ored together, should cover the entire set of characteristics specified by optreqxch_want in the corresponding request.

4.4. ROPT_UPDXCH: Update Transport Characteristics

The ROPT_UPDXCH message type allows an RPC-over-RDMA participant to notify the other participant that a change to the transport characteristics has occurred.

This may be because:

• A change requested by a ROPT_REQXCH message, has, after some delay, been effected.
• The sender has decided, independently, to modify the transport characteristic and is notifying the receiver of this change.

One should pay particular attention to the fact that there is no there no way to tie a message reporting a change to the specific request which asked for the change. In particular, the rdma_xid field in this message is independent of that for any earlier ROPT_REQXCH message.

<CODE BEGINS>
 
const uint32     ROPT_UPDXCH = 4;

struct optinfo_updxch {
        xcharval        optupdxch_now;
        bool            optupdxch_pendclr;
};        

<CODE ENDS>

          

The message definition for this operation is as follows:

optupdxch_now defines the new characteristic value to be used.

optupdxch_pendclr, if true, indicates that a previous request to update the characteristic specified by optupdxch_now.xchv_which is no longer to be considered pending. This may be set true even if the characteristic value is not changed from the previous value.

Some instances of ROPT_UPDXCH are the result of a previous a previous ROPT_REQXCH while others are unsolicited. This distinction relates to the setting of optupdxch_pendclr as follows:

• If a characteristic update is unsolicited, then optupdxch_pendclr will always be false.
• If a characteristic update is prompted by a previous ROPT_REQXCH and optupdxch_pendclr is true, then the current message indicates the (asynchronous) completion of that previous change request.
  
  In this case the disposition of the change request can be determined using optupdxch_now. If the value is that requested by the associated ROPT_REQXCH then the request was successful, while if the value is unchanged from the original value, the change can be considered rejected.
  
  In cases in which the characteristic has a range of values, intermediate value are possible, indicating a partial satisfaction of the original request.
• If a characteristic update is prompted by a previous ROPT_REQXCH and optupdxch_pendclr is false, then the current message does not indicate completion of a previous change request.
  
  In such cases, the characteristic value indicates the current value of the characteristic, which the receiver is entitled to rely upon, just as would have been the case if the change had been unsolicited.
  
  Nevertheless, the change request is still active and will remain so until a ROPT_UPDXCH with optupdxch_pendclr is received.

5. XDR

This section contains an XDR [RFC4506] description of the proposed extension.

<CODE BEGINS>

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

<CODE ENDS>

       

This description is provided in a way that makes it simple to extract into ready-to-use form. The reader can apply the following shell script to this document to produce a machine-readable XDR description of extension which can be combined with XDR for the base protocol to produce an XDR that combines the base protocol with the optional extensions.

<CODE BEGINS>

sh extract.sh < ext.txt > charext.x

<CODE ENDS>

        

That is, if the above script is stored in a file called "extract.sh" and this document is in a file called "ext.txt" then the reader can do the following to extract an XDR description file for this extension:

5.1. Code Component License

<CODE BEGINS>

/// /*
///  * Copyright (c) 2010, 2016 IETF Trust and the persons
///  * identified as authors of the code.  All rights reserved.
///  *
///  * The author of the code is: D. Noveck.
///  *
///  * Redistribution and use in source and binary forms, with
///  * or without modification, are permitted provided that the
///  * following conditions are met:
///  *
///  * - Redistributions of source code must retain the above
///  *   copyright notice, this list of conditions and the
///  *   following disclaimer.
///  *
///  * - Redistributions in binary form must reproduce the above
///  *   copyright notice, this list of conditions and the
///  *   following disclaimer in the documentation and/or other
///  *   materials provided with the distribution.
///  *
///  * - Neither the name of Internet Society, IETF or IETF
///  *   Trust, nor the names of specific contributors, may be
///  *   used to endorse or promote products derived from this
///  *   software without specific prior written permission.
///  *
///  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS
///  *   AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
///  *   WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
///  *   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
///  *   FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO
///  *   EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
///  *   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
///  *   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
///  *   NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
///  *   SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
///  *   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
///  *   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
///  *   OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
///  *   IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
///  *   ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
///  */

<CODE ENDS>

          

Code components extracted from this document must include the following license text. When the extracted XDR code is combined with other complementary XDR code which itself has an identical license, only a single copy of the license text need be preserved.

5.2. XDR Proper for Extension

<CODE BEGINS>

///
////*
/// * Basic transport characteristic types
/// */ 
///typedef xcharid         uint32;
///
///struct xcharval {
///        xcharid         xchv_which;
///        opaque          xchv_data<>;
///};
///
///typedef xcharspec       xcharval<>;
///
///typedef xcharsubset     uint32<>;
///
////*
/// * Transport characteristic codes
/// */
///const uint32    XCHAR_RBSIZ = 1;
///const uint32    XCHAR_REQREMINV = 2;
///const uint32    XCHAR_BRS = 3;
///
////*
/// * Other transport characteristic types
/// */
///enum bkreqsup {
///        BKREQSUP_NONE    = 0,
///        BKREQSUP_INLINE  = 1,
///        BKREQSUP_GENL    = 2
///};
///
////*
/// * Transport characteristic typedefs
/// */
///typedef uint32   xchrbsiz;
///typedef bool     xchrreqrem;
///typedef bkreqsup xchrbrs;                
///
////*
/// * Optional operation codes
/// */
///const uint32     ROPT_INITXCH = 1;
///const uint32     ROPT_REQXCH = 2;
///const uint32     ROPT_RESPXCH = 3;
///const uint32     ROPT_UPDXCH = 4;
///
////*
/// * Optional operation message structures
/// */
///struct optinfo_initxch {
///        xcharspec       optixch_start;
///        xcharsubset     optixch_nochg;
///};       
///
///struct optinfo_reqxch {
///        xcharspec       optreqxch_want;
///};        
///
///struct optinfo_respxch {
///        xcharsubset     optrespxch_done;
///        xcharsubset     optrespxch_rej;
///        xcharsubset     optrespxch_pend;                        
///};        
///
///struct optinfo_updxch {
///        xcharval        optupdxch_now;
///        bool            optupdxch_pendclr;
///};        

<CODE ENDS>
          

6. Extensibility

6.1. Additional Characteristics

The set of transport characteristics is designed to be extensible. As a result, once new characteristics are defined in standards track documents, the operations defined in this document may reference these new transport characteristics, as well as the ones described in this document.

A standards track document defining a new transport characteristic should include the following information paralleling that provided in this document for the transport characteristics defined herein.

• The xcharid value used to identify this characteristic.
• The XDR typedef specifying the form in which the characteristic value is communicated.
• A description of the transport characteristic that is communicated by the sender of ROPT_INITXCH and ROPT_UPDXCH and requested by the sender of ROP_REQXCH.
• An explanation of how this knowledge could be used by the participant receiving this information.
• Information giving rules governing possible changes of values of this characteristic.

The definition of transport characteristic structures is such as to make it easy to assign unique values. There is no requirement that a continuous set of values be used and implementations should not rely on all such values being small integers. A unique value should be selected when the defining document is first published as an internet draft. When the document becomes a standards track document working group should insure that:

• The xcharids specified in the document do not conflict with those currently assigned or in use by other pending working group documents defining transport characteristics.
• The xcharids specified in the document do not conflict with the range reserved for experimental use, as defined in Section 6.2.

Documents defining new characteristics fall into a number of categories.

• Those defining new characteristics and explaining (only) how they affect use of existing message types.
• Those defining new OPTIONAL message types and new characteristics applicable to the operation of those new message types.
• Those defining new OPTIONAL message types and new characteristics applicable both to new and existing message types.

When additional transport characteristics are proposed, the review of the associated standards track document should deal with possible security issues raised by those new transport characteristics.

6.2. Experimental Characteristics

Given the design of the transport characteristics data structure, it possible to use the operations to implement experimental, possibly unpublished, transport characteristics.

xcharids in the range from 4,294,967,040 to 4,294,967,295 are reserved for experimental use and these values should not be assigned to new characteristics in standards track documents.

When values in this range are used there is no guarantee if successful interoperation among independent implementations.

7. Security Considerations

Like other fields that appear in each RPC-over-RDMA header, characteristic information is sent in the clear on the fabric with no integrity protection, making it vulnerable to man-in-the-middle attacks.

For example, if a man-in-the-middle were to change the value of the Receive buffer size or the Requester Remote Invalidation boolean, it could reduce connection performance or trigger loss of connection. Repeated connection loss can impact performance or even prevent a new connection from being established. Recourse is to deploy on a private network or use link-layer encryption.

8. IANA Considerations

This document does not require any actions by IANA.

9. References

9.1. Normative References

[bidir]	Lever, C., "Size-Limited Bi-directional Remote Procedure Call On Remote Direct Memory Access Transports", April 2016. Work in progress.
[RFC2119]	Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[RFC4506]	Eisler, M., "XDR: External Data Representation Standard", STD 67, RFC 4506, DOI 10.17487/RFC4506, May 2006.
[rfc5666bis]	Lever, C., Simpson, W. and T. Talpey, "Remote Direct Memory Access Transport for Remote Procedure Call", May 2016. Work in progress.
[rpcrdmav2]	Lever, C. and D. Noveck, "RPC-over-RDMA Version Two", June 2016. Work in progress.

9.2. Informative References

[RFC5662]	Shepler, S., Eisler, M. and D. Noveck, "Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description", RFC 5662, DOI 10.17487/RFC5662, January 2010.
[RFC5666]	Talpey, T. and B. Callaghan, "Remote Direct Memory Access Transport for Remote Procedure Call", RFC 5666, DOI 10.17487/RFC5666, January 2010.

Appendix A. Acknowledgments

The author gratefully acknowledges the work of Brent Callaghan and Tom Talpey producing the original RPC-over-RDMA Version One specification [RFC5666] and also Tom's work in helping to clarify that specification.

The author also wishes to thank Chuck Lever for his work resurrecting NFS support for RDMA in [rfc5666bis] and for his helpful review of and suggestions for this document.

The extract.sh shell script and formatting conventions were first described by the authors of the NFSv4.1 XDR specification [RFC5662].

Author's Address