]>
Commit | Line | Data |
---|---|---|
e571cbf1 TM |
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 | |
6f2ea7f2 CL |
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 | ||
e571cbf1 TM |
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} | |
136 |