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