Documentation/filesystems/nfs.txt

   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