Found wdiff, but it reported no recognisable version. Falling back to builtin diff colouring... Diff: draft-20-pre-ch3.txt - draft-ietf-nfsv4-minorversion1-20.txt
 draft-20-pre-ch3.txt   draft-ietf-nfsv4-minorversion1-20.txt 
NFSv4 S. Shepler NFSv4 S. Shepler
Internet-Draft M. Eisler Internet-Draft M. Eisler
Intended status: Standards Track D. Noveck Intended status: Standards Track D. Noveck
Expires: August 22, 2008 Editors Expires: August 23, 2008 Editors
February 19, 2008 February 20, 2008
NFS Version 4 Minor Version 1 NFS Version 4 Minor Version 1
draft-ietf-nfsv4-minorversion1-20.txt draft-ietf-nfsv4-minorversion1-20.txt
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79. aware will be disclosed, in accordance with Section 6 of BCP 79.
skipping to change at page 1, line 35 skipping to change at page 1, line 35
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 22, 2008. This Internet-Draft will expire on August 23, 2008.
Copyright Notice Copyright Notice
Copyright (C) The IETF Trust (2008). Copyright (C) The IETF Trust (2008).
Abstract Abstract
This Internet-Draft describes NFS version 4 minor version one, This Internet-Draft describes NFS version 4 minor version one,
including features retained from the base protocol and protocol including features retained from the base protocol and protocol
extensions made subsequently. Major extensions introduced in NFS extensions made subsequently. Major extensions introduced in NFS
skipping to change at page 3, line 21 skipping to change at page 3, line 21
2.10.11. Parallel NFS and Sessions . . . . . . . . . . . . . 75 2.10.11. Parallel NFS and Sessions . . . . . . . . . . . . . 75
3. Protocol Constants and Data Types . . . . . . . . . . . . . . 76 3. Protocol Constants and Data Types . . . . . . . . . . . . . . 76
3.1. Basic Constants . . . . . . . . . . . . . . . . . . . . 76 3.1. Basic Constants . . . . . . . . . . . . . . . . . . . . 76
3.2. Basic Data Types . . . . . . . . . . . . . . . . . . . . 77 3.2. Basic Data Types . . . . . . . . . . . . . . . . . . . . 77
3.3. Structured Data Types . . . . . . . . . . . . . . . . . 78 3.3. Structured Data Types . . . . . . . . . . . . . . . . . 78
4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . 88 4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . 88
4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 88 4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 88
4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . 88 4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . 88
4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . 89 4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . 89
4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 89 4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 89
4.2.1. General Properties of a Filehandle . . . . . . . . . 89 4.2.1. General Properties of a Filehandle . . . . . . . . . 90
4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . 90 4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . 90
4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . 90 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . 91
4.3. One Method of Constructing a Volatile Filehandle . . . . 92 4.3. One Method of Constructing a Volatile Filehandle . . . . 92
4.4. Client Recovery from Filehandle Expiration . . . . . . . 92 4.4. Client Recovery from Filehandle Expiration . . . . . . . 92
5. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 93 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 93
5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . 94 5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . 95
5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 95 5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 95
5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 95 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 95
5.4. Classification of Attributes . . . . . . . . . . . . . . 97 5.4. Classification of Attributes . . . . . . . . . . . . . . 97
5.5. REQUIRED Attributes - List and Definition References . . 98 5.5. REQUIRED Attributes - List and Definition References . . 98
5.6. RECOMMENDED Attributes - List and Definition 5.6. RECOMMENDED Attributes - List and Definition
References . . . . . . . . . . . . . . . . . . . . . . . 98 References . . . . . . . . . . . . . . . . . . . . . . . 98
5.7. Attribute Definitions . . . . . . . . . . . . . . . . . 100 5.7. Attribute Definitions . . . . . . . . . . . . . . . . . 100
5.7.1. Definitions of REQUIRED Attributes . . . . . . . . . 100 5.7.1. Definitions of REQUIRED Attributes . . . . . . . . . 100
5.7.2. Definitions of Uncategorized RECOMMENDED 5.7.2. Definitions of Uncategorized RECOMMENDED
Attributes . . . . . . . . . . . . . . . . . . . . . 102 Attributes . . . . . . . . . . . . . . . . . . . . . 102
skipping to change at page 77, line 21 skipping to change at page 77, line 21
These are the base NFSv4.1 data types. These are the base NFSv4.1 data types.
+---------------+---------------------------------------------------+ +---------------+---------------------------------------------------+
| Data Type | Definition | | Data Type | Definition |
+---------------+---------------------------------------------------+ +---------------+---------------------------------------------------+
| int32_t | typedef int int32_t; | | int32_t | typedef int int32_t; |
| uint32_t | typedef unsigned int uint32_t; | | uint32_t | typedef unsigned int uint32_t; |
| int64_t | typedef hyper int64_t; | | int64_t | typedef hyper int64_t; |
| uint64_t | typedef unsigned hyper uint64_t; | | uint64_t | typedef unsigned hyper uint64_t; |
| attrlist4 | typedef opaque attrlist4<>; | | attrlist4 | typedef opaque attrlist4<>; |
| | Used for file/directory attributes | | | Used for file/directory attributes. |
| bitmap4 | typedef uint32_t bitmap4<>; | | bitmap4 | typedef uint32_t bitmap4<>; |
| | Used in attribute array encoding. | | | Used in attribute array encoding. |
| changeid4 | typedef uint64_t changeid4; | | changeid4 | typedef uint64_t changeid4; |
| | Used in definition of change_info | | | Used in the definition of change_info4. |
| clientid4 | typedef uint64_t clientid4; | | clientid4 | typedef uint64_t clientid4; |
| | Shorthand reference to client identification | | | Shorthand reference to client identification. |
| count4 | typedef uint32_t count4; | | count4 | typedef uint32_t count4; |
| | Various count parameters (READ, WRITE, COMMIT) | | | Various count parameters (READ, WRITE, COMMIT). |
| length4 | typedef uint64_t length4; | | length4 | typedef uint64_t length4; |
| | Describes LOCK lengths | | | Describes LOCK lengths. |
| mode4 | typedef uint32_t mode4; | | mode4 | typedef uint32_t mode4; |
| | Mode attribute data type | | | Mode attribute data type. |
| nfs_cookie4 | typedef uint64_t nfs_cookie4; | | nfs_cookie4 | typedef uint64_t nfs_cookie4; |
| | Opaque cookie value for READDIR | | | Opaque cookie value for READDIR. |
| nfs_fh4 | typedef opaque nfs_fh4<NFS4_FHSIZE>; | | nfs_fh4 | typedef opaque nfs_fh4<NFS4_FHSIZE>; |
| | Filehandle definition | | | Filehandle definition. |
| nfs_ftype4 | enum nfs_ftype4; | | nfs_ftype4 | enum nfs_ftype4; |
| | Various defined file types | | | Various defined file types. |
| nfsstat4 | enum nfsstat4; | | nfsstat4 | enum nfsstat4; |
| | Return value for operations | | | Return value for operations. |
| offset4 | typedef uint64_t offset4; | | offset4 | typedef uint64_t offset4; |
| | Various offset designations (READ, WRITE, LOCK, | | | Various offset designations (READ, WRITE, LOCK, |
| | COMMIT) | | | COMMIT). |
| qop4 | typedef uint32_t qop4; | | qop4 | typedef uint32_t qop4; |
| | Quality of protection designation in SECINFO | | | Quality of protection designation in SECINFO. |
| sec_oid4 | typedef opaque sec_oid4<>; | | sec_oid4 | typedef opaque sec_oid4<>; |
| | Security Object Identifier. The sec_oid4 data | | | Security Object Identifier. The sec_oid4 data |
| | type is not really opaque. Instead it contains an | | | type is not really opaque. Instead it contains an |
| | ASN.1 OBJECT IDENTIFIER as used by GSS-API in the | | | ASN.1 OBJECT IDENTIFIER as used by GSS-API in the |
| | mech_type argument to GSS_Init_sec_context. See | | | mech_type argument to GSS_Init_sec_context. See |
| | [7] for details. | | | [7] for details. |
| sequenceid4 | typedef uint32_t sequenceid4; | | sequenceid4 | typedef uint32_t sequenceid4; |
| | sequence number used for various session | | | Sequence number used for various session |
| | operations (EXCHANGE_ID, CREATE_SESSION, | | | operations (EXCHANGE_ID, CREATE_SESSION, |
| | SEQUENCE, CB_SEQUENCE). | | | SEQUENCE, CB_SEQUENCE). |
| seqid4 | typedef uint32_t seqid4; | | seqid4 | typedef uint32_t seqid4; |
| | Sequence identifier used for file locking | | | Sequence identifier used for file locking. |
| sessionid4 | typedef opaque sessionid4[NFS4_SESSIONID_SIZE]; | | sessionid4 | typedef opaque sessionid4[NFS4_SESSIONID_SIZE]; |
| | Session identifier | | | Session identifier. |
| slotid4 | typedef uint32_t slotid4; | | slotid4 | typedef uint32_t slotid4; |
| | sequencing artifact for various session | | | Sequencing artifact for various session |
| | operations (SEQUENCE, CB_SEQUENCE). | | | operations (SEQUENCE, CB_SEQUENCE). |
| utf8string | typedef opaque utf8string<>; | | utf8string | typedef opaque utf8string<>; |
| | UTF-8 encoding for strings | | | UTF-8 encoding for strings. |
| utf8str_cis | typedef utf8string utf8str_cis; | | utf8str_cis | typedef utf8string utf8str_cis; |
| | Case-insensitive UTF-8 string | | | Case-insensitive UTF-8 string. |
| utf8str_cs | typedef utf8string utf8str_cs; | | utf8str_cs | typedef utf8string utf8str_cs; |
| | Case-sensitive UTF-8 string | | | Case-sensitive UTF-8 string. |
| utf8str_mixed | typedef utf8string utf8str_mixed; | | utf8str_mixed | typedef utf8string utf8str_mixed; |
| | UTF-8 strings with a case sensitive prefix and a | | | UTF-8 strings with a case sensitive prefix and a |
| | case insensitive suffix. | | | case insensitive suffix. |
| component4 | typedef utf8str_cs component4; | | component4 | typedef utf8str_cs component4; |
| | Represents path name components | | | Represents path name components. |
| linktext4 | typedef utf8str_cs linktext4; | | linktext4 | typedef utf8str_cs linktext4; |
| | Symbolic link contents | | | Symbolic link contents. |
| pathname4 | typedef component4 pathname4<>; | | pathname4 | typedef component4 pathname4<>; |
| | Represents path name for fs_locations | | | Represents path name for fs_locations. |
| verifier4 | typedef opaque verifier4[NFS4_VERIFIER_SIZE]; | | verifier4 | typedef opaque verifier4[NFS4_VERIFIER_SIZE]; |
| | Verifier used for various operations (COMMIT, | | | Verifier used for various operations (COMMIT, |
| | CREATE, EXCHANGE_ID, OPEN, READDIR, WRITE) | | | CREATE, EXCHANGE_ID, OPEN, READDIR, WRITE) |
| | NFS4_VERIFIER_SIZE is defined as 8. | | | NFS4_VERIFIER_SIZE is defined as 8. |
+---------------+---------------------------------------------------+ +---------------+---------------------------------------------------+
End of Base Data Types End of Base Data Types
Table 1 Table 1
3.3. Structured Data Types 3.3. Structured Data Types
3.3.1. nfstime4 3.3.1. nfstime4
struct nfstime4 { struct nfstime4 {
int64_t seconds; int64_t seconds;
uint32_t nseconds; uint32_t nseconds;
}; };
The nfstime4 structure gives the number of seconds and nanoseconds The nfstime4 data type gives the number of seconds and nanoseconds
since midnight or 0 hour January 1, 1970 Coordinated Universal Time since midnight or 0 hour January 1, 1970 Coordinated Universal Time
(UTC). Values greater than zero for the seconds field denote dates (UTC). Values greater than zero for the seconds field denote dates
after the 0 hour January 1, 1970. Values less than zero for the after the 0 hour January 1, 1970. Values less than zero for the
seconds field denote dates before the 0 hour January 1, 1970. In seconds field denote dates before the 0 hour January 1, 1970. In
both cases, the nseconds field is to be added to the seconds field both cases, the nseconds field is to be added to the seconds field
for the final time representation. For example, if the time to be for the final time representation. For example, if the time to be
represented is one-half second before 0 hour January 1, 1970, the represented is one-half second before 0 hour January 1, 1970, the
seconds field would have a value of negative one (-1) and the seconds field would have a value of negative one (-1) and the
nseconds fields would have a value of one-half second (500000000). nseconds fields would have a value of one-half second (500000000).
Values greater than 999,999,999 for nseconds are considered invalid. Values greater than 999,999,999 for nseconds are invalid.
This data type is used to pass time and date information. A server This data type is used to pass time and date information. A server
converts to and from its local representation of time when processing converts to and from its local representation of time when processing
time values, preserving as much accuracy as possible. If the time values, preserving as much accuracy as possible. If the
precision of timestamps stored for a file system object is less than precision of timestamps stored for a file system object is less than
defined, loss of precision can occur. An adjunct time maintenance defined, loss of precision can occur. An adjunct time maintenance
protocol is RECOMMENDED to reduce client and server time skew. protocol is RECOMMENDED to reduce client and server time skew.
3.3.2. time_how4 3.3.2. time_how4
skipping to change at page 79, line 36 skipping to change at page 79, line 36
3.3.3. settime4 3.3.3. settime4
union settime4 switch (time_how4 set_it) { union settime4 switch (time_how4 set_it) {
case SET_TO_CLIENT_TIME4: case SET_TO_CLIENT_TIME4:
nfstime4 time; nfstime4 time;
default: default:
void; void;
}; };
The above definitions are used as the attribute definitions to set The time_how4 and settime4 data types are used for setting timestamps
time values. If set_it is SET_TO_SERVER_TIME4, then the server uses in file object attributes. If set_it is SET_TO_SERVER_TIME4, then
its local representation of time for the time value. the server uses its local representation of time for the time value.
3.3.4. specdata4 3.3.4. specdata4
struct specdata4 { struct specdata4 {
uint32_t specdata1; /* major device number */ uint32_t specdata1; /* major device number */
uint32_t specdata2; /* minor device number */ uint32_t specdata2; /* minor device number */
}; };
This data type represents additional information for the device file This data type represents the device numbers for the device file
types NF4CHR and NF4BLK. types NF4CHR and NF4BLK.
3.3.5. fsid4 3.3.5. fsid4
struct fsid4 { struct fsid4 {
uint64_t major; uint64_t major;
uint64_t minor; uint64_t minor;
}; };
3.3.6. chg_policy4 3.3.6. chg_policy4
skipping to change at page 80, line 34 skipping to change at page 80, line 34
id and the second to be incremented non-persistently, within a given id and the second to be incremented non-persistently, within a given
server instance. server instance.
3.3.7. fattr4 3.3.7. fattr4
struct fattr4 { struct fattr4 {
bitmap4 attrmask; bitmap4 attrmask;
attrlist4 attr_vals; attrlist4 attr_vals;
}; };
The fattr4 structure is used to represent file and directory The fattr4 data type is used to represent file and directory
attributes. attributes.
The bitmap is a counted array of 32 bit integers used to contain bit The bitmap is a counted array of 32 bit integers used to contain bit
values. The position of the integer in the array that contains bit n values. The position of the integer in the array that contains bit n
can be computed from the expression (n / 32) and its bit within that can be computed from the expression (n / 32) and its bit within that
integer is (n mod 32). integer is (n mod 32).
0 1 0 1
+-----------+-----------+-----------+-- +-----------+-----------+-----------+--
| count | 31 .. 0 | 63 .. 32 | | count | 31 .. 0 | 63 .. 32 |
+-----------+-----------+-----------+-- +-----------+-----------+-----------+--
3.3.8. change_info4 3.3.8. change_info4
struct change_info4 { struct change_info4 {
bool atomic; bool atomic;
changeid4 before; changeid4 before;
changeid4 after; changeid4 after;
}; };
This structure is used with the CREATE, LINK, REMOVE, RENAME This data type is used with the CREATE, LINK, OPEN, REMOVE, and
operations to let the client know the value of the change attribute RENAME operations to let the client know the value of the change
for the directory in which the target file system object resides. attribute for the directory in which the target file system object
resides.
3.3.9. netaddr4 3.3.9. netaddr4
struct netaddr4 { struct netaddr4 {
/* see struct rpcb in RFC 1833 */ /* see struct rpcb in RFC 1833 */
string na_r_netid<>; /* network id */ string na_r_netid<>; /* network id */
string na_r_addr<>; /* universal address */ string na_r_addr<>; /* universal address */
}; };
The netaddr4 structure is used to identify TCP/IP based endpoints. The netaddr4 data type is used to identify TCP/IP based endpoints.
The r_netid and r_addr fields are specified in RFC1833 [26], but they The r_netid and r_addr fields are specified in RFC1833 [26], but they
are underspecified in RFC1833 [26] as far as what they should look are underspecified in RFC1833 [26] as far as what they should look
like for specific protocols. like for specific protocols. The next section clarifies this.
3.3.9.1. Format of netaddr4 for TCP and UDP over IPv4 3.3.9.1. Format of netaddr4 for TCP and UDP over IPv4
For TCP over IPv4 and for UDP over IPv4, the format of r_addr is the For TCP over IPv4 and for UDP over IPv4, the format of r_addr is the
US-ASCII string: US-ASCII string:
h1.h2.h3.h4.p1.p2 h1.h2.h3.h4.p1.p2
The prefix, "h1.h2.h3.h4", is the standard textual form for The prefix, "h1.h2.h3.h4", is the standard textual form for
representing an IPv4 address, which is always four bytes long. representing an IPv4 address, which is always four bytes long.
Assuming big-endian ordering, h1, h2, h3, and h4, are respectively, Assuming big-endian ordering, h1, h2, h3, and h4, are respectively,
the first through fourth bytes each converted to ASCII-decimal. the first through fourth bytes each converted to ASCII-decimal. The
Assuming big-endian ordering, p1 and p2 are, respectively, the first suffix, "p1.p2", is a textual form for representing a TCP and UDP
and second bytes each converted to ASCII-decimal. For example, if a service port. Assuming big-endian ordering, p1 and p2 are,
host, in big-endian order, has an address of 0x0A010307 and there is respectively, the first and second bytes each converted to ASCII-
a service listening on, in big endian order, port 0x020F (decimal decimal. For example, if a host, in big-endian order, has an address
527), then complete universal address is "10.1.3.7.2.15". of 0x0A010307 and there is a service listening on, in big endian
order, port 0x020F (decimal 527), then the complete universal address
is "10.1.3.7.2.15".
For TCP over IPv4 the value of r_netid is the string "tcp". For UDP For TCP over IPv4 the value of r_netid is the string "tcp". For UDP
over IPv4 the value of r_netid is the string "udp". That this over IPv4 the value of r_netid is the string "udp". That this
document specifies the universal address and netid for UDP/IPv6 does document specifies the universal address and netid for UDP/IPv6 does
not imply that UDP/IPv4 is a legal transport for NFSv4.1 (see not imply that UDP/IPv4 is a legal transport for NFSv4.1 (see
Section 2.9). Section 2.9).
3.3.9.2. Format of netaddr4 for TCP and UDP over IPv6 3.3.9.2. Format of netaddr4 for TCP and UDP over IPv6
For TCP over IPv6 and for UDP over IPv6, the format of r_addr is the For TCP over IPv6 and for UDP over IPv6, the format of r_addr is the
skipping to change at page 82, line 40 skipping to change at page 82, line 42
}; };
typedef state_owner4 open_owner4; typedef state_owner4 open_owner4;
typedef state_owner4 lock_owner4; typedef state_owner4 lock_owner4;
The state_owner4 data type is the base type for the open_owner4 The state_owner4 data type is the base type for the open_owner4
Section 3.3.10.1 and lock_owner4 Section 3.3.10.2. Section 3.3.10.1 and lock_owner4 Section 3.3.10.2.
3.3.10.1. open_owner4 3.3.10.1. open_owner4
This structure is used to identify the owner of open state. This data type is used to identify the owner of open state.
3.3.10.2. lock_owner4 3.3.10.2. lock_owner4
This structure is used to identify the owner of file locking state. This data type is used to identify the owner of file locking state.
3.3.11. open_to_lock_owner4 3.3.11. open_to_lock_owner4
struct open_to_lock_owner4 { struct open_to_lock_owner4 {
seqid4 open_seqid; seqid4 open_seqid;
stateid4 open_stateid; stateid4 open_stateid;
seqid4 lock_seqid; seqid4 lock_seqid;
lock_owner4 lock_owner; lock_owner4 lock_owner;
}; };
This structure is used for the first LOCK operation done for an This data type is used for the first LOCK operation done for an
open_owner4. It provides both the open_stateid and lock_owner such open_owner4. It provides both the open_stateid and lock_owner such
that the transition is made from a valid open_stateid sequence to that the transition is made from a valid open_stateid sequence to
that of the new lock_stateid sequence. Using this mechanism avoids that of the new lock_stateid sequence. Using this mechanism avoids
the confirmation of the lock_owner/lock_seqid pair since it is tied the confirmation of the lock_owner/lock_seqid pair since it is tied
to established state in the form of the open_stateid/open_seqid. to established state in the form of the open_stateid/open_seqid.
3.3.12. stateid4 3.3.12. stateid4
struct stateid4 { struct stateid4 {
uint32_t seqid; uint32_t seqid;
opaque other[12]; opaque other[12];
}; };
This structure is used for the various state sharing mechanisms This data type is used for the various state sharing mechanisms
between the client and server. For the client, this data structure between the client and server. The client never modifies a value of
is read-only. The starting value of the seqid field is undefined. data type stateid. The starting value of the seqid field is
The server is required to increment the seqid field monotonically at undefined. The server is required to increment the seqid field by
each transition of the stateid. This is important since the client one (1) at each transition of the stateid. This is important since
will inspect the seqid in OPEN stateids to determine the order of the client will inspect the seqid in OPEN stateids to determine the
OPEN processing done by the server. order of OPEN processing done by the server.
3.3.13. layouttype4 3.3.13. layouttype4
enum layouttype4 { enum layouttype4 {
LAYOUT4_NFSV4_1_FILES = 1, LAYOUT4_NFSV4_1_FILES = 0x1,
LAYOUT4_OSD2_OBJECTS = 2, LAYOUT4_OSD2_OBJECTS = 0x2,
LAYOUT4_BLOCK_VOLUME = 3 LAYOUT4_BLOCK_VOLUME = 0x3
}; };
This data type indicates what type of layout is being used. The file This data type indicates what type of layout is being used. The file
server advertises the layout types it supports through the server advertises the layout types it supports through the
fs_layout_type file system attribute (Section 5.11.1). A client asks fs_layout_type file system attribute (Section 5.11.1). A client asks
for layouts of a particular type in LAYOUTGET, and processes those for layouts of a particular type in LAYOUTGET, and processes those
layouts in its layout-type-specific logic. layouts in its layout-type-specific logic.
The layouttype4 structure is 32 bits in length. The range The layouttype4 data type is 32 bits in length. The range
represented by the layout type is split into three parts. Type 0x0 represented by the layout type is split into three parts. Type 0x0
is reserved. Types within the range 0x00000001-0x7FFFFFFF are is reserved. Types within the range 0x00000001-0x7FFFFFFF are
globally unique and are assigned according to the description in globally unique and are assigned according to the description in
Section 22.4; they are maintained by IANA. Types within the range Section 22.4; they are maintained by IANA. Types within the range
0x80000000-0xFFFFFFFF are site specific and for "private use" only. 0x80000000-0xFFFFFFFF are site specific and for private use only.
The LAYOUT4_NFSV4_1_FILES enumeration specifies that the NFSv4.1 file The LAYOUT4_NFSV4_1_FILES enumeration specifies that the NFSv4.1 file
layout type is to be used. The LAYOUT4_OSD2_OBJECTS enumeration layout type, as defined in Section 13, is to be used. The
specifies that the object layout, as defined in [30], is to be used. LAYOUT4_OSD2_OBJECTS enumeration specifies that the object layout, as
Similarly, the LAYOUT4_BLOCK_VOLUME enumeration that the block/volume defined in [30], is to be used. Similarly, the LAYOUT4_BLOCK_VOLUME
layout, as defined in [31], is to be used. enumeration specifies that the block/volume layout, as defined in
[31], is to be used.
3.3.14. deviceid4 3.3.14. deviceid4
const NFS4_DEVICEID4_SIZE = 16; const NFS4_DEVICEID4_SIZE = 16;
typedef opaque deviceid4[NFS4_DEVICEID4_SIZE]; typedef opaque deviceid4[NFS4_DEVICEID4_SIZE];
Layout information includes device IDs that specify a storage device Layout information includes device IDs that specify a storage device
through a compact handle. Addressing and type information is through a compact handle. Addressing and type information is
obtained with the GETDEVICEINFO operation. A client must not assume obtained with the GETDEVICEINFO operation. Device IDs are not
that device IDs are valid across metadata server reboots. The device guaranteed to be valid across metadata server reboots. A device ID
ID is qualified by the layout type and are unique per file system is unique per client ID and layout type. See Section 12.2.10 for
(FSID). See Section 12.2.10 for more details. more details.
3.3.15. device_addr4 3.3.15. device_addr4
struct device_addr4 { struct device_addr4 {
layouttype4 da_layout_type; layouttype4 da_layout_type;
opaque da_addr_body<>; opaque da_addr_body<>;
}; };
The device address is used to set up a communication channel with the The device address is used to set up a communication channel with the
storage device. Different layout types will require different types storage device. Different layout types will require different data
of structures to define how they communicate with storage devices. types to define how they communicate with storage devices. The
The opaque da_addr_body field must be interpreted based on the opaque da_addr_body field must be interpreted based on the specified
specified da_layout_type field. da_layout_type field.
This document defines the device address for the NFSv4.1 file layout This document defines the device address for the NFSv4.1 file layout
(see Section 13.3), which identifies a storage device by network IP (see Section 13.3), which identifies a storage device by network IP
address and port number. This is sufficient for the clients to address and port number. This is sufficient for the clients to
communicate with the NFSv4.1 storage devices, and may be sufficient communicate with the NFSv4.1 storage devices, and may be sufficient
for other layout types as well. Device types for object storage for other layout types as well. Device types for object storage
devices and block storage devices (e.g., SCSI volume labels) will be devices and block storage devices (e.g., SCSI volume labels) will be
defined by their respective layout specifications. defined by their respective layout specifications.
3.3.16. layout_content4 3.3.16. layout_content4
skipping to change at page 85, line 25 skipping to change at page 85, line 25
3.3.17. layout4 3.3.17. layout4
struct layout4 { struct layout4 {
offset4 lo_offset; offset4 lo_offset;
length4 lo_length; length4 lo_length;
layoutiomode4 lo_iomode; layoutiomode4 lo_iomode;
layout_content4 lo_content; layout_content4 lo_content;
}; };
The layout4 structure defines a layout for a file. The layout type The layout4 data type defines a layout for a file. The layout type
specific data is opaque within lo_content. Since layouts are sub- specific data is opaque within lo_content. Since layouts are sub-
dividable, the offset and length together with the file's filehandle, dividable, the offset and length together with the file's filehandle,
the client ID, iomode, and layout type, identify the layout. the client ID, iomode, and layout type, identify the layout.
3.3.18. layoutupdate4 3.3.18. layoutupdate4
struct layoutupdate4 { struct layoutupdate4 {
layouttype4 lou_type; layouttype4 lou_type;
opaque lou_body<>; opaque lou_body<>;
}; };
The layoutupdate4 structure is used by the client to return 'updated' The layoutupdate4 data type is used by the client to return updated
layout information to the metadata server at LAYOUTCOMMIT time. This layout information to the metadata server via the LAYOUTCOMMIT
structure provides a channel to pass layout type specific information (Section 18.42) operation. This data type provides a channel to pass
(in field lou_body) back to the metadata server. E.g., for block/ layout type specific information (in field lou_body) back to the
volume layout types this could include the list of reserved blocks metadata server. E.g., for the block/volume layout type this could
that were written. The contents of the opaque lou_body argument are include the list of reserved blocks that were written. The contents
determined by the layout type and are defined in their context. The of the opaque lou_body argument are determined by the layout type.
NFSv4.1 file-based layout does not use this structure, thus the The NFSv4.1 file-based layout does not use this data type; if
lou_body field should have a zero length. lou_type is LAYOUT4_NFSV4_1_FILES, the lou_body field MUST have a
zero length.
3.3.19. layouthint4 3.3.19. layouthint4
struct layouthint4 { struct layouthint4 {
layouttype4 loh_type; layouttype4 loh_type;
opaque loh_body<>; opaque loh_body<>;
}; };
The layouthint4 structure is used by the client to pass in a hint
The layouthint4 data type is used by the client to pass in a hint
about the type of layout it would like created for a particular file. about the type of layout it would like created for a particular file.
It is the structure specified by the layout_hint attribute described It is the data type specified by the layout_hint attribute described
in Section 5.11.4. The metadata server may ignore the hint, or may in Section 5.11.4. The metadata server may ignore the hint, or may
selectively ignore fields within the hint. This hint should be selectively ignore fields within the hint. This hint should be
provided at create time as part of the initial attributes within provided at create time as part of the initial attributes within
OPEN. The loh_body field is specific to the type of layout OPEN. The loh_body field is specific to the type of layout
(loh_type). The NFSv4.1 file-based layout uses the (loh_type). The NFSv4.1 file-based layout uses the
nfsv4_1_file_layouthint4 structure as defined in Section 13.3. nfsv4_1_file_layouthint4 data type as defined in Section 13.3.
3.3.20. layoutiomode4 3.3.20. layoutiomode4
enum layoutiomode4 { enum layoutiomode4 {
LAYOUTIOMODE4_READ = 1, LAYOUTIOMODE4_READ = 1,
LAYOUTIOMODE4_RW = 2, LAYOUTIOMODE4_RW = 2,
LAYOUTIOMODE4_ANY = 3 LAYOUTIOMODE4_ANY = 3
}; };
The iomode specifies whether the client intends to read or write The iomode specifies whether the client intends to just read or both
(with the possibility of reading) the data represented by the layout. read and write the data represented by the layout. While the
The ANY iomode MUST NOT be used for LAYOUTGET, however, it can be LAYOUTIOMODE4_ANY iomode MUST NOT be used in the arguments to the
used for LAYOUTRETURN and CB_LAYOUTRECALL. The ANY iomode specifies LAYOUTGET operation, it MAY be used in the arguments to the
that layouts pertaining to both READ and RW iomodes are being LAYOUTRETURN and CB_LAYOUTRECALL operations. The LAYOUTIOMODE4_ANY
returned or recalled, respectively. The metadata server's use of the iomode specifies that layouts pertaining to both LAYOUTIOMODE4_READ
iomode may depend on the layout type being used. The storage devices and LAYOUTIOMODE4_RW iomodes are being returned or recalled,
may validate I/O accesses against the iomode and reject invalid respectively. The metadata server's use of the iomode may depend on
accesses. the layout type being used. The storage devices MAY validate I/O
accesses against the iomode and reject invalid accesses.
3.3.21. nfs_impl_id4 3.3.21. nfs_impl_id4
struct nfs_impl_id4 { struct nfs_impl_id4 {
utf8str_cis nii_domain; utf8str_cis nii_domain;
utf8str_cs nii_name; utf8str_cs nii_name;
nfstime4 nii_date; nfstime4 nii_date;
}; };
This structure is used to identify client and server implementation This data type is used to identify client and server implementation
detail. The nii_domain field is the DNS domain name that the details. The nii_domain field is the DNS domain name that the
implementer is associated with. The nii_name field is the product implementer is associated with. The nii_name field is the product
name of the implementation and is completely free form. It is name of the implementation and is completely free form. It is
RECOMMENDED that the nii_name be used to distinguish machine RECOMMENDED that the nii_name be used to distinguish machine
architecture, machine platforms, revisions, versions, and patch architecture, machine platforms, revisions, versions, and patch
levels. The nii_date field is the timestamp of when the software levels. The nii_date field is the timestamp of when the software
instance was published or built. instance was published or built.
3.3.22. threshold_item4 3.3.22. threshold_item4
struct threshold_item4 { struct threshold_item4 {
layouttype4 thi_layout_type; layouttype4 thi_layout_type;
bitmap4 thi_hintset; bitmap4 thi_hintset;
opaque thi_hintlist<>; opaque thi_hintlist<>;
}; };
This structure contains a list of hints specific to a layout type for This data type contains a list of hints specific to a layout type for
helping the client determine when it should send I/O directly through helping the client determine when it should send I/O directly through
the metadata server vs. the data servers. The hint structure the metadata server versus the storage devices. The data type
consists of the layout type (thi_layout_type), a bitmap (thi_hintset) consists of the layout type (thi_layout_type), a bitmap (thi_hintset)
describing the set of hints supported by the server (they may differ describing the set of hints supported by the server (they may differ
based on the layout type), and a list of hints (thi_hintlist), whose based on the layout type), and a list of hints (thi_hintlist), whose
structure is determined by the hintset bitmap. See the mdsthreshold content is determined by the hintset bitmap. See the mdsthreshold
attribute for more details. attribute for more details.
The thi_hintset field is a bitmap of the following values: The thi_hintset field is a bitmap of the following values:
+-------------------------+---+---------+---------------------------+ +-------------------------+---+---------+---------------------------+
| name | # | Data | Description | | name | # | Data | Description |
| | | Type | | | | | Type | |
+-------------------------+---+---------+---------------------------+ +-------------------------+---+---------+---------------------------+
| threshold4_read_size | 0 | length4 | The file size below which | | threshold4_read_size | 0 | length4 | The file size below which |
| | | | it is RECOMMENDED to read | | | | | it is RECOMMENDED to read |
skipping to change at page 87, line 51 skipping to change at page 88, line 11
| | | | RECOMMENDED to write data | | | | | RECOMMENDED to write data |
| | | | through the MDS | | | | | through the MDS |
+-------------------------+---+---------+---------------------------+ +-------------------------+---+---------+---------------------------+
3.3.23. mdsthreshold4 3.3.23. mdsthreshold4
struct mdsthreshold4 { struct mdsthreshold4 {
threshold_item4 mth_hints<>; threshold_item4 mth_hints<>;
}; };
This structure holds an array of threshold_item4 structures each of This data type holds an array of elements of data type
which is valid for a particular layout type. An array is necessary threshold_item4, each of which is valid for a particular layout type.
since a server can support multiple layout types for a single file. An array is necessary because a server can support multiple layout
types for a single file.
4. Filehandles 4. Filehandles
The filehandle in the NFS protocol is a per server unique identifier The filehandle in the NFS protocol is a per server unique identifier
for a file system object. The contents of the filehandle are opaque for a file system object. The contents of the filehandle are opaque
to the client. Therefore, the server is responsible for translating to the client. Therefore, the server is responsible for translating
the filehandle to an internal representation of the file system the filehandle to an internal representation of the file system
object. object.
4.1. Obtaining the First Filehandle 4.1. Obtaining the First Filehandle
 End of changes. 57 change blocks. 
103 lines changed or deleted 111 lines changed or added

This html diff was produced by rfcdiff 1.33. The latest version is available from http://tools.ietf.org/tools/rfcdiff/