12f123b9aSDaniel W. S. Almeida========== 22f123b9aSDaniel W. S. AlmeidaNFS Client 32f123b9aSDaniel W. S. Almeida========== 42f123b9aSDaniel W. S. Almeida 52f123b9aSDaniel W. S. AlmeidaThe NFS client 62f123b9aSDaniel W. S. Almeida============== 72f123b9aSDaniel W. S. Almeida 82f123b9aSDaniel W. S. AlmeidaThe NFS version 2 protocol was first documented in RFC1094 (March 1989). 92f123b9aSDaniel W. S. AlmeidaSince then two more major releases of NFS have been published, with NFSv3 102f123b9aSDaniel W. S. Almeidabeing documented in RFC1813 (June 1995), and NFSv4 in RFC3530 (April 112f123b9aSDaniel W. S. Almeida2003). 122f123b9aSDaniel W. S. Almeida 132f123b9aSDaniel W. S. AlmeidaThe Linux NFS client currently supports all the above published versions, 142f123b9aSDaniel W. S. Almeidaand work is in progress on adding support for minor version 1 of the NFSv4 152f123b9aSDaniel W. S. Almeidaprotocol. 162f123b9aSDaniel W. S. Almeida 172f123b9aSDaniel W. S. AlmeidaThe purpose of this document is to provide information on some of the 182f123b9aSDaniel W. S. Almeidaspecial features of the NFS client that can be configured by system 192f123b9aSDaniel W. S. Almeidaadministrators. 202f123b9aSDaniel W. S. Almeida 212f123b9aSDaniel W. S. Almeida 222f123b9aSDaniel W. S. AlmeidaThe nfs4_unique_id parameter 232f123b9aSDaniel W. S. Almeida============================ 242f123b9aSDaniel W. S. Almeida 252f123b9aSDaniel W. S. AlmeidaNFSv4 requires clients to identify themselves to servers with a unique 262f123b9aSDaniel W. S. Almeidastring. File open and lock state shared between one client and one server 272f123b9aSDaniel W. S. Almeidais associated with this identity. To support robust NFSv4 state recovery 282f123b9aSDaniel W. S. Almeidaand transparent state migration, this identity string must not change 292f123b9aSDaniel W. S. Almeidaacross client reboots. 302f123b9aSDaniel W. S. Almeida 312f123b9aSDaniel W. S. AlmeidaWithout any other intervention, the Linux client uses a string that contains 322f123b9aSDaniel W. S. Almeidathe local system's node name. System administrators, however, often do not 332f123b9aSDaniel W. S. Almeidatake care to ensure that node names are fully qualified and do not change 342f123b9aSDaniel W. S. Almeidaover the lifetime of a client system. Node names can have other 352f123b9aSDaniel W. S. Almeidaadministrative requirements that require particular behavior that does not 362f123b9aSDaniel W. S. Almeidawork well as part of an nfs_client_id4 string. 372f123b9aSDaniel W. S. Almeida 382f123b9aSDaniel W. S. AlmeidaThe nfs.nfs4_unique_id boot parameter specifies a unique string that can be 39*5e12f172SNeilBrownused together with a system's node name when an NFS client identifies itself to 40*5e12f172SNeilBrowna server. Thus, if the system's node name is not unique, its 41*5e12f172SNeilBrownnfs.nfs4_unique_id can help prevent collisions with other clients. 422f123b9aSDaniel W. S. Almeida 432f123b9aSDaniel W. S. AlmeidaThe nfs.nfs4_unique_id string is typically a UUID, though it can contain 442f123b9aSDaniel W. S. Almeidaanything that is believed to be unique across all NFS clients. An 452f123b9aSDaniel W. S. Almeidanfs4_unique_id string should be chosen when a client system is installed, 462f123b9aSDaniel W. S. Almeidajust as a system's root file system gets a fresh UUID in its label at 472f123b9aSDaniel W. S. Almeidainstall time. 482f123b9aSDaniel W. S. Almeida 492f123b9aSDaniel W. S. AlmeidaThe string should remain fixed for the lifetime of the client. It can be 502f123b9aSDaniel W. S. Almeidachanged safely if care is taken that the client shuts down cleanly and all 512f123b9aSDaniel W. S. Almeidaoutstanding NFSv4 state has expired, to prevent loss of NFSv4 state. 522f123b9aSDaniel W. S. Almeida 532f123b9aSDaniel W. S. AlmeidaThis string can be stored in an NFS client's grub.conf, or it can be provided 542f123b9aSDaniel W. S. Almeidavia a net boot facility such as PXE. It may also be specified as an nfs.ko 55*5e12f172SNeilBrownmodule parameter. 56*5e12f172SNeilBrown 57*5e12f172SNeilBrownThis uniquifier string will be the same for all NFS clients running in 58*5e12f172SNeilBrowncontainers unless it is overridden by a value written to 59*5e12f172SNeilBrown/sys/fs/nfs/net/nfs_client/identifier which will be local to the network 60*5e12f172SNeilBrownnamespace of the process which writes. 612f123b9aSDaniel W. S. Almeida 622f123b9aSDaniel W. S. Almeida 632f123b9aSDaniel W. S. AlmeidaThe DNS resolver 642f123b9aSDaniel W. S. Almeida================ 652f123b9aSDaniel W. S. Almeida 662f123b9aSDaniel W. S. AlmeidaNFSv4 allows for one server to refer the NFS client to data that has been 672f123b9aSDaniel W. S. Almeidamigrated onto another server by means of the special "fs_locations" 682f123b9aSDaniel W. S. Almeidaattribute. See `RFC3530 Section 6: Filesystem Migration and Replication`_ and 692f123b9aSDaniel W. S. Almeida`Implementation Guide for Referrals in NFSv4`_. 702f123b9aSDaniel W. S. Almeida 716b2484e1SAlexander A. Klimov.. _RFC3530 Section 6\: Filesystem Migration and Replication: https://tools.ietf.org/html/rfc3530#section-6 726b2484e1SAlexander A. Klimov.. _Implementation Guide for Referrals in NFSv4: https://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00 732f123b9aSDaniel W. S. Almeida 742f123b9aSDaniel W. S. AlmeidaThe fs_locations information can take the form of either an ip address and 752f123b9aSDaniel W. S. Almeidaa path, or a DNS hostname and a path. The latter requires the NFS client to 762f123b9aSDaniel W. S. Almeidado a DNS lookup in order to mount the new volume, and hence the need for an 772f123b9aSDaniel W. S. Almeidaupcall to allow userland to provide this service. 782f123b9aSDaniel W. S. Almeida 792f123b9aSDaniel W. S. AlmeidaAssuming that the user has the 'rpc_pipefs' filesystem mounted in the usual 802f123b9aSDaniel W. S. Almeida/var/lib/nfs/rpc_pipefs, the upcall consists of the following steps: 812f123b9aSDaniel W. S. Almeida 822f123b9aSDaniel W. S. Almeida (1) The process checks the dns_resolve cache to see if it contains a 832f123b9aSDaniel W. S. Almeida valid entry. If so, it returns that entry and exits. 842f123b9aSDaniel W. S. Almeida 852f123b9aSDaniel W. S. Almeida (2) If no valid entry exists, the helper script '/sbin/nfs_cache_getent' 862f123b9aSDaniel W. S. Almeida (may be changed using the 'nfs.cache_getent' kernel boot parameter) 872f123b9aSDaniel W. S. Almeida is run, with two arguments: 882f123b9aSDaniel W. S. Almeida - the cache name, "dns_resolve" 892f123b9aSDaniel W. S. Almeida - the hostname to resolve 902f123b9aSDaniel W. S. Almeida 912f123b9aSDaniel W. S. Almeida (3) After looking up the corresponding ip address, the helper script 922f123b9aSDaniel W. S. Almeida writes the result into the rpc_pipefs pseudo-file 932f123b9aSDaniel W. S. Almeida '/var/lib/nfs/rpc_pipefs/cache/dns_resolve/channel' 942f123b9aSDaniel W. S. Almeida in the following (text) format: 952f123b9aSDaniel W. S. Almeida 962f123b9aSDaniel W. S. Almeida "<ip address> <hostname> <ttl>\n" 972f123b9aSDaniel W. S. Almeida 982f123b9aSDaniel W. S. Almeida Where <ip address> is in the usual IPv4 (123.456.78.90) or IPv6 992f123b9aSDaniel W. S. Almeida (ffee:ddcc:bbaa:9988:7766:5544:3322:1100, ffee::1100, ...) format. 1002f123b9aSDaniel W. S. Almeida <hostname> is identical to the second argument of the helper 1012f123b9aSDaniel W. S. Almeida script, and <ttl> is the 'time to live' of this cache entry (in 1022f123b9aSDaniel W. S. Almeida units of seconds). 1032f123b9aSDaniel W. S. Almeida 1042f123b9aSDaniel W. S. Almeida .. note:: 1052f123b9aSDaniel W. S. Almeida If <ip address> is invalid, say the string "0", then a negative 1062f123b9aSDaniel W. S. Almeida entry is created, which will cause the kernel to treat the hostname 1072f123b9aSDaniel W. S. Almeida as having no valid DNS translation. 1082f123b9aSDaniel W. S. Almeida 1092f123b9aSDaniel W. S. Almeida 1102f123b9aSDaniel W. S. Almeida 1112f123b9aSDaniel W. S. Almeida 1122f123b9aSDaniel W. S. AlmeidaA basic sample /sbin/nfs_cache_getent 1132f123b9aSDaniel W. S. Almeida===================================== 1142f123b9aSDaniel W. S. Almeida.. code-block:: sh 1152f123b9aSDaniel W. S. Almeida 1162f123b9aSDaniel W. S. Almeida #!/bin/bash 1172f123b9aSDaniel W. S. Almeida # 1182f123b9aSDaniel W. S. Almeida ttl=600 1192f123b9aSDaniel W. S. Almeida # 1202f123b9aSDaniel W. S. Almeida cut=/usr/bin/cut 1212f123b9aSDaniel W. S. Almeida getent=/usr/bin/getent 1222f123b9aSDaniel W. S. Almeida rpc_pipefs=/var/lib/nfs/rpc_pipefs 1232f123b9aSDaniel W. S. Almeida # 1242f123b9aSDaniel W. S. Almeida die() 1252f123b9aSDaniel W. S. Almeida { 1262f123b9aSDaniel W. S. Almeida echo "Usage: $0 cache_name entry_name" 1272f123b9aSDaniel W. S. Almeida exit 1 1282f123b9aSDaniel W. S. Almeida } 1292f123b9aSDaniel W. S. Almeida 1302f123b9aSDaniel W. S. Almeida [ $# -lt 2 ] && die 1312f123b9aSDaniel W. S. Almeida cachename="$1" 1322f123b9aSDaniel W. S. Almeida cache_path=${rpc_pipefs}/cache/${cachename}/channel 1332f123b9aSDaniel W. S. Almeida 1342f123b9aSDaniel W. S. Almeida case "${cachename}" in 1352f123b9aSDaniel W. S. Almeida dns_resolve) 1362f123b9aSDaniel W. S. Almeida name="$2" 1372f123b9aSDaniel W. S. Almeida result="$(${getent} hosts ${name} | ${cut} -f1 -d\ )" 1382f123b9aSDaniel W. S. Almeida [ -z "${result}" ] && result="0" 1392f123b9aSDaniel W. S. Almeida ;; 1402f123b9aSDaniel W. S. Almeida *) 1412f123b9aSDaniel W. S. Almeida die 1422f123b9aSDaniel W. S. Almeida ;; 1432f123b9aSDaniel W. S. Almeida esac 1442f123b9aSDaniel W. S. Almeida echo "${result} ${name} ${ttl}" >${cache_path} 145