1RPC.STATD(8)                System Manager's Manual               RPC.STATD(8)
2
3
4

NAME

6       rpc.statd - NSM service daemon
7

SYNOPSIS

9       rpc.statd [-dh?FLNvV] [-H prog] [-n my-name] [-o outgoing-port]
10                 [-p listener-port] [-P path]
11                 [--nlm-port port] [--nlm-udp-port port]
12

DESCRIPTION

14       File locks are not part of persistent file system state.  Lock state is
15       thus lost when a host reboots.
16
17       Network file systems must also detect when lock state is lost because a
18       remote  host  has rebooted.  After an NFS client reboots, an NFS server
19       must release all file locks held by applications that were  running  on
20       that  client.   After a server reboots, a client must remind the server
21       of file locks held by applications running on that client.
22
23       For NFS version 2 [RFC1094] and NFS version 3  [RFC1813],  the  Network
24       Status  Monitor protocol (or NSM for short) is used to notify NFS peers
25       of reboots.  On Linux, two separate  user-space  components  constitute
26       the NSM service:
27
28       rpc.statd
29              A daemon that listens for reboot notifications from other hosts,
30              and manages the list of hosts to be notified when the local sys‐
31              tem reboots
32
33       sm-notify
34              A  helper program that notifies NFS peers after the local system
35              reboots
36
37       The local NFS lock manager alerts its local rpc.statd  of  each  remote
38       peer  that should be monitored.  When the local system reboots, the sm-
39       notify command notifies the NSM  service  on  monitored  peers  of  the
40       reboot.  When a remote reboots, that peer notifies the local rpc.statd,
41       which in turn passes the reboot notification back to the local NFS lock
42       manager.
43

NSM OPERATION IN DETAIL

45       The  first  file  locking  interaction between an NFS client and server
46       causes the NFS lock managers on both peers to contact their  local  NSM
47       service  to  store  information about the opposite peer.  On Linux, the
48       local lock manager contacts rpc.statd.
49
50       rpc.statd records information about each monitored NFS peer on  persis‐
51       tent  storage.  This information describes how to contact a remote peer
52       in case the local system reboots, how to recognize which monitored peer
53       is  reporting a reboot, and how to notify the local lock manager when a
54       monitored peer indicates it has rebooted.
55
56       An NFS client sends a hostname, known as the client's  caller_name,  in
57       each  file  lock  request.  An NFS server can use this hostname to send
58       asynchronous GRANT calls to a client, or to notify the  client  it  has
59       rebooted.
60
61       The  Linux  NFS  server  can  provide  the  client's caller_name or the
62       client's network address to rpc.statd.  For the  purposes  of  the  NSM
63       protocol,  this  name  or  address  is  known  as  the monitored peer's
64       mon_name.  In addition, the local lock manager tells rpc.statd what  it
65       thinks its own hostname is.  For the purposes of the NSM protocol, this
66       hostname is known as my_name.
67
68       There is no equivalent interaction between an NFS server and  a  client
69       to  inform  the  client  of  the  server's  caller_name.  Therefore NFS
70       clients do not actually know what mon_name an NFS server might  use  in
71       an  SM_NOTIFY  request.   The Linux NFS client uses the server hostname
72       from the mount command to identify rebooting NFS servers.
73
74   Reboot notification
75       When the local system reboots, the sm-notify command reads the list  of
76       monitored  peers from persistent storage and sends an SM_NOTIFY request
77       to the NSM service on each listed remote peer.  It  uses  the  mon_name
78       string  as  the  destination.  To identify which host has rebooted, the
79       sm-notify command sends the my_name string recorded  when  that  remote
80       was   monitored.   The  remote  rpc.statd  matches  incoming  SM_NOTIFY
81       requests using this string, or the caller's network address, to one  or
82       more peers on its own monitor list.
83
84       If  rpc.statd  does not find a peer on its monitor list that matches an
85       incoming SM_NOTIFY request, the notification is not  forwarded  to  the
86       local  lock manager.  In addition, each peer has its own NSM state num‐
87       ber, a 32-bit integer that is bumped after each reboot by the sm-notify
88       command.   rpc.statd  uses  this  number  to distinguish between actual
89       reboots and replayed notifications.
90
91       Part of NFS lock recovery is rediscovering which peers need to be moni‐
92       tored  again.  The sm-notify command clears the monitor list on persis‐
93       tent storage after each reboot.
94

