Debian Codegraph @

upstream/debian-unstable/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
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 .PP
329 You can also protect your
330 .B rpc.statd
331 listeners using the
332 .B tcp_wrapper
333 library or
334 .BR iptables (8).
335 To use the
336 .B tcp_wrapper
337 library, add the hostnames of peers that should be allowed access to
338 .IR /etc/hosts.allow .
339 Use the daemon name
340 .B statd
341 even if the
342 .B rpc.statd
343 binary has a different filename.
344 .P
345 For further information see the
346 .BR tcpd (8)
347 and
348 .BR hosts_access (5)
349 man pages.
350 .SH ADDITIONAL NOTES
351 Lock recovery after a reboot is critical to maintaining data integrity
352 and preventing unnecessary application hangs.
353 To help
354 .B rpc.statd
355 match SM_NOTIFY requests to NLM requests, a number of best practices
356 should be observed, including:
357 .IP
358 The UTS nodename of your systems should match the DNS names that NFS
359 peers use to contact them
360 .IP
361 The UTS nodenames of your systems should always be fully qualified domain names
362 .IP
363 The forward and reverse DNS mapping of the UTS nodenames should be
364 consistent
365 .IP
366 The hostname the client uses to mount the server should match the server's
367 .I mon_name
368 in SM_NOTIFY requests it sends
369 .PP
370 Unmounting an NFS file system does not necessarily stop
371 either the NFS client or server from monitoring each other.
372 Both may continue monitoring each other for a time in case subsequent
373 NFS traffic between the two results in fresh mounts and additional
374 file locking.
375 .PP
376 On Linux, if the
377 .B lockd
378 kernel module is unloaded during normal operation,
379 all remote NFS peers are unmonitored.
380 This can happen on an NFS client, for example,
381 if an automounter removes all NFS mount
382 points due to inactivity.
383 .SS High-availability callouts
384 .B rpc.statd
385 can exec a special callout program during processing of
386 successful SM_MON, SM_UNMON, and SM_UNMON_ALL requests,
387 or when it receives SM_NOTIFY.
388 Such a program may be used in High Availability NFS (HA-NFS)
389 environments to track lock state that may need to be migrated after
390 a system reboot.
391 .PP
392 The name of the callout program is specified with the
393 .B -H
394 option.
395 The program is run with 3 arguments:
396 The first is either
397 .B add-client
398 .B del-client
399 or
400 .B sm-notify
401 depending on the reason for the callout.
402 The second is the
403 .I mon_name
404 of the monitored peer.
405 The third is the
406 .I caller_name
407 of the requesting lock manager for
408 .B add-client
409 or
410 .B del-client
411 , otherwise it is
412 .I IP_address
413 of the caller sending SM_NOTIFY.
414 The forth is the
415 .I state_value
416 in the SM_NOTIFY request.
417
418 .SS IPv6 and TI-RPC support
419 TI-RPC is a pre-requisite for supporting NFS on IPv6.
420 If TI-RPC support is built into
421 .BR rpc.statd ,
422 it attempts to start listeners on network transports marked 'visible' in
423 .IR /etc/netconfig .
424 As long as at least one network transport listener starts successfully,
425 .B rpc.statd
426 will operate.
427 .SH ENVIRONMENT
428 .TP
429 .B RPC_STATD_NO_NOTIFY=
430 If set to a positive integer, has the same effect as
431 .IR \-\-no\-notify .
432 .SH FILES
433 .TP 2.5i
434 .I /var/lib/nfs/sm
435 directory containing monitor list
436 .TP 2.5i
437 .I /var/lib/nfs/sm.bak
438 directory containing notify list
439 .TP 2.5i
440 .I /var/lib/nfs/state
441 NSM state number for this host
442 .TP 2.5i
443 .I /run/run.statd.pid
444 pid file
445 .TP 2.5i
446 .I /etc/netconfig
447 network transport capability database
448 .SH SEE ALSO
449 .BR sm-notify (8),
450 .BR nfs (5),
451 .BR rpc.nfsd (8),
452 .BR rpcbind (8),
453 .BR tcpd (8),
454 .BR hosts_access (5),
455 .BR iptables (8),
456 .BR netconfig (5)
457 .sp
458 RFC 1094 - "NFS: Network File System Protocol Specification"
459 .br
460 RFC 1813 - "NFS Version 3 Protocol Specification"
461 .br
462 OpenGroup Protocols for Interworking: XNFS, Version 3W - Chapter 11
463 .SH AUTHORS
464 Jeff Uphoff <[email protected]>
465 .br
466 Olaf Kirch <[email protected]>
467 .br
468 H.J. Lu <[email protected]>
469 .br
470 Lon Hohberger <[email protected]>
471 .br
472 Paul Clements <[email protected]>
473 .br
474 Chuck Lever <[email protected]>