Trond Myklebust | e571cbf | 2009-08-19 18:12:27 -0400 | [diff] [blame] | 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 |
| 15 | upcall interfaces that are used in order to provide the NFS client with |
| 16 | some of the information that it requires in order to fully comply with |
| 17 | the NFS spec. |
| 18 | |
| 19 | The DNS resolver |
| 20 | ================ |
| 21 | |
| 22 | NFSv4 allows for one server to refer the NFS client to data that has been |
| 23 | migrated onto another server by means of the special "fs_locations" |
| 24 | attribute. See |
| 25 | http://tools.ietf.org/html/rfc3530#section-6 |
| 26 | and |
| 27 | http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00 |
| 28 | |
| 29 | The fs_locations information can take the form of either an ip address and |
| 30 | a path, or a DNS hostname and a path. The latter requires the NFS client to |
| 31 | do a DNS lookup in order to mount the new volume, and hence the need for an |
| 32 | upcall to allow userland to provide this service. |
| 33 | |
| 34 | Assuming that the user has the 'rpc_pipefs' filesystem mounted in the usual |
| 35 | /var/lib/nfs/rpc_pipefs, the upcall consists of the following steps: |
| 36 | |
| 37 | (1) The process checks the dns_resolve cache to see if it contains a |
| 38 | valid entry. If so, it returns that entry and exits. |
| 39 | |
| 40 | (2) If no valid entry exists, the helper script '/sbin/nfs_cache_getent' |
| 41 | (may be changed using the 'nfs.cache_getent' kernel boot parameter) |
| 42 | is run, with two arguments: |
| 43 | - the cache name, "dns_resolve" |
| 44 | - the hostname to resolve |
| 45 | |
| 46 | (3) After looking up the corresponding ip address, the helper script |
| 47 | writes the result into the rpc_pipefs pseudo-file |
| 48 | '/var/lib/nfs/rpc_pipefs/cache/dns_resolve/channel' |
| 49 | in the following (text) format: |
| 50 | |
| 51 | "<ip address> <hostname> <ttl>\n" |
| 52 | |
| 53 | Where <ip address> is in the usual IPv4 (123.456.78.90) or IPv6 |
| 54 | (ffee:ddcc:bbaa:9988:7766:5544:3322:1100, ffee::1100, ...) format. |
| 55 | <hostname> is identical to the second argument of the helper |
| 56 | script, and <ttl> is the 'time to live' of this cache entry (in |
| 57 | units of seconds). |
| 58 | |
| 59 | Note: If <ip address> is invalid, say the string "0", then a negative |
| 60 | entry is created, which will cause the kernel to treat the hostname |
| 61 | as having no valid DNS translation. |
| 62 | |
| 63 | |
| 64 | |
| 65 | |
| 66 | A basic sample /sbin/nfs_cache_getent |
| 67 | ===================================== |
| 68 | |
| 69 | #!/bin/bash |
| 70 | # |
| 71 | ttl=600 |
| 72 | # |
| 73 | cut=/usr/bin/cut |
| 74 | getent=/usr/bin/getent |
| 75 | rpc_pipefs=/var/lib/nfs/rpc_pipefs |
| 76 | # |
| 77 | die() |
| 78 | { |
| 79 | echo "Usage: $0 cache_name entry_name" |
| 80 | exit 1 |
| 81 | } |
| 82 | |
| 83 | [ $# -lt 2 ] && die |
| 84 | cachename="$1" |
| 85 | cache_path=${rpc_pipefs}/cache/${cachename}/channel |
| 86 | |
| 87 | case "${cachename}" in |
| 88 | dns_resolve) |
| 89 | name="$2" |
| 90 | result="$(${getent} hosts ${name} | ${cut} -f1 -d\ )" |
| 91 | [ -z "${result}" ] && result="0" |
| 92 | ;; |
| 93 | *) |
| 94 | die |
| 95 | ;; |
| 96 | esac |
| 97 | echo "${result} ${name} ${ttl}" >${cache_path} |
| 98 | |