OPTIONS

96       -d, --no-syslog
97              Causes rpc.statd to write log messages on stderr instead  of  to
98              the system log, if the -F option was also specified.
99
100       -F, --foreground
101              Keeps rpc.statd attached to its controlling terminal so that NSM
102              operation can be monitored directly or run under a debugger.  If
103              this  option is not specified, rpc.statd backgrounds itself soon
104              after it starts.
105
106       -h, -?, --help
107              Causes rpc.statd to display usage information on stderr and then
108              exit.
109
110       -H, --ha-callout prog
111              Specifies  a  high availability callout program.  If this option
112              is not specified, no callouts  are  performed.   See  the  High-
113              availability callouts section below for details.
114
115       -L, --no-notify
116              Prevents  rpc.statd  from  running the sm-notify command when it
117              starts up, preserving the existing NSM state number and  monitor
118              list.
119
120              Note:  the  sm-notify command contains a check to ensure it runs
121              only once after each  system  reboot.   This  prevents  spurious
122              reboot notification if rpc.statd restarts without the -L option.
123
124       -n, --name ipaddr | hostname
125              Specifies  the  bind address used for RPC listener sockets.  The
126              ipaddr form can be expressed as either an IPv4 or an  IPv6  pre‐
127              sentation  address.   If this option is not specified, rpc.statd
128              uses a wildcard address as the transport bind address.
129
130              This string is also passed to the sm-notify command to  be  used
131              as  the  source  address  from which to send reboot notification
132              requests.  See sm-notify(8) for details.
133
134       -N     Causes rpc.statd to run the sm-notify command,  and  then  exit.
135              Since  the  sm-notify  command  can  also  be run directly, this
136              option is deprecated.
137
138       -o, --outgoing-port port
139              Specifies the source port number the  sm-notify  command  should
140              use  when  sending  reboot  notifications.  See sm-notify(8) for
141              details.
142
143       -p, --port port
144              Specifies the port number used for  RPC  listener  sockets.   If
145              this  option  is  not  specified,  rpc.statd will try to consult
146              /etc/services, if gets port succeed, set the same port  for  all
147              listener  socket,  otherwise chooses a random ephemeral port for
148              each listener socket.
149
150              This option can be used to fix the port value of  its  listeners
151              when SM_NOTIFY requests must traverse a firewall between clients
152              and servers.
153
154       -T, --nlm-port port
155              Specifies the port number that lockd should listen  on  for  NLM
156              requests.   This  sets both the TCP and UDP ports unless the UDP
157              port is set separately.
158
159       -U, --nlm-udp-port port
160              Specifies the UDP port number that lockd should  listen  on  for
161              NLM requests.
162
163       -P, --state-directory-path pathname
164              Specifies  the  pathname of the parent directory where NSM state
165              information resides.  If this option is not specified, rpc.statd
166              uses /var/lib/nfs/statd by default.
167
168              After  starting, rpc.statd attempts to set its effective UID and
169              GID to the owner and group of this directory.
170
171       -v, -V, --version
172              Causes rpc.statd to display version information  on  stderr  and
173              then exit.
174

CONFIGURATION FILE

176       Many  of  the  options  that can be set on the command line can also be
177       controlled through values set in the [statd] or,  in  some  cases,  the
178       [lockd]  sections of the /etc/nfs.conf configuration file.  Values rec‐
179       ognized in the  [statd]  section  include  port,  outgoing-port,  name,
180       state-directory-path, and ha-callout which each have the same effect as
181       the option with the same name.
182
183       The values recognized in the [lockd] section include port and  udp-port
184       which  have  the  same  effect  as  the  --nlm-port  and --nlm-udp-port
185       options, respectively.
186
187

SECURITY

