1 2The NFS client 3============== 4 5The NFS version 2 protocol was first documented in RFC1094 (March 1989). 6Since then two more major releases of NFS have been published, with NFSv3 7being documented in RFC1813 (June 1995), and NFSv4 in RFC3530 (April 82003). 9 10The Linux NFS client currently supports all the above published versions, 11and work is in progress on adding support for minor version 1 of the NFSv4 12protocol. 13 14The purpose of this document is to provide information on some of the 15special features of the NFS client that can be configured by system 16administrators. 17 18 19The nfs4_unique_id parameter 20============================ 21 22NFSv4 requires clients to identify themselves to servers with a unique 23string. File open and lock state shared between one client and one server 24is associated with this identity. To support robust NFSv4 state recovery 25and transparent state migration, this identity string must not change 26across client reboots. 27 28Without any other intervention, the Linux client uses a string that contains 29the local system's node name. System administrators, however, often do not 30take care to ensure that node names are fully qualified and do not change 31over the lifetime of a client system. Node names can have other 32administrative requirements that require particular behavior that does not 33work well as part of an nfs_client_id4 string. 34 35The nfs.nfs4_unique_id boot parameter specifies a unique string that can be 36used instead of a system's node name when an NFS client identifies itself to 37a server. Thus, if the system's node name is not unique, or it changes, its 38nfs.nfs4_unique_id stays the same, preventing collision with other clients 39or loss of state during NFS reboot recovery or transparent state migration. 40 41The nfs.nfs4_unique_id string is typically a UUID, though it can contain 42anything that is believed to be unique across all NFS clients. An 43nfs4_unique_id string should be chosen when a client system is installed, 44just as a system's root file system gets a fresh UUID in its label at 45install time. 46 47The string should remain fixed for the lifetime of the client. It can be 48changed safely if care is taken that the client shuts down cleanly and all 49outstanding NFSv4 state has expired, to prevent loss of NFSv4 state. 50 51This string can be stored in an NFS client's grub.conf, or it can be provided 52via a net boot facility such as PXE. It may also be specified as an nfs.ko 53module parameter. Specifying a uniquifier string is not support for NFS 54clients running in containers. 55 56 57The DNS resolver 58================ 59 60NFSv4 allows for one server to refer the NFS client to data that has been 61migrated onto another server by means of the special "fs_locations" 62attribute. See 63 http://tools.ietf.org/html/rfc3530#section-6 64and 65 http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00 66 67The fs_locations information can take the form of either an ip address and 68a path, or a DNS hostname and a path. The latter requires the NFS client to 69do a DNS lookup in order to mount the new volume, and hence the need for an 70upcall to allow userland to provide this service. 71 72Assuming 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 104A basic sample /sbin/nfs_cache_getent 105===================================== 106 107#!/bin/bash 108# 109ttl=600 110# 111cut=/usr/bin/cut 112getent=/usr/bin/getent 113rpc_pipefs=/var/lib/nfs/rpc_pipefs 114# 115die() 116{ 117 echo "Usage: $0 cache_name entry_name" 118 exit 1 119} 120 121[ $# -lt 2 ] && die 122cachename="$1" 123cache_path=${rpc_pipefs}/cache/${cachename}/channel 124 125case "${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 ;; 134esac 135echo "${result} ${name} ${ttl}" >${cache_path} 136 137