[linux-2.6-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.

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.

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   |
I  | GETDEVICEINFO        | OPT        | pNFS (REQ)   | Section 18.40  |
NS*| GETDEVICELIST        | OPT        | pNFS (OPT)   | Section 18.41  |
   | GETFH                | REQ        |              | Section 18.8   |
NS*| GET_DIR_DELEGATION   | OPT        | DDELG (REQ)  | Section 18.39  |
I  | LAYOUTCOMMIT         | OPT        | pNFS (REQ)   | Section 18.42  |
I  | LAYOUTGET            | OPT        | pNFS (REQ)   | Section 18.43  |
I  | 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  |
I  | CB_LAYOUTRECALL         | OPT       | pNFS (REQ)  | Section 20.3  |
NS*| CB_NOTIFY               | OPT       | DDELG (REQ) | Section 20.4  |
NS*| 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
3ef17288 BH	27	The table below, taken from the NFSv4.1 document, lists
	28	the operations that are mandatory to implement (REQ), optional
	29	(OPT), and NFSv4.0 operations that are required not to implement (MNI)
	30	in minor version 1. The first column indicates the operations that
	31	are not supported yet by the linux server implementation.
	32
	33	The OPTIONAL features identified and their abbreviations are as follows:
	34	pNFS Parallel NFS
	35	FDELG File Delegations
	36	DDELG Directory Delegations
	37
	38	The following abbreviations indicate the linux server implementation status.
	39	I Implemented NFSv4.1 operations.
	40	NS Not Supported.
18d1aef8	41	NS* Unimplemented optional feature.
3ef17288 BH	42
	43	Operations
	44
	45	+----------------------+------------+--------------+----------------+
	46	\| Operation \| REQ, REC, \| Feature \| Definition \|
	47	\| \| OPT, or \| (REQ, REC, \| \|
	48	\| \| MNI \| or OPT) \| \|
	49	+----------------------+------------+--------------+----------------+
	50	\| ACCESS \| REQ \| \| Section 18.1 \|
cb73a9f4	51	I \| BACKCHANNEL_CTL \| REQ \| \| Section 18.33 \|
c46556c6	52	I \| BIND_CONN_TO_SESSION \| REQ \| \| Section 18.34 \|
3ef17288 BH	53	\| CLOSE \| REQ \| \| Section 18.2 \|
	54	\| COMMIT \| REQ \| \| Section 18.3 \|
	55	\| CREATE \| REQ \| \| Section 18.4 \|
	56	I \| CREATE_SESSION \| REQ \| \| Section 18.36 \|
	57	NS*\| DELEGPURGE \| OPT \| FDELG (REQ) \| Section 18.5 \|
	58	\| DELEGRETURN \| OPT \| FDELG, \| Section 18.6 \|
	59	\| \| \| DDELG, pNFS \| \|
	60	\| \| \| (REQ) \| \|
292a4171	61	I \| DESTROY_CLIENTID \| REQ \| \| Section 18.50 \|
3ef17288 BH	62	I \| DESTROY_SESSION \| REQ \| \| Section 18.37 \|
3ef17288 BH	63	I \| EXCHANGE_ID \| REQ \| \| Section 18.35 \|
c46556c6	64	I \| FREE_STATEID \| REQ \| \| Section 18.38 \|
3ef17288	65	\| GETATTR \| REQ \| \| Section 18.7 \|
18d1aef8 CH	66	I \| GETDEVICEINFO \| OPT \| pNFS (REQ) \| Section 18.40 \|
18d1aef8 CH	67	NS*\| GETDEVICELIST \| OPT \| pNFS (OPT) \| Section 18.41 \|
3ef17288 BH	68	\| GETFH \| REQ \| \| Section 18.8 \|
3ef17288 BH	69	NS*\| GET_DIR_DELEGATION \| OPT \| DDELG (REQ) \| Section 18.39 \|
18d1aef8 CH	70	I \| LAYOUTCOMMIT \| OPT \| pNFS (REQ) \| Section 18.42 \|
	71	I \| LAYOUTGET \| OPT \| pNFS (REQ) \| Section 18.43 \|
	72	I \| LAYOUTRETURN \| OPT \| pNFS (REQ) \| Section 18.44 \|
3ef17288 BH	73	\| LINK \| OPT \| \| Section 18.9 \|
	74	\| LOCK \| REQ \| \| Section 18.10 \|
	75	\| LOCKT \| REQ \| \| Section 18.11 \|
	76	\| LOCKU \| REQ \| \| Section 18.12 \|
	77	\| LOOKUP \| REQ \| \| Section 18.13 \|
	78	\| LOOKUPP \| REQ \| \| Section 18.14 \|
	79	\| NVERIFY \| REQ \| \| Section 18.15 \|
	80	\| OPEN \| REQ \| \| Section 18.16 \|
	81	NS*\| OPENATTR \| OPT \| \| Section 18.17 \|
	82	\| OPEN_CONFIRM \| MNI \| \| N/A \|
	83	\| OPEN_DOWNGRADE \| REQ \| \| Section 18.18 \|
	84	\| PUTFH \| REQ \| \| Section 18.19 \|
	85	\| PUTPUBFH \| REQ \| \| Section 18.20 \|
	86	\| PUTROOTFH \| REQ \| \| Section 18.21 \|
	87	\| READ \| REQ \| \| Section 18.22 \|
	88	\| READDIR \| REQ \| \| Section 18.23 \|
	89	\| READLINK \| OPT \| \| Section 18.24 \|
4dc6ec00	90	\| RECLAIM_COMPLETE \| REQ \| \| Section 18.51 \|
3ef17288 BH	91	\| RELEASE_LOCKOWNER \| MNI \| \| N/A \|
	92	\| REMOVE \| REQ \| \| Section 18.25 \|
	93	\| RENAME \| REQ \| \| Section 18.26 \|
	94	\| RENEW \| MNI \| \| N/A \|
	95	\| RESTOREFH \| REQ \| \| Section 18.27 \|
	96	\| SAVEFH \| REQ \| \| Section 18.28 \|
	97	\| SECINFO \| REQ \| \| Section 18.29 \|
c46556c6	98	I \| SECINFO_NO_NAME \| REC \| pNFS files \| Section 18.45, \|
3ef17288 BH	99	\| \| \| layout (REQ) \| Section 13.12 \|
	100	I \| SEQUENCE \| REQ \| \| Section 18.46 \|
	101	\| SETATTR \| REQ \| \| Section 18.30 \|
	102	\| SETCLIENTID \| MNI \| \| N/A \|
	103	\| SETCLIENTID_CONFIRM \| MNI \| \| N/A \|
	104	NS \| SET_SSV \| REQ \| \| Section 18.47 \|
c46556c6	105	I \| TEST_STATEID \| REQ \| \| Section 18.48 \|
3ef17288 BH	106	\| VERIFY \| REQ \| \| Section 18.31 \|
	107	NS*\| WANT_DELEGATION \| OPT \| FDELG (OPT) \| Section 18.49 \|
	108	\| WRITE \| REQ \| \| Section 18.32 \|
	109
	110	Callback Operations
	111
	112	+-------------------------+-----------+-------------+---------------+
	113	\| Operation \| REQ, REC, \| Feature \| Definition \|
	114	\| \| OPT, or \| (REQ, REC, \| \|
	115	\| \| MNI \| or OPT) \| \|
	116	+-------------------------+-----------+-------------+---------------+
	117	\| CB_GETATTR \| OPT \| FDELG (REQ) \| Section 20.1 \|
18d1aef8	118	I \| CB_LAYOUTRECALL \| OPT \| pNFS (REQ) \| Section 20.3 \|
3ef17288	119	NS*\| CB_NOTIFY \| OPT \| DDELG (REQ) \| Section 20.4 \|
18d1aef8	120	NS*\| CB_NOTIFY_DEVICEID \| OPT \| pNFS (OPT) \| Section 20.12 \|
3ef17288 BH	121	NS*\| CB_NOTIFY_LOCK \| OPT \| \| Section 20.11 \|
	122	NS*\| CB_PUSH_DELEG \| OPT \| FDELG (OPT) \| Section 20.5 \|
	123	\| CB_RECALL \| OPT \| FDELG, \| Section 20.2 \|
	124	\| \| \| DDELG, pNFS \| \|
	125	\| \| \| (REQ) \| \|
	126	NS*\| CB_RECALL_ANY \| OPT \| FDELG, \| Section 20.6 \|
	127	\| \| \| DDELG, pNFS \| \|
	128	\| \| \| (REQ) \| \|
	129	NS \| CB_RECALL_SLOT \| REQ \| \| Section 20.8 \|
	130	NS*\| CB_RECALLABLE_OBJ_AVAIL \| OPT \| DDELG, pNFS \| Section 20.7 \|
	131	\| \| \| (REQ) \| \|
	132	I \| CB_SEQUENCE \| OPT \| FDELG, \| Section 20.9 \|
	133	\| \| \| DDELG, pNFS \| \|
	134	\| \| \| (REQ) \| \|
	135	NS*\| CB_WANTS_CANCELLED \| OPT \| FDELG, \| Section 20.10 \|
	136	\| \| \| DDELG, pNFS \| \|
	137	\| \| \| (REQ) \| \|
	138	+-------------------------+-----------+-------------+---------------+
	139
	140	Implementation notes:
	141
4bd8eabc BF	142	SSV:
	143	* The spec claims this is mandatory, but we don't actually know of any
	144	implementations, so we're ignoring it for now. The server returns
	145	NFS4ERR_ENCR_ALG_UNSUPP on EXCHANGE_ID, which should be future-proof.
	146
	147	GSS on the backchannel:
	148	* Again, theoretically required but not widely implemented (in
	149	particular, the current Linux client doesn't request it). We return
	150	NFS4ERR_ENCR_ALG_UNSUPP on CREATE_SESSION.
	151
285a0f00 BF	152	DELEGPURGE:
	153	* mandatory only for servers that support CLAIM_DELEGATE_PREV and/or
	154	CLAIM_DELEG_PREV_FH (which allows clients to keep delegations that
	155	persist across client reboots). Thus we need not implement this for
	156	now.
	157
3ef17288	158	EXCHANGE_ID:
3ef17288 BH	159	* implementation ids are ignored
	160
	161	CREATE_SESSION:
	162	* backchannel attributes are ignored
3ef17288 BH	163
	164	SEQUENCE:
	165	* no support for dynamic slot table renegotiation (optional)
	166
ddc04fd4 AA	167	Nonstandard compound limitations:
	168	* No support for a sessions fore channel RPC compound that requires both a
	169	ca_maxrequestsize request and a ca_maxresponsesize reply, so we may
	170	fail to live up to the promise we made in CREATE_SESSION fore channel
	171	negotiation.
c46556c6 BF	172
c46556c6 BF	173	See also http://wiki.linux-nfs.org/wiki/index.php/Server_4.0_and_4.1_issues.