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