1 .. SPDX-License-Identifier: GPL-2.0
2
3 =======================
4 NFSv4 client identifier
5 =======================
6
7 This document explains how the NFSv4 protocol
8 instances in order to maintain file open and l
9 system restarts. A special identifier and prin
10 on each client. These can be set by administra
11 provided by site administrators, or tools prov
12 distributors.
13
14 There are risks if a client's NFSv4 identifier
15 are not chosen carefully.
16
17
18 Introduction
19 ------------
20
21 The NFSv4 protocol uses "lease-based file lock
22 NFSv4 servers provide file lock guarantees and
23 resources.
24
25 Simply put, an NFSv4 server creates a lease fo
26 The server collects each client's file open an
27 the lease for that client.
28
29 The client is responsible for periodically ren
30 While a lease remains valid, the server holdin
31 guarantees the file locks the client has creat
32
33 If a client stops renewing its lease (for exam
34 the NFSv4 protocol allows the server to remove
35 and lock state after a certain period of time.
36 restarts, it indicates to servers that open an
37 associated with its previous leases is no long
38 destroyed immediately.
39
40 In addition, each NFSv4 server manages a persi
41 leases. When the server restarts and clients a
42 their state, the server uses this list to dist
43 clients that held state before the server rest
44 sending fresh OPEN and LOCK requests. This ena
45 persist safely across server restarts.
46
47 NFSv4 client identifiers
48 ------------------------
49
50 Each NFSv4 client presents an identifier to NF
51 they can associate the client with its lease.
52 identifier consists of two elements:
53
54 - co_ownerid: An arbitrary but fixed string.
55
56 - boot verifier: A 64-bit incarnation verifi
57 server to distinguish successive boot epoc
58
59 The NFSv4.0 specification refers to these two
60 "nfs_client_id4". The NFSv4.1 specification re
61 items as a "client_owner4".
62
63 NFSv4 servers tie this identifier to the princ
64 flavor that the client used when presenting it
65 principal to authorize subsequent lease modifi
66 sent by the client. Effectively this principal
67 the identifier.
68
69 As part of the identity presented to servers,
70 "co_ownerid" string has several important prop
71
72 - The "co_ownerid" string identifies the cli
73 recovery, therefore the string is persiste
74 reboots.
75 - The "co_ownerid" string helps servers dist
76 from others, therefore the string is globa
77 that there is no central authority that as
78 strings.
79 - Because it often appears on the network in
80 "co_ownerid" string does not reveal privat
81 the client itself.
82 - The content of the "co_ownerid" string is
83 before the client attempts NFSv4 mounts af
84 - The NFSv4 protocol places a 1024-byte limi
85 "co_ownerid" string.
86
87 Protecting NFSv4 lease state
88 ----------------------------
89
90 NFSv4 servers utilize the "client_owner4" as d
91 assign a unique lease to each client. Under th
92 circumstances where clients can interfere with
93 referred to as "lease stealing".
94
95 If distinct clients present the same "co_owner
96 the same principal (for example, AUTH_SYS and
97 unable to tell that the clients are not the sa
98 client presents a different boot verifier, so
99 server as if there is one client that is reboo
100 Neither client can maintain open or lock state
101
102 If distinct clients present the same "co_owner
103 distinct principals, the server is likely to a
104 to operate normally but reject subsequent clie
105 "co_ownerid" string.
106
107 If a client's "co_ownerid" string or principal
108 state recovery after a server or client reboot
109 If a client unexpectedly restarts but presents
110 "co_ownerid" string or principal to the server
111 the client's previous open and lock state. Thi
112 locked files until the server removes the orph
113
114 If the server restarts and a client presents a
115 string or principal to the server, the server
116 client to reclaim its open and lock state, and
117 to other clients in the meantime. This is refe
118 stealing".
119
120 Lease stealing and lock stealing increase the
121 of service and in rare cases even data corrupt
122
123 Selecting an appropriate client identifier
124 ------------------------------------------
125
126 By default, the Linux NFSv4 client implementat
127 "co_ownerid" string starting with the words "L
128 the client's UTS node name (the same node name
129 is used as the "machine name" in an AUTH_SYS c
130 deployments, this construction is usually adeq
131 the node name by itself is not adequately uniq
132 unexpectedly. Problematic situations include:
133
134 - NFS-root (diskless) clients, where the loc
135 equivalent) does not provide a unique host
136
137 - "Containers" within a single Linux host.
138 a separate network namespace, but does not
139 to provide a unique host name, then there
140 client instances with the same host name.
141
142 - Clients across multiple administrative dom
143 common NFS server. If hostnames are not as
144 then uniqueness cannot be guaranteed unles
145 included in the hostname.
146
147 Linux provides two mechanisms to add uniquenes
148 string:
149
150 nfs.nfs4_unique_id
151 This module parameter can set an arbitra
152 via the kernel command line, or when the
153 loaded.
154
155 /sys/fs/nfs/net/nfs_client/identifier
156 This virtual file, available since Linux
157 network namespace in which it is accesse
158 distinction between network namespaces (
159 hostname remains uniform.
160
161 Note that this file is empty on name-space cre
162 container system has access to some sort of pe
163 then that uniquifier can be used. For example,
164 be formed at boot using the container's intern
165
166 sha256sum /etc/machine-id | awk '{print $1
167 > /sys/fs/nfs/net/nfs_client/identifie
168
169 Security considerations
170 -----------------------
171
172 The use of cryptographic security for lease ma
173 is strongly encouraged.
174
175 If NFS with Kerberos is not configured, a Linu
176 AUTH_SYS and UID 0 as the principal part of it
177 This configuration is not only insecure, it in
178 lease and lock stealing. However, it might be
179 client configurations that have no local persi
180 "co_ownerid" string uniqueness and persistence
181 case.
182
183 When a Kerberos keytab is present on a Linux N
184 attempts to use one of the principals in that
185 identifying itself to servers. The "sec=" moun
186 control this behavior. Alternately, a single-u
187 Kerberos principal can use that principal in p
188 host principal.
189
190 Using Kerberos for this purpose enables the cl
191 use the same lease for operations covered by a
192 Additionally, the Linux NFS client uses the RP
193 flavor with Kerberos and the integrity QOS to
194 modification of lease modification requests.
195
196 Additional notes
197 ----------------
198 The Linux NFSv4 client establishes a single le
199 server it accesses. NFSv4 mounts from a Linux
200 particular server then share that lease.
201
202 Once a client establishes open and lock state,
203 enables lease state to transition to other ser
204 that has been migrated. This hides data migrat
205 running applications. The Linux NFSv4 client f
206 migration by presenting the same "client_owner
207 encounters.
208
209 ========
210 See Also
211 ========
212
213 - nfs(5)
214 - kerberos(7)
215 - RFC 7530 for the NFSv4.0 specification
216 - RFC 8881 for the NFSv4.1 specification.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.