Debian Codegraph @

upstream/mageia-cauldron/man8/statd.8

raw
1 .\"@(#)rpc.statd.8"
2 .\"
3 .\" Copyright (C) 1999 Olaf Kirch <[email protected]>
4 .\" Modified by Jeffrey A. Uphoff, 1999, 2002, 2005.
5 .\" Modified by Lon Hohberger, 2000.
6 .\" Modified by Paul Clements, 2004.
7 .\"
8 .\" Rewritten by Chuck Lever <[email protected]>, 2009.
9 .\" Copyright 2009 Oracle. All rights reserved.
10 .\"
11 .TH RPC.STATD 8 "1 November 2009"
12 .SH NAME
13 rpc.statd \- NSM service daemon
14 .SH SYNOPSIS
15 .BI "rpc.statd [-dh?FLNvV] [-H " prog "] [-n " my-name "] [-o " outgoing-port ]
16 .ti +10
17 .BI "[-p " listener-port "] [-P " path ]
18 .ti +10
19 .BI "[--nlm-port " port "] [--nlm-udp-port " port ]
20 .SH DESCRIPTION
21 File locks are not part of persistent file system state.
22 Lock state is thus lost when a host reboots.
23 .PP
24 Network file systems must also detect when lock state is lost
25 because a remote host has rebooted.
26 After an NFS client reboots, an NFS server must release all file locks
27 held by applications that were running on that client.
28 After a server reboots, a client must remind the
29 server of file locks held by applications running on that client.
30 .PP
31 For NFS version 2 [RFC1094] and NFS version 3 [RFC1813], the
32 .I Network Status Monitor
33 protocol (or NSM for short)
34 is used to notify NFS peers of reboots.
35 On Linux, two separate user-space components constitute the NSM service:
36 .TP
37 .B rpc.statd
38 A daemon that listens for reboot notifications from other hosts, and
39 manages the list of hosts to be notified when the local system reboots
40 .TP
41 .B sm-notify
42 A helper program that notifies NFS peers after the local system reboots
43 .PP
44 The local NFS lock manager alerts its local
45 .B rpc.statd
46 of each remote peer that should be monitored.
47 When the local system reboots, the
48 .B sm-notify
49 command notifies the NSM service on monitored peers of the reboot.
50 When a remote reboots, that peer notifies the local
51 .BR rpc.statd ,
52 which in turn passes the reboot notification
53 back to the local NFS lock manager.
54 .SH NSM OPERATION IN DETAIL
55 The first file locking interaction between an NFS client and server causes
56 the NFS lock managers on both peers to contact their local NSM service to
57 store information about the opposite peer.
58 On Linux, the local lock manager contacts
59 .BR rpc.statd .
60 .PP
61 .B rpc.statd
62 records information about each monitored NFS peer on persistent storage.
63 This information describes how to contact a remote peer
64 in case the local system reboots,
65 how to recognize which monitored peer is reporting a reboot,
66 and how to notify the local lock manager when a monitored peer
67 indicates it has rebooted.
68 .PP
69 An NFS client sends a hostname, known as the client's
70 .IR caller_name ,
71 in each file lock request.
72 An NFS server can use this hostname to send asynchronous GRANT
73 calls to a client, or to notify the client it has rebooted.
74 .PP
75 The Linux NFS server can provide the client's
76 .I caller_name
77 or the client's network address to
78 .BR rpc.statd .
79 For the purposes of the NSM protocol,
80 this name or address is known as the monitored peer's
81 .IR mon_name .
82 In addition, the local lock manager tells
83 .B rpc.statd
84 what it thinks its own hostname is.
85 For the purposes of the NSM protocol,
86 this hostname is known as
87 .IR my_name .
88 .PP
89 There is no equivalent interaction between an NFS server and a client
90 to inform the client of the server's
91 .IR caller_name .
92 Therefore NFS clients do not actually know what
93 .I mon_name
94 an NFS server might use in an SM_NOTIFY request.
95 The Linux NFS client uses the server hostname from the mount command
96 to identify rebooting NFS servers.
97 .SS Reboot notification
98 When the local system reboots, the
99 .B sm-notify
100 command reads the list of monitored peers from persistent storage and
101 sends an SM_NOTIFY request to the NSM service on each listed remote peer.
102 It uses the
103 .I mon_name
104 string as the destination.
105 To identify which host has rebooted, the
106 .B sm-notify
107 command sends the
108 .I my_name
109 string recorded when that remote was monitored.
110 The remote
111 .B rpc.statd
112 matches incoming SM_NOTIFY requests using this string,
113 or the caller's network address,
114 to one or more peers on its own monitor list.
115 .PP
116 If
117 .B rpc.statd
118 does not find a peer on its monitor list that matches
119 an incoming SM_NOTIFY request,
120 the notification is not forwarded to the local lock manager.
121 In addition, each peer has its own
122 .IR "NSM state number" ,
123 a 32-bit integer that is bumped after each reboot by the
124 .B sm-notify
125 command.
126 .B rpc.statd
127 uses this number to distinguish between actual reboots
128 and replayed notifications.
129 .PP
130 Part of NFS lock recovery is rediscovering
131 which peers need to be monitored again.
132 The
133 .B sm-notify
134 command clears the monitor list on persistent storage after each reboot.
135 .SH OPTIONS
136 .TP
137 .BR -d , " --no-syslog
138 Causes
139 .B rpc.statd
140 to write log messages on
141 .I stderr
142 instead of to the system log,
143 if the
144 .B -F
145 option was also specified.
146 .TP
147 .BR -F , " --foreground
148 Keeps
149 .B rpc.statd
150 attached to its controlling terminal so that NSM
151 operation can be monitored directly or run under a debugger.
152 If this option is not specified,
153 .B rpc.statd
154 backgrounds itself soon after it starts.
155 .TP
156 .BR -h , " -?" , " --help
157 Causes
158 .B rpc.statd
159 to display usage information on
160 .I stderr
161 and then exit.
162 .TP
163 .BI "\-H," "" " \-\-ha-callout " prog
164 Specifies a high availability callout program.
165 If this option is not specified, no callouts are performed.
166 See the
167 .B High-availability callouts
168 section below for details.
169 .TP
170 .BR -L , " --no-notify
171 Prevents
172 .B rpc.statd
173 from running the
174 .B sm-notify
175 command when it starts up,
176 preserving the existing NSM state number and monitor list.
177 .IP
178 Note: the
179 .B sm-notify
180 command contains a check to ensure it runs only once after each system reboot.
181 This prevents spurious reboot notification if
182 .B rpc.statd
183 restarts without the
184 .B -L
185 option.
186 .TP
187 .BI "\-n, " "" "\-\-name " ipaddr " | " hostname
188 This string is only used by the
189 .B sm-notify
190 command as the source address from which to send reboot notification requests.
191 .IP
192 The
193 .I ipaddr
194 form can be expressed as either an IPv4 or an IPv6 presentation address.
195 If this option is not specified,
196 .B rpc.statd
197 uses a wildcard address as the transport bind address.
198 See
199 .BR sm-notify (8)
200 for details.
201 .TP
202 .BR -N
203 Causes
204 .B rpc.statd
205 to run the
206 .B sm-notify
207 command, and then exit.
208 Since the
209 .B sm-notify
210 command can also be run directly, this option is deprecated.
211 .TP
212 .BI "\-o," "" " \-\-outgoing\-port " port
213 Specifies the source port number the
214 .B sm-notify
215 command should use when sending reboot notifications.
216 See
217 .BR sm-notify (8)
218 for details.
219 .TP
220 .BI "\-p," "" " \-\-port " port
221 Specifies the port number used for RPC listener sockets.
222 If this option is not specified,
223 .B rpc.statd
224 will try to consult
225 .IR /etc/services ,
226 if gets port succeed, set the same port for all listener socket,
227 otherwise chooses a random ephemeral port for each listener socket.
228 .IP
229 This option can be used to fix the port value of its listeners when
230 SM_NOTIFY requests must traverse a firewall between clients and
231 servers.
232 .TP
233 .BI "\-T," "" " \-\-nlm\-port " port
234 Specifies the port number that
235 .I lockd
236 should listen on for
237 .B NLM
238 requests. This sets both the TCP and UDP ports unless the UDP port is
239 set separately.
240 .TP
241 .BI "\-U," "" " \-\-nlm\-udp\-port " port
242 Specifies the UDP port number that
243 .I lockd
244 should listen on for
245 .B NLM
246 requests.
247 .TP
248 .BI "\-P, " "" \-\-state\-directory\-path " pathname"
249 Specifies the pathname of the parent directory
250 where NSM state information resides.
251 If this option is not specified,
252 .B rpc.statd
253 uses
254 .I /var/lib/nfs/statd
255 by default.
256 .IP
257 After starting,
258 .B rpc.statd
259 attempts to set its effective UID and GID to the owner
260 and group of the subdirectory
261 .B sm
262 of this directory. After changing the effective ids,
263 .B rpc.statd
264 only needs to access files in
265 .B sm
266 and
267 .B sm.bak
268 within the state-directory-path.
269 .TP
270 .BR -v ", " -V ", " --version
271 Causes
272 .B rpc.statd
273 to display version information on
274 .I stderr
275 and then exit.
276 .SH CONFIGURATION FILE
277 Many of the options that can be set on the command line can also be
278 controlled through values set in the
279 .B [statd]
280 or, in some cases, the
281 .B [lockd]
282 sections of the
283 .I /etc/nfs.conf
284 configuration file.
285 Values recognized in the
286 .B [statd]
287 section include
288 .BR port ,
289 .BR outgoing-port ,
290 .BR name ,
291 .BR state-directory-path ", and"
292 .B ha-callout
293 which each have the same effect as the option with the same name.
294
295 The values recognized in the
296 .B [lockd]
297 section include
298 .B port
299 and
300 .B udp-port
301 which have the same effect as the
302 .B --nlm-port
303 and
304 .B --nlm-udp-port
305 options, respectively.
306
307 .SH SECURITY
308 The
309 .B rpc.statd
310 daemon must be started as root to acquire privileges needed
311 to create sockets with privileged source ports, and to access the
312 state information database.
313 Because
314 .B rpc.statd
315 maintains a long-running network service, however, it drops root privileges
316 as soon as it starts up to reduce the risk of a privilege escalation attack.
317 .PP
318 During normal operation,
319 the effective user ID it chooses is the owner of the state directory.
320 This allows it to continue to access files in that directory after it
321 has dropped its root privileges.
322 To control which user ID
323 .B rpc.statd
324 chooses, simply use
325 .BR chown (1)
326 to set the owner of
327 the state directory.
328 .SH ADDITIONAL NOTES
329 Lock recovery after a reboot is critical to maintaining data integrity
330 and preventing unnecessary application hangs.
331 To help
332 .B rpc.statd
333 match SM_NOTIFY requests to NLM requests, a number of best practices
334 should be observed, including:
335 .IP
336 The UTS nodename of your systems should match the DNS names that NFS
337 peers use to contact them
338 .IP
339 The UTS nodenames of your systems should always be fully qualified domain names
340 .IP
341 The forward and reverse DNS mapping of the UTS nodenames should be
342 consistent
343 .IP
344 The hostname the client uses to mount the server should match the server's
345 .I mon_name
346 in SM_NOTIFY requests it sends
347 .PP
348 Unmounting an NFS file system does not necessarily stop
349 either the NFS client or server from monitoring each other.
350 Both may continue monitoring each other for a time in case subsequent
351 NFS traffic between the two results in fresh mounts and additional
352 file locking.
353 .PP
354 On Linux, if the
355 .B lockd
356 kernel module is unloaded during normal operation,
357 all remote NFS peers are unmonitored.
358 This can happen on an NFS client, for example,
359 if an automounter removes all NFS mount
360 points due to inactivity.
361 .SS High-availability callouts
362 .B rpc.statd
363 can exec a special callout program during processing of
364 successful SM_MON, SM_UNMON, and SM_UNMON_ALL requests,
365 or when it receives SM_NOTIFY.
366 Such a program may be used in High Availability NFS (HA-NFS)
367 environments to track lock state that may need to be migrated after
368 a system reboot.
369 .PP
370 The name of the callout program is specified with the
371 .B -H
372 option.
373 The program is run with 3 arguments:
374 The first is either
375 .B add-client
376 .B del-client
377 or
378 .B sm-notify
379 depending on the reason for the callout.
380 The second is the
381 .I mon_name
382 of the monitored peer.
383 The third is the
384 .I caller_name
385 of the requesting lock manager for
386 .B add-client
387 or
388 .B del-client
389 , otherwise it is
390 .I IP_address
391 of the caller sending SM_NOTIFY.
392 The forth is the
393 .I state_value
394 in the SM_NOTIFY request.
395
396 .SS IPv6 and TI-RPC support
397 TI-RPC is a pre-requisite for supporting NFS on IPv6.
398 If TI-RPC support is built into
399 .BR rpc.statd ,
400 it attempts to start listeners on network transports marked 'visible' in
401 .IR /etc/netconfig .
402 As long as at least one network transport listener starts successfully,
403 .B rpc.statd
404 will operate.
405 .SH ENVIRONMENT
406 .TP
407 .B RPC_STATD_NO_NOTIFY=
408 If set to a positive integer, has the same effect as
409 .IR \-\-no\-notify .
410 .SH FILES
411 .TP 2.5i
412 .I /var/lib/nfs/statd/sm
413 directory containing monitor list
414 .TP 2.5i
415 .I /var/lib/nfs/statd/sm.bak
416 directory containing notify list
417 .TP 2.5i
418 .I /var/lib/nfs/statd/state
419 NSM state number for this host
420 .TP 2.5i
421 .I /run/run.statd.pid
422 pid file
423 .TP 2.5i
424 .I /etc/netconfig
425 network transport capability database
426 .SH SEE ALSO
427 .BR sm-notify (8),
428 .BR nfs (5),
429 .BR rpc.nfsd (8),
430 .BR rpcbind (8),
431 .BR tcpd (8),
432 .BR iptables (8),
433 .BR netconfig (5)
434 .sp
435 RFC 1094 - "NFS: Network File System Protocol Specification"
436 .br
437 RFC 1813 - "NFS Version 3 Protocol Specification"
438 .br
439 OpenGroup Protocols for Interworking: XNFS, Version 3W - Chapter 11
440 .SH AUTHORS
441 Jeff Uphoff <[email protected]>
442 .br
443 Olaf Kirch <[email protected]>
444 .br
445 H.J. Lu <[email protected]>
446 .br
447 Lon Hohberger <[email protected]>
448 .br
449 Paul Clements <[email protected]>
450 .br
451 Chuck Lever <[email protected]>