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              This  string is only used by the sm-notify command as the source
126              address from which to send reboot notification requests.
127
128              The ipaddr form can be expressed as either an IPv4  or  an  IPv6
129              presentation   address.    If  this  option  is  not  specified,
130              rpc.statd uses a wildcard address as the transport bind address.
131              See sm-notify(8) for details.
132
133       -N     Causes  rpc.statd  to  run the sm-notify command, and then exit.
134              Since the sm-notify command  can  also  be  run  directly,  this
135              option is deprecated.
136
137       -o, --outgoing-port port
138              Specifies  the  source  port number the sm-notify command should
139              use when sending reboot  notifications.   See  sm-notify(8)  for
140              details.
141
142       -p, --port port
143              Specifies  the  port  number  used for RPC listener sockets.  If
144              this option is not specified,  rpc.statd  will  try  to  consult
145              /etc/services,  if  gets port succeed, set the same port for all
146              listener socket, otherwise chooses a random ephemeral  port  for
147              each listener socket.
148
149              This  option  can be used to fix the port value of its listeners
150              when SM_NOTIFY requests must traverse a firewall between clients
151              and servers.
152
153       -T, --nlm-port port
154              Specifies  the  port  number that lockd should listen on for NLM
155              requests.  This sets both the TCP and UDP ports unless  the  UDP
156              port is set separately.
157
158       -U, --nlm-udp-port port
159              Specifies  the  UDP  port number that lockd should listen on for
160              NLM requests.
161
162       -P, --state-directory-path pathname
163              Specifies the pathname of the parent directory where  NSM  state
164              information resides.  If this option is not specified, rpc.statd
165              uses /var/lib/nfs/statd by default.
166
167              After starting, rpc.statd attempts to set its effective UID  and
168              GID to the owner and group of the subdirectory sm of this direc‐
169              tory.  After changing the effective ids, rpc.statd only needs to
170              access files in sm and sm.bak within the state-directory-path.
171
172       -v, -V, --version
173              Causes  rpc.statd  to  display version information on stderr and
174              then exit.
175

CONFIGURATION FILE

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

SECURITY

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

ADDITIONAL NOTES

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

ENVIRONMENT

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

FILES

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

SEE ALSO

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

AUTHORS

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