About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / filesystems / nfs / nfs.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

1	
2	The NFS client
3	==============
4	
5	The NFS version 2 protocol was first documented in RFC1094 (March 1989).
6	Since then two more major releases of NFS have been published, with NFSv3
7	being documented in RFC1813 (June 1995), and NFSv4 in RFC3530 (April
8	2003).
9	
10	The Linux NFS client currently supports all the above published versions,
11	and work is in progress on adding support for minor version 1 of the NFSv4
12	protocol.
13	
14	The purpose of this document is to provide information on some of the
15	special features of the NFS client that can be configured by system
16	administrators.
17	
18	
19	The nfs4_unique_id parameter
20	============================
21	
22	NFSv4 requires clients to identify themselves to servers with a unique
23	string.  File open and lock state shared between one client and one server
24	is associated with this identity.  To support robust NFSv4 state recovery
25	and transparent state migration, this identity string must not change
26	across client reboots.
27	
28	Without any other intervention, the Linux client uses a string that contains
29	the local system's node name.  System administrators, however, often do not
30	take care to ensure that node names are fully qualified and do not change
31	over the lifetime of a client system.  Node names can have other
32	administrative requirements that require particular behavior that does not
33	work well as part of an nfs_client_id4 string.
34	
35	The nfs.nfs4_unique_id boot parameter specifies a unique string that can be
36	used instead of a system's node name when an NFS client identifies itself to
37	a server.  Thus, if the system's node name is not unique, or it changes, its
38	nfs.nfs4_unique_id stays the same, preventing collision with other clients
39	or loss of state during NFS reboot recovery or transparent state migration.
40	
41	The nfs.nfs4_unique_id string is typically a UUID, though it can contain
42	anything that is believed to be unique across all NFS clients.  An
43	nfs4_unique_id string should be chosen when a client system is installed,
44	just as a system's root file system gets a fresh UUID in its label at
45	install time.
46	
47	The string should remain fixed for the lifetime of the client.  It can be
48	changed safely if care is taken that the client shuts down cleanly and all
49	outstanding NFSv4 state has expired, to prevent loss of NFSv4 state.
50	
51	This string can be stored in an NFS client's grub.conf, or it can be provided
52	via a net boot facility such as PXE.  It may also be specified as an nfs.ko
53	module parameter.  Specifying a uniquifier string is not support for NFS
54	clients running in containers.
55	
56	
57	The DNS resolver
58	================
59	
60	NFSv4 allows for one server to refer the NFS client to data that has been
61	migrated onto another server by means of the special "fs_locations"
62	attribute. See
63		http://tools.ietf.org/html/rfc3530#section-6
64	and
65		http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00
66	
67	The fs_locations information can take the form of either an ip address and
68	a path, or a DNS hostname and a path. The latter requires the NFS client to
69	do a DNS lookup in order to mount the new volume, and hence the need for an
70	upcall to allow userland to provide this service.
71	
72	Assuming that the user has the 'rpc_pipefs' filesystem mounted in the usual
73	/var/lib/nfs/rpc_pipefs, the upcall consists of the following steps:
74	
75	   (1) The process checks the dns_resolve cache to see if it contains a
76	       valid entry. If so, it returns that entry and exits.
77	
78	   (2) If no valid entry exists, the helper script '/sbin/nfs_cache_getent'
79	       (may be changed using the 'nfs.cache_getent' kernel boot parameter)
80	       is run, with two arguments:
81			- the cache name, "dns_resolve"
82			- the hostname to resolve
83	
84	   (3) After looking up the corresponding ip address, the helper script
85	       writes the result into the rpc_pipefs pseudo-file
86	       '/var/lib/nfs/rpc_pipefs/cache/dns_resolve/channel'
87	       in the following (text) format:
88	
89			"<ip address> <hostname> <ttl>\n"
90	
91	       Where <ip address> is in the usual IPv4 (123.456.78.90) or IPv6
92	       (ffee:ddcc:bbaa:9988:7766:5544:3322:1100, ffee::1100, ...) format.
93	       <hostname> is identical to the second argument of the helper
94	       script, and <ttl> is the 'time to live' of this cache entry (in
95	       units of seconds).
96	
97	       Note: If <ip address> is invalid, say the string "0", then a negative
98	       entry is created, which will cause the kernel to treat the hostname
99	       as having no valid DNS translation.
100	
101	
102	
103	
104	A basic sample /sbin/nfs_cache_getent
105	=====================================
106	
107	#!/bin/bash
108	#
109	ttl=600
110	#
111	cut=/usr/bin/cut
112	getent=/usr/bin/getent
113	rpc_pipefs=/var/lib/nfs/rpc_pipefs
114	#
115	die()
116	{
117		echo "Usage: $0 cache_name entry_name"
118		exit 1
119	}
120	
121	[ $# -lt 2 ] && die
122	cachename="$1"
123	cache_path=${rpc_pipefs}/cache/${cachename}/channel
124	
125	case "${cachename}" in
126		dns_resolve)
127			name="$2"
128			result="$(${getent} hosts ${name} | ${cut} -f1 -d\ )"
129			[ -z "${result}" ] && result="0"
130			;;
131		*)
132			die
133			;;
134	esac
135	echo "${result} ${name} ${ttl}" >${cache_path}
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog