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