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