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
15upcall interfaces that are used in order to provide the NFS client with
16some of the information that it requires in order to fully comply with
17the NFS spec.
18
19The DNS resolver
20================
21
22NFSv4 allows for one server to refer the NFS client to data that has been
23migrated onto another server by means of the special "fs_locations"
24attribute. See
25	http://tools.ietf.org/html/rfc3530#section-6
26and
27	http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00
28
29The fs_locations information can take the form of either an ip address and
30a path, or a DNS hostname and a path. The latter requires the NFS client to
31do a DNS lookup in order to mount the new volume, and hence the need for an
32upcall to allow userland to provide this service.
33
34Assuming 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
66A basic sample /sbin/nfs_cache_getent
67=====================================
68
69#!/bin/bash
70#
71ttl=600
72#
73cut=/usr/bin/cut
74getent=/usr/bin/getent
75rpc_pipefs=/var/lib/nfs/rpc_pipefs
76#
77die()
78{
79	echo "Usage: $0 cache_name entry_name"
80	exit 1
81}
82
83[ $# -lt 2 ] && die
84cachename="$1"
85cache_path=${rpc_pipefs}/cache/${cachename}/channel
86
87case "${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		;;
96esac
97echo "${result} ${name} ${ttl}" >${cache_path}
98
99