[linux-block.git] / Documentation / filesystems / nfs / nfs41-server.txt

NFSv4.1 Server Implementation

Server support for minorversion 1 can be controlled using the
/proc/fs/nfsd/versions control file.  The string output returned
by reading this file will contain either "+4.1" or "-4.1"
correspondingly.

Currently, server support for minorversion 1 is enabled by default.
It can be disabled at run time by writing the string "-4.1" to
the /proc/fs/nfsd/versions control file.  Note that to write this
control file, the nfsd service must be taken down.  You can use rpc.nfsd
for this; see rpc.nfsd(8).

(Warning: older servers will interpret "+4.1" and "-4.1" as "+4" and
"-4", respectively.  Therefore, code meant to work on both new and old
kernels must turn 4.1 on or off *before* turning support for version 4
on or off; rpc.nfsd does this correctly.)

The NFSv4 minorversion 1 (NFSv4.1) implementation in nfsd is based
on RFC 5661.

From the many new features in NFSv4.1 the current implementation
focuses on the mandatory-to-implement NFSv4.1 Sessions, providing
"exactly once" semantics and better control and throttling of the
resources allocated for each client.

Other NFSv4.1 features, Parallel NFS operations in particular,
are still under development out of tree.
See http://wiki.linux-nfs.org/wiki/index.php/PNFS_prototype_design
for more information.

The table below, taken from the NFSv4.1 document, lists
the operations that are mandatory to implement (REQ), optional
(OPT), and NFSv4.0 operations that are required not to implement (MNI)
in minor version 1.  The first column indicates the operations that
are not supported yet by the linux server implementation.

The OPTIONAL features identified and their abbreviations are as follows:
	pNFS	Parallel NFS
	FDELG	File Delegations
	DDELG	Directory Delegations

The following abbreviations indicate the linux server implementation status.
	I	Implemented NFSv4.1 operations.
	NS	Not Supported.
	NS*	unimplemented optional feature.
	P	pNFS features implemented out of tree.
	PNS	pNFS features that are not supported yet (out of tree).

Operations

   +----------------------+------------+--------------+----------------+
   | Operation            | REQ, REC,  | Feature      | Definition     |
   |                      | OPT, or    | (REQ, REC,   |                |
   |                      | MNI        | or OPT)      |                |
   +----------------------+------------+--------------+----------------+
   | ACCESS               | REQ        |              | Section 18.1   |
I  | BACKCHANNEL_CTL      | REQ        |              | Section 18.33  |
I  | BIND_CONN_TO_SESSION | REQ        |              | Section 18.34  |
   | CLOSE                | REQ        |              | Section 18.2   |
   | COMMIT               | REQ        |              | Section 18.3   |
   | CREATE               | REQ        |              | Section 18.4   |
I  | CREATE_SESSION       | REQ        |              | Section 18.36  |
NS*| DELEGPURGE           | OPT        | FDELG (REQ)  | Section 18.5   |
   | DELEGRETURN          | OPT        | FDELG,       | Section 18.6   |
   |                      |            | DDELG, pNFS  |                |
   |                      |            | (REQ)        |                |
I  | DESTROY_CLIENTID     | REQ        |              | Section 18.50  |
I  | DESTROY_SESSION      | REQ        |              | Section 18.37  |
I  | EXCHANGE_ID          | REQ        |              | Section 18.35  |
I  | FREE_STATEID         | REQ        |              | Section 18.38  |
   | GETATTR              | REQ        |              | Section 18.7   |
P  | GETDEVICEINFO        | OPT        | pNFS (REQ)   | Section 18.40  |
P  | GETDEVICELIST        | OPT        | pNFS (OPT)   | Section 18.41  |
   | GETFH                | REQ        |              | Section 18.8   |
NS*| GET_DIR_DELEGATION   | OPT        | DDELG (REQ)  | Section 18.39  |
P  | LAYOUTCOMMIT         | OPT        | pNFS (REQ)   | Section 18.42  |
P  | LAYOUTGET            | OPT        | pNFS (REQ)   | Section 18.43  |
P  | LAYOUTRETURN         | OPT        | pNFS (REQ)   | Section 18.44  |
   | LINK                 | OPT        |              | Section 18.9   |
   | LOCK                 | REQ        |              | Section 18.10  |
   | LOCKT                | REQ        |              | Section 18.11  |
   | LOCKU                | REQ        |              | Section 18.12  |
   | LOOKUP               | REQ        |              | Section 18.13  |
   | LOOKUPP              | REQ        |              | Section 18.14  |
   | NVERIFY              | REQ        |              | Section 18.15  |
   | OPEN                 | REQ        |              | Section 18.16  |