189       The rpc.statd daemon must be started  as  root  to  acquire  privileges
190       needed  to  create  sockets with privileged source ports, and to access
191       the state information database.  Because rpc.statd  maintains  a  long-
192       running  network  service, however, it drops root privileges as soon as
193       it starts up to reduce the risk of a privilege escalation attack.
194
195       During normal operation, the effective user ID it chooses is the  owner
196       of  the state directory.  This allows it to continue to access files in
197       that directory after it has dropped its root  privileges.   To  control
198       which  user  ID rpc.statd chooses, simply use chown(1) to set the owner
199       of the state directory.
200

ADDITIONAL NOTES

202       Lock recovery after a reboot is critical to maintaining data  integrity
203       and  preventing unnecessary application hangs.  To help rpc.statd match
204       SM_NOTIFY requests to NLM requests, a number of best  practices  should
205       be observed, including:
206
207              The UTS nodename of your systems should match the DNS names that
208              NFS peers use to contact them
209
210              The UTS nodenames of your systems should always be fully  quali‐
211              fied domain names
212
213              The  forward and reverse DNS mapping of the UTS nodenames should
214              be consistent
215
216              The hostname the client uses to mount the  server  should  match
217              the server's mon_name in SM_NOTIFY requests it sends
218
219       Unmounting  an NFS file system does not necessarily stop either the NFS
220       client or server from monitoring each other.  Both may  continue  moni‐
221       toring each other for a time in case subsequent NFS traffic between the
222       two results in fresh mounts and additional file locking.
223
224       On Linux, if the lockd kernel module is unloaded during  normal  opera‐
225       tion,  all remote NFS peers are unmonitored.  This can happen on an NFS
226       client, for example, if an automounter removes all NFS mount points due
227       to inactivity.
228
229   High-availability callouts
230       rpc.statd  can exec a special callout program during processing of suc‐
231       cessful  SM_MON,  SM_UNMON,  and  SM_UNMON_ALL  requests,  or  when  it
232       receives  SM_NOTIFY.   Such  a program may be used in High Availability
233       NFS (HA-NFS) environments to track lock  state  that  may  need  to  be
234       migrated after a system reboot.
235
236       The  name  of the callout program is specified with the -H option.  The
237       program is run with 3 arguments: The first is  either  add-client  del-
238       client  or sm-notify depending on the reason for the callout.  The sec‐
239       ond is the mon_name of the monitored peer.   The  third  is  the  call‐
240       er_name  of  the requesting lock manager for add-client or del-client ,
241       otherwise it is IP_address of the caller sending SM_NOTIFY.  The  forth
242       is the state_value in the SM_NOTIFY request.
243
244
245   IPv6 and TI-RPC support
246       TI-RPC  is  a pre-requisite for supporting NFS on IPv6.  If TI-RPC sup‐
247       port is built into rpc.statd, it attempts to start listeners on network
248       transports marked 'visible' in /etc/netconfig.  As long as at least one
249       network transport listener starts successfully, rpc.statd will operate.
250

ENVIRONMENT

252       RPC_STATD_NO_NOTIFY=
253              If  set  to  a  positive  integer,  has  the  same   effect   as
254              --no-notify.
255

FILES

257       /var/lib/nfs/statd/sm    directory containing monitor list
258
259       /var/lib/nfs/statd/sm.bak
260                                directory containing notify list
261
262       /var/lib/nfs/statd/state NSM state number for this host
263
264       /var/run/run.statd.pid   pid file
265
266       /etc/netconfig           network transport capability database
267

SEE ALSO

269       sm-notify(8),  nfs(5),  rpc.nfsd(8),  rpcbind(8), tcpd(8), iptables(8),
270       netconfig(5)
271
272       RFC 1094 - "NFS: Network File System Protocol Specification"
273       RFC 1813 - "NFS Version 3 Protocol Specification"
274       OpenGroup Protocols for Interworking: XNFS, Version 3W - Chapter 11
275

AUTHORS

277       Jeff Uphoff <juphoff@users.sourceforge.net>
278       Olaf Kirch <okir@monad.swb.de>
279       H.J. Lu <hjl@gnu.org>
280       Lon Hohberger <hohberger@missioncriticallinux.com>
281       Paul Clements <paul.clements@steeleye.com>
282       Chuck Lever <chuck.lever@oracle.com>
283
284
285
286                                1 November 2009                   RPC.STATD(8)
Impressum