Debian Codegraph @

upstream/debian-unstable/man8/sm-notify.8

raw
1 .\"@(#)sm-notify.8"
2 .\"
3 .\" Copyright (C) 2004 Olaf Kirch <[email protected]>
4 .\"
5 .\" Rewritten by Chuck Lever <[email protected]>, 2009.
6 .\" Copyright 2009 Oracle. All rights reserved.
7 .\"
8 .TH SM-NOTIFY 8 "1 November 2009
9 .SH NAME
10 sm-notify \- send reboot notifications to NFS peers
11 .SH SYNOPSIS
12 .BI "/usr/sbin/sm-notify [-dfn] [-m " minutes "] [-v " name "] [-p " notify-port "] [-P " path "]
13 .SH DESCRIPTION
14 File locks are not part of persistent file system state.
15 Lock state is thus lost when a host reboots.
16 .PP
17 Network file systems must also detect when lock state is lost
18 because a remote host has rebooted.
19 After an NFS client reboots, an NFS server must release all file locks
20 held by applications that were running on that client.
21 After a server reboots, a client must remind the
22 server of file locks held by applications running on that client.
23 .PP
24 For NFS version 2 and version 3, the
25 .I Network Status Monitor
26 protocol (or NSM for short)
27 is used to notify NFS peers of reboots.
28 On Linux, two separate user-space components constitute the NSM service:
29 .TP
30 .B sm-notify
31 A helper program that notifies NFS peers after the local system reboots
32 .TP
33 .B rpc.statd
34 A daemon that listens for reboot notifications from other hosts, and
35 manages the list of hosts to be notified when the local system reboots
36 .PP
37 The local NFS lock manager alerts its local
38 .B rpc.statd
39 of each remote peer that should be monitored.
40 When the local system reboots, the
41 .B sm-notify
42 command notifies the NSM service on monitored peers of the reboot.
43 When a remote reboots, that peer notifies the local
44 .BR rpc.statd ,
45 which in turn passes the reboot notification
46 back to the local NFS lock manager.
47 .SH NSM OPERATION IN DETAIL
48 The first file locking interaction between an NFS client and server causes
49 the NFS lock managers on both peers to contact their local NSM service to
50 store information about the opposite peer.
51 On Linux, the local lock manager contacts
52 .BR rpc.statd .
53 .PP
54 .B rpc.statd
55 records information about each monitored NFS peer on persistent storage.
56 This information describes how to contact a remote peer
57 in case the local system reboots,
58 how to recognize which monitored peer is reporting a reboot,
59 and how to notify the local lock manager when a monitored peer
60 indicates it has rebooted.
61 .PP
62 An NFS client sends a hostname, known as the client's
63 .IR caller_name ,
64 in each file lock request.
65 An NFS server can use this hostname to send asynchronous GRANT
66 calls to a client, or to notify the client it has rebooted.
67 .PP
68 The Linux NFS server can provide the client's
69 .I caller_name
70 or the client's network address to
71 .BR rpc.statd .
72 For the purposes of the NSM protocol,
73 this name or address is known as the monitored peer's
74 .IR mon_name .
75 In addition, the local lock manager tells
76 .B rpc.statd
77 what it thinks its own hostname is.
78 For the purposes of the NSM protocol,
79 this hostname is known as
80 .IR my_name .
81 .PP
82 There is no equivalent interaction between an NFS server and a client
83 to inform the client of the server's
84 .IR caller_name .
85 Therefore NFS clients do not actually know what
86 .I mon_name
87 an NFS server might use in an SM_NOTIFY request.
88 The Linux NFS client records the server's hostname used on the mount command
89 to identify rebooting NFS servers.
90 .SS Reboot notification
91 When the local system reboots, the
92 .B sm-notify
93 command reads the list of monitored peers from persistent storage and
94 sends an SM_NOTIFY request to the NSM service on each listed remote peer.
95 It uses the
96 .I mon_name
97 string as the destination.
98 To identify which host has rebooted, the
99 .B sm-notify
100 command normally sends
101 .I my_name
102 string recorded when that remote was monitored.
103 The remote
104 .B rpc.statd
105 matches incoming SM_NOTIFY requests using this string,
106 or the caller's network address,
107 to one or more peers on its own monitor list.
108 .PP
109 If
110 .B rpc.statd
111 does not find a peer on its monitor list that matches
112 an incoming SM_NOTIFY request,
113 the notification is not forwarded to the local lock manager.
114 In addition, each peer has its own
115 .IR "NSM state number" ,
116 a 32-bit integer that is bumped after each reboot by the
117 .B sm-notify
118 command.
119 .B rpc.statd
120 uses this number to distinguish between actual reboots
121 and replayed notifications.
122 .PP
123 Part of NFS lock recovery is rediscovering
124 which peers need to be monitored again.
125 The
126 .B sm-notify
127 command clears the monitor list on persistent storage after each reboot.
128 .SH OPTIONS
129 .TP
130 .B -d
131 Keeps
132 .B sm-notify
133 attached to its controlling terminal and running in the foreground
134 so that notification progress may be monitored directly.
135 .TP
136 .B -f
137 Send notifications even if
138 .B sm-notify
139 has already run since the last system reboot.
140 .TP
141 .BI -m " retry-time
142 Specifies the length of time, in minutes, to continue retrying
143 notifications to unresponsive hosts.
144 If this option is not specified,
145 .B sm-notify
146 attempts to send notifications for 15 minutes.
147 Specifying a value of 0 causes
148 .B sm-notify
149 to continue sending notifications to unresponsive peers
150 until it is manually killed.
151 .IP
152 Notifications are retried if sending fails,
153 the remote does not respond,
154 the remote's NSM service is not registered,
155 or if there is a DNS failure
156 which prevents the remote's
157 .I mon_name
158 from being resolved to an address.
159 .IP
160 Hosts are not removed from the notification list until a valid
161 reply has been received.
162 However, the SM_NOTIFY procedure has a void result.
163 There is no way for
164 .B sm-notify
165 to tell if the remote recognized the sender and has started
166 appropriate lock recovery.
167 .TP
168 .B -n
169 Prevents
170 .B sm-notify
171 from updating the local system's NSM state number.
172 .TP
173 .BI -p " port
174 Specifies the source port number
175 .B sm-notify
176 should use when sending reboot notifications.
177 If this option is not specified, a randomly chosen ephemeral port is used.
178 .IP
179 This option can be used to traverse a firewall between client and server.
180 .TP
181 .BI "\-P, " "" \-\-state\-directory\-path " pathname
182 Specifies the pathname of the parent directory
183 where NSM state information resides.
184 If this option is not specified,
185 .B sm-notify
186 uses
187 .I /var/lib/nfs
188 by default.
189 .IP
190 After starting,
191 .B sm-notify
192 attempts to set its effective UID and GID to the owner
193 and group of the subdirectory
194 .B sm
195 of this directory. After changing the effective ids,
196 .B sm-notify
197 only needs to access files in
198 .B sm
199 and
200 .B sm.bak
201 within the state-directory-path.
202 .TP
203 .BI -v " ipaddr " | " hostname
204 Specifies the network address from which to send reboot notifications,
205 and the
206 .I mon_name
207 argument to use when sending SM_NOTIFY requests.
208 If this option is not specified,
209 .B sm-notify
210 uses a wildcard address as the transport bind address,
211 and uses the
212 .I my_name
213 recorded when the remote was monitored as the
214 .I mon_name
215 argument when sending SM_NOTIFY requests.
216 .IP
217 The
218 .I ipaddr
219 form can be expressed as either an IPv4 or an IPv6 presentation address.
220 If the
221 .I ipaddr
222 form is used, the
223 .B sm-notify
224 command converts this address to a hostname for use as the
225 .I mon_name
226 argument when sending SM_NOTIFY requests.
227 .IP
228 This option can be useful in multi-homed configurations where
229 the remote requires notification from a specific network address.
230 .SH CONFIGURATION FILE
231 Many of the options that can be set on the command line can also be
232 controlled through values set in the
233 .B [sm-notify]
234 or, in one case, the
235 .B [statd]
236 section of the
237 .I /etc/nfs.conf
238 configuration file.
239
240 Values recognized in the
241 .B [sm-notify]
242 section include:
243 .BR retry-time ,
244 .BR outgoing-port ", and"
245 .BR outgoing-addr .
246 These have the same effect as the command line options
247 .BR m ,
248 .BR p ", and"
249 .B v
250 respectively.
251
252 An additional value recognized in the
253 .B [sm-notify]
254 section is
255 .BR lift-grace .
256 By default,
257 .B sm-notify
258 will lift lockd's grace period early if it has no hosts to notify.
259 Some high availability configurations will run one
260 .B sm-notify
261 per floating IP address. In these configurations, lifting the
262 grace period early may prevent clients from reclaiming locks.
263 .RB "Setting " lift-grace " to " n
264 will prevent
265 .B sm-notify
266 from ending the grace period early.
267 .B lift-grace
268 has no corresponding command line option.
269
270 The value recognized in the
271 .B [statd]
272 section is
273 .BR state-directory-path .
274
275 .SH SECURITY
276 The
277 .B sm-notify
278 command is, generally, started as root to acquire privileges needed
279 to access the state information database.
280 It drops root privileges
281 as soon as it starts up to reduce the risk of a privilege escalation attack.
282 .PP
283 During normal operation,
284 the effective user ID it chooses is the owner of the state directory.
285 This allows it to continue to access files in that directory after it
286 has dropped its root privileges.
287 To control which user ID
288 .B rpc.statd
289 chooses, simply use
290 .BR chown (1)
291 to set the owner of
292 the state directory.
293 .PP
294 The
295 .B sm-notify
296 command can also be started by the user ID that owns the state directory.
297 That is useful for the situation when it is called from an rpc-stat
298 ha-callout program that is already running as the
299 non-privileged user. The non-root user will not have the capabilities
300 to drop the root privileges as described above.
301 .SH ADDITIONAL NOTES
302 Lock recovery after a reboot is critical to maintaining data integrity
303 and preventing unnecessary application hangs.
304 .PP
305 To help
306 .B rpc.statd
307 match SM_NOTIFY requests to NLM requests, a number of best practices
308 should be observed, including:
309 .IP
310 The UTS nodename of your systems should match the DNS names that NFS
311 peers use to contact them
312 .IP
313 The UTS nodenames of your systems should always be fully qualified domain names
314 .IP
315 The forward and reverse DNS mapping of the UTS nodenames should be
316 consistent
317 .IP
318 The hostname the client uses to mount the server should match the server's
319 .I mon_name
320 in SM_NOTIFY requests it sends
321 .PP
322 Unmounting an NFS file system does not necessarily stop
323 either the NFS client or server from monitoring each other.
324 Both may continue monitoring each other for a time in case subsequent
325 NFS traffic between the two results in fresh mounts and additional
326 file locking.
327 .PP
328 On Linux, if the
329 .B lockd
330 kernel module is unloaded during normal operation,
331 all remote NFS peers are unmonitored.
332 This can happen on an NFS client, for example,
333 if an automounter removes all NFS mount
334 points due to inactivity.
335 .SS IPv6 and TI-RPC support
336 TI-RPC is a pre-requisite for supporting NFS on IPv6.
337 If TI-RPC support is built into the
338 .B sm-notify
339 command ,it will choose an appropriate IPv4 or IPv6 transport
340 based on the network address returned by DNS for each remote peer.
341 It should be fully compatible with remote systems
342 that do not support TI-RPC or IPv6.
343 .PP
344 Currently, the
345 .B sm-notify
346 command supports sending notification only via datagram transport protocols.
347 .SH FILES
348 .TP 2.5i
349 .I /var/lib/nfs/sm
350 directory containing monitor list
351 .TP 2.5i
352 .I /var/lib/nfs/sm.bak
353 directory containing notify list
354 .TP 2.5i
355 .I /var/lib/nfs/state
356 NSM state number for this host
357 .TP 2.5i
358 .I /proc/sys/fs/nfs/nsm_local_state
359 kernel's copy of the NSM state number
360 .SH SEE ALSO
361 .BR rpc.statd (8),
362 .BR nfs (5),
363 .BR uname (2),
364 .BR hostname (7)
365 .PP
366 RFC 1094 - "NFS: Network File System Protocol Specification"
367 .br
368 RFC 1813 - "NFS Version 3 Protocol Specification"
369 .br
370 OpenGroup Protocols for Interworking: XNFS, Version 3W - Chapter 11
371 .SH AUTHORS
372 Olaf Kirch <[email protected]>
373 .br
374 Chuck Lever <[email protected]>