NS*| OPENATTR             | OPT        |              | Section 18.17  |
   | OPEN_CONFIRM         | MNI        |              | N/A            |
   | OPEN_DOWNGRADE       | REQ        |              | Section 18.18  |
   | PUTFH                | REQ        |              | Section 18.19  |
   | PUTPUBFH             | REQ        |              | Section 18.20  |
   | PUTROOTFH            | REQ        |              | Section 18.21  |
   | READ                 | REQ        |              | Section 18.22  |
   | READDIR              | REQ        |              | Section 18.23  |
   | READLINK             | OPT        |              | Section 18.24  |
   | RECLAIM_COMPLETE     | REQ        |              | Section 18.51  |
   | RELEASE_LOCKOWNER    | MNI        |              | N/A            |
   | REMOVE               | REQ        |              | Section 18.25  |
   | RENAME               | REQ        |              | Section 18.26  |
   | RENEW                | MNI        |              | N/A            |
   | RESTOREFH            | REQ        |              | Section 18.27  |
   | SAVEFH               | REQ        |              | Section 18.28  |
   | SECINFO              | REQ        |              | Section 18.29  |
I  | SECINFO_NO_NAME      | REC        | pNFS files   | Section 18.45, |
   |                      |            | layout (REQ) | Section 13.12  |
I  | SEQUENCE             | REQ        |              | Section 18.46  |
   | SETATTR              | REQ        |              | Section 18.30  |
   | SETCLIENTID          | MNI        |              | N/A            |
   | SETCLIENTID_CONFIRM  | MNI        |              | N/A            |
NS | SET_SSV              | REQ        |              | Section 18.47  |
I  | TEST_STATEID         | REQ        |              | Section 18.48  |
   | VERIFY               | REQ        |              | Section 18.31  |
NS*| WANT_DELEGATION      | OPT        | FDELG (OPT)  | Section 18.49  |
   | WRITE                | REQ        |              | Section 18.32  |

Callback Operations

   +-------------------------+-----------+-------------+---------------+
   | Operation               | REQ, REC, | Feature     | Definition    |
   |                         | OPT, or   | (REQ, REC,  |               |
   |                         | MNI       | or OPT)     |               |
   +-------------------------+-----------+-------------+---------------+
   | CB_GETATTR              | OPT       | FDELG (REQ) | Section 20.1  |
P  | CB_LAYOUTRECALL         | OPT       | pNFS (REQ)  | Section 20.3  |
NS*| CB_NOTIFY               | OPT       | DDELG (REQ) | Section 20.4  |
P  | CB_NOTIFY_DEVICEID      | OPT       | pNFS (OPT)  | Section 20.12 |
NS*| CB_NOTIFY_LOCK          | OPT       |             | Section 20.11 |
NS*| CB_PUSH_DELEG           | OPT       | FDELG (OPT) | Section 20.5  |
   | CB_RECALL               | OPT       | FDELG,      | Section 20.2  |
   |                         |           | DDELG, pNFS |               |
   |                         |           | (REQ)       |               |
NS*| CB_RECALL_ANY           | OPT       | FDELG,      | Section 20.6  |
   |                         |           | DDELG, pNFS |               |
   |                         |           | (REQ)       |               |
NS | CB_RECALL_SLOT          | REQ       |             | Section 20.8  |
NS*| CB_RECALLABLE_OBJ_AVAIL | OPT       | DDELG, pNFS | Section 20.7  |
   |                         |           | (REQ)       |               |
I  | CB_SEQUENCE             | OPT       | FDELG,      | Section 20.9  |
   |                         |           | DDELG, pNFS |               |
   |                         |           | (REQ)       |               |
NS*| CB_WANTS_CANCELLED      | OPT       | FDELG,      | Section 20.10 |
   |                         |           | DDELG, pNFS |               |
   |                         |           | (REQ)       |               |
   +-------------------------+-----------+-------------+---------------+

Implementation notes:

SSV:
* The spec claims this is mandatory, but we don't actually know of any
  implementations, so we're ignoring it for now.  The server returns
  NFS4ERR_ENCR_ALG_UNSUPP on EXCHANGE_ID, which should be future-proof.

GSS on the backchannel:
* Again, theoretically required but not widely implemented (in
  particular, the current Linux client doesn't request it).  We return
  NFS4ERR_ENCR_ALG_UNSUPP on CREATE_SESSION.

DELEGPURGE:
* mandatory only for servers that support CLAIM_DELEGATE_PREV and/or
  CLAIM_DELEG_PREV_FH (which allows clients to keep delegations that
  persist across client reboots).  Thus we need not implement this for
  now.

EXCHANGE_ID:
* implementation ids are ignored

CREATE_SESSION:
* backchannel attributes are ignored

SEQUENCE:
* no support for dynamic slot table renegotiation (optional)

Nonstandard compound limitations:
* No support for a sessions fore channel RPC compound that requires both a
  ca_maxrequestsize request and a ca_maxresponsesize reply, so we may
  fail to live up to the promise we made in CREATE_SESSION fore channel
  negotiation.

See also http://wiki.linux-nfs.org/wiki/index.php/Server_4.0_and_4.1_issues.
Commit	Line	Data
3ef17288 BH	1	NFSv4.1 Server Implementation
	2
	3	Server support for minorversion 1 can be controlled using the
	4	/proc/fs/nfsd/versions control file. The string output returned
	5	by reading this file will contain either "+4.1" or "-4.1"
	6	correspondingly.
	7
4bd8eabc BF	8	Currently, server support for minorversion 1 is enabled by default.
4bd8eabc BF	9	It can be disabled at run time by writing the string "-4.1" to
3ef17288	10	the /proc/fs/nfsd/versions control file. Note that to write this
4bd8eabc BF	11	control file, the nfsd service must be taken down. You can use rpc.nfsd
4bd8eabc BF	12	for this; see rpc.nfsd(8).
3ef17288	13
285a0f00 BF	14	(Warning: older servers will interpret "+4.1" and "-4.1" as "+4" and
	15	"-4", respectively. Therefore, code meant to work on both new and old
	16	kernels must turn 4.1 on or off before turning support for version 4
	17	on or off; rpc.nfsd does this correctly.)
	18
3ef17288	19	The NFSv4 minorversion 1 (NFSv4.1) implementation in nfsd is based
73834d6f	20	on RFC 5661.
3ef17288 BH	21
	22	From the many new features in NFSv4.1 the current implementation
	23	focuses on the mandatory-to-implement NFSv4.1 Sessions, providing
	24	"exactly once" semantics and better control and throttling of the
	25	resources allocated for each client.
	26
	27	Other NFSv4.1 features, Parallel NFS operations in particular,
	28	are still under development out of tree.
	29	See http://wiki.linux-nfs.org/wiki/index.php/PNFS_prototype_design
	30	for more information.
	31
	32	The table below, taken from the NFSv4.1 document, lists
	33	the operations that are mandatory to implement (REQ), optional
	34	(OPT), and NFSv4.0 operations that are required not to implement (MNI)
	35	in minor version 1. The first column indicates the operations that
	36	are not supported yet by the linux server implementation.
	37
	38	The OPTIONAL features identified and their abbreviations are as follows:
	39	pNFS Parallel NFS
	40	FDELG File Delegations
	41	DDELG Directory Delegations
	42
	43	The following abbreviations indicate the linux server implementation status.
	44	I Implemented NFSv4.1 operations.
	45	NS Not Supported.
	46	NS* unimplemented optional feature.
	47	P pNFS features implemented out of tree.
	48	PNS pNFS features that are not supported yet (out of tree).
	49
	50	Operations
	51
	52	+----------------------+------------+--------------+----------------+
	53	\| Operation \| REQ, REC, \| Feature \| Definition \|
	54	\| \| OPT, or \| (REQ, REC, \| \|
	55	\| \| MNI \| or OPT) \| \|
	56	+----------------------+------------+--------------+----------------+
	57	\| ACCESS \| REQ \| \| Section 18.1 \|
cb73a9f4	58	I \| BACKCHANNEL_CTL \| REQ \| \| Section 18.33 \|
c46556c6	59	I \| BIND_CONN_TO_SESSION \| REQ \| \| Section 18.34 \|
3ef17288 BH	60	\| CLOSE \| REQ \| \| Section 18.2 \|
	61	\| COMMIT \| REQ \| \| Section 18.3 \|
	62	\| CREATE \| REQ \| \| Section 18.4 \|
	63	I \| CREATE_SESSION \| REQ \| \| Section 18.36 \|
	64	NS*\| DELEGPURGE \| OPT \| FDELG (REQ) \| Section 18.5 \|
	65	\| DELEGRETURN \| OPT \| FDELG, \| Section 18.6 \|
	66	\| \| \| DDELG, pNFS \| \|
	67	\| \| \| (REQ) \| \|
292a4171	68	I \| DESTROY_CLIENTID \| REQ \| \| Section 18.50 \|
3ef17288 BH	69	I \| DESTROY_SESSION \| REQ \| \| Section 18.37 \|
3ef17288 BH	70	I \| EXCHANGE_ID \| REQ \| \| Section 18.35 \|
c46556c6	71	I \| FREE_STATEID \| REQ \| \| Section 18.38 \|
3ef17288 BH	72	\| GETATTR \| REQ \| \| Section 18.7 \|
	73	P \| GETDEVICEINFO \| OPT \| pNFS (REQ) \| Section 18.40 \|
	74	P \| GETDEVICELIST \| OPT \| pNFS (OPT) \| Section 18.41 \|
	75	\| GETFH \| REQ \| \| Section 18.8 \|
	76	NS*\| GET_DIR_DELEGATION \| OPT \| DDELG (REQ) \| Section 18.39 \|
	77	P \| LAYOUTCOMMIT \| OPT \| pNFS (REQ) \| Section 18.42 \|
	78	P \| LAYOUTGET \| OPT \| pNFS (REQ) \| Section 18.43 \|
	79	P \| LAYOUTRETURN \| OPT \| pNFS (REQ) \| Section 18.44 \|
	80	\| LINK \| OPT \| \| Section 18.9 \|
	81	\| LOCK \| REQ \| \| Section 18.10 \|
	82	\| LOCKT \| REQ \| \| Section 18.11 \|
	83	\| LOCKU \| REQ \| \| Section 18.12 \|
	84	\| LOOKUP \| REQ \| \| Section 18.13 \|
	85	\| LOOKUPP \| REQ \| \| Section 18.14 \|
	86	\| NVERIFY \| REQ \| \| Section 18.15 \|
	87	\| OPEN \| REQ \| \| Section 18.16 \|
	88	NS*\| OPENATTR \| OPT \| \| Section 18.17 \|
	89	\| OPEN_CONFIRM \| MNI \| \| N/A \|
	90	\| OPEN_DOWNGRADE \| REQ \| \| Section 18.18 \|
	91	\| PUTFH \| REQ \| \| Section 18.19 \|
	92	\| PUTPUBFH \| REQ \| \| Section 18.20 \|
	93	\| PUTROOTFH \| REQ \| \| Section 18.21 \|
	94	\| READ \| REQ \| \| Section 18.22 \|
	95	\| READDIR \| REQ \| \| Section 18.23 \|
	96	\| READLINK \| OPT \| \| Section 18.24 \|
4dc6ec00	97	\| RECLAIM_COMPLETE \| REQ \| \| Section 18.51 \|
3ef17288 BH	98	\| RELEASE_LOCKOWNER \| MNI \| \| N/A \|
	99	\| REMOVE \| REQ \| \| Section 18.25 \|
	100	\| RENAME \| REQ \| \| Section 18.26 \|
	101	\| RENEW \| MNI \| \| N/A \|
	102	\| RESTOREFH \| REQ \| \| Section 18.27 \|
	103	\| SAVEFH \| REQ \| \| Section 18.28 \|
	104	\| SECINFO \| REQ \| \| Section 18.29 \|
c46556c6	105	I \| SECINFO_NO_NAME \| REC \| pNFS files \| Section 18.45, \|
3ef17288 BH	106	\| \| \| layout (REQ) \| Section 13.12 \|
	107	I \| SEQUENCE \| REQ \| \| Section 18.46 \|
	108	\| SETATTR \| REQ \| \| Section 18.30 \|
	109	\| SETCLIENTID \| MNI \| \| N/A \|
	110	\| SETCLIENTID_CONFIRM \| MNI \| \| N/A \|
	111	NS \| SET_SSV \| REQ \| \| Section 18.47 \|
c46556c6	112	I \| TEST_STATEID \| REQ \| \| Section 18.48 \|
3ef17288 BH	113	\| VERIFY \| REQ \| \| Section 18.31 \|
	114	NS*\| WANT_DELEGATION \| OPT \| FDELG (OPT) \| Section 18.49 \|
	115	\| WRITE \| REQ \| \| Section 18.32 \|
	116
	117	Callback Operations
	118
	119	+-------------------------+-----------+-------------+---------------+
	120	\| Operation \| REQ, REC, \| Feature \| Definition \|
	121	\| \| OPT, or \| (REQ, REC, \| \|
	122	\| \| MNI \| or OPT) \| \|
	123	+-------------------------+-----------+-------------+---------------+
	124	\| CB_GETATTR \| OPT \| FDELG (REQ) \| Section 20.1 \|
	125	P \| CB_LAYOUTRECALL \| OPT \| pNFS (REQ) \| Section 20.3 \|
	126	NS*\| CB_NOTIFY \| OPT \| DDELG (REQ) \| Section 20.4 \|
	127	P \| CB_NOTIFY_DEVICEID \| OPT \| pNFS (OPT) \| Section 20.12 \|
	128	NS*\| CB_NOTIFY_LOCK \| OPT \| \| Section 20.11 \|
	129	NS*\| CB_PUSH_DELEG \| OPT \| FDELG (OPT) \| Section 20.5 \|
	130	\| CB_RECALL \| OPT \| FDELG, \| Section 20.2 \|
	131	\| \| \| DDELG, pNFS \| \|
	132	\| \| \| (REQ) \| \|
	133	NS*\| CB_RECALL_ANY \| OPT \| FDELG, \| Section 20.6 \|
	134	\| \| \| DDELG, pNFS \| \|
	135	\| \| \| (REQ) \| \|
	136	NS \| CB_RECALL_SLOT \| REQ \| \| Section 20.8 \|
	137	NS*\| CB_RECALLABLE_OBJ_AVAIL \| OPT \| DDELG, pNFS \| Section 20.7 \|
	138	\| \| \| (REQ) \| \|
	139	I \| CB_SEQUENCE \| OPT \| FDELG, \| Section 20.9 \|
	140	\| \| \| DDELG, pNFS \| \|
	141	\| \| \| (REQ) \| \|
	142	NS*\| CB_WANTS_CANCELLED \| OPT \| FDELG, \| Section 20.10 \|
	143	\| \| \| DDELG, pNFS \| \|
	144	\| \| \| (REQ) \| \|
	145	+-------------------------+-----------+-------------+---------------+
	146
	147	Implementation notes:
	148
4bd8eabc BF	149	SSV:
	150	* The spec claims this is mandatory, but we don't actually know of any
	151	implementations, so we're ignoring it for now. The server returns
	152	NFS4ERR_ENCR_ALG_UNSUPP on EXCHANGE_ID, which should be future-proof.
	153
	154	GSS on the backchannel:
	155	* Again, theoretically required but not widely implemented (in
	156	particular, the current Linux client doesn't request it). We return
	157	NFS4ERR_ENCR_ALG_UNSUPP on CREATE_SESSION.
	158
285a0f00 BF	159	DELEGPURGE:
	160	* mandatory only for servers that support CLAIM_DELEGATE_PREV and/or
	161	CLAIM_DELEG_PREV_FH (which allows clients to keep delegations that
	162	persist across client reboots). Thus we need not implement this for
	163	now.
	164
3ef17288	165	EXCHANGE_ID:
3ef17288 BH	166	* implementation ids are ignored
	167
	168	CREATE_SESSION:
	169	* backchannel attributes are ignored
3ef17288 BH	170
	171	SEQUENCE:
	172	* no support for dynamic slot table renegotiation (optional)
	173
ddc04fd4 AA	174	Nonstandard compound limitations:
	175	* No support for a sessions fore channel RPC compound that requires both a
	176	ca_maxrequestsize request and a ca_maxresponsesize reply, so we may
	177	fail to live up to the promise we made in CREATE_SESSION fore channel
	178	negotiation.
c46556c6 BF	179
c46556c6 BF	180	See also http://wiki.linux-nfs.org/wiki/index.php/Server_4.0_and_4.1_issues.