utils/statd/sm-notify.man

   1 .\"@(#)sm-notify.8"
   2 .\"
   3 .\" Copyright (C) 2004 Olaf Kirch <okir@suse.de>
   4 .\"
   5 .\" Rewritten by Chuck Lever <chuck.lever@oracle.com>, 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 the results of
 101 .BR gethostname (3)
 102 as the
 103 .I my_name
 104 string.
 105 The remote
 106 .B rpc.statd
 107 matches incoming SM_NOTIFY requests using this string,
 108 or the caller's network address,
 109 to one or more peers on its own monitor list.
 110 .PP
 111 If
 112 .B rpc.statd
 113 does not find a peer on its monitor list that matches
 114 an incoming SM_NOTIFY request,
 115 the notification is not forwarded to the local lock manager.
 116 In addition, each peer has its own
 117 .IR "NSM state number" ,
 118 a 32-bit integer that is bumped after each reboot by the
 119 .B sm-notify
 120 command.
 121 .B rpc.statd
 122 uses this number to distinguish between actual reboots
 123 and replayed notifications.
 124 .PP
 125 Part of NFS lock recovery is rediscovering
 126 which peers need to be monitored again.
 127 The
 128 .B sm-notify
 129 command clears the monitor list on persistent storage after each reboot.
 130 .SH OPTIONS
 131 .TP
 132 .B -d
 133 Keeps
 134 .B sm-notify
 135 attached to its controlling terminal and running in the foreground
 136 so that notification progress may be monitored directly.
 137 .TP
 138 .B -f
 139 Send notifications even if
 140 .B sm-notify
 141 has already run since the last system reboot.
 142 .TP
 143 .BI -m " retry-time
 144 Specifies the length of time, in minutes, to continue retrying
 145 notifications to unresponsive hosts.
 146 If this option is not specified,
 147 .B sm-notify
 148 attempts to send notifications for 15 minutes.
 149 Specifying a value of 0 causes
 150 .B sm-notify
 151 to continue sending notifications to unresponsive peers
 152 until it is manually killed.
 153 .IP
 154 Notifications are retried if sending fails,
 155 the remote does not respond,
 156 the remote's NSM service is not registered,
 157 or if there is a DNS failure
 158 which prevents the remote's
 159 .I mon_name
 160 from being resolved to an address.
 161 .IP
 162 Hosts are not removed from the notification list until a valid
 163 reply has been received.
 164 However, the SM_NOTIFY procedure has a void result.
 165 There is no way for
 166 .B sm-notify
 167 to tell if the remote recognized the sender and has started
 168 appropriate lock recovery.
 169 .TP
 170 .B -n
 171 Prevents
 172 .B sm-notify
 173 from updating the local system's NSM state number.
 174 .TP
 175 .BI -p " port
 176 Specifies the source port number
 177 .B sm-notify
 178 should use when sending reboot notifications.
 179 If this option is not specified, a randomly chosen ephemeral port is used.
 180 .IP
 181 This option can be used to traverse a firewall between client and server.
 182 .TP
 183 .BI "\-P, " "" \-\-state\-directory\-path " pathname
 184 Specifies the pathname of the parent directory
 185 where NSM state information resides.
 186 If this option is not specified,
 187 .B sm-notify
 188 uses
 189 .I /var/lib/nfs
 190 by default.
 191 .IP
 192 After starting,
 193 .B sm-notify
 194 attempts to set its effective UID and GID to the owner
 195 and group of this directory.
 196 .TP
 197 .BI -v " ipaddr " | " hostname
 198 Specifies the network address from which to send reboot notifications,
 199 and the
 200 .I mon_name
 201 argument to use when sending SM_NOTIFY requests.
 202 If this option is not specified,
 203 .B sm-notify
 204 uses a wildcard address as the transport bind address,
 205 and uses the results of
 206 .BR gethostname (3)
 207 as the
 208 .I mon_name
 209 argument.
 210 .IP
 211 The
 212 .I ipaddr
 213 form can be expressed as either an IPv4 or an IPv6 presentation address.
 214 .IP
 215 This option can be useful in multi-homed configurations where
 216 the remote requires notification from a specific network address.
 217 .SH SECURITY
 218 The
 219 .B sm-notify
 220 command must be started as root to acquire privileges needed
 221 to access the state information database.
 222 It drops root privileges
 223 as soon as it starts up to reduce the risk of a privilege escalation attack.
 224 .PP
 225 During normal operation,
 226 the effective user ID it chooses is the owner of the state directory.
 227 This allows it to continue to access files in that directory after it
 228 has dropped its root privileges.
 229 To control which user ID
 230 .B rpc.statd
 231 chooses, simply use
 232 .BR chown (1)
 233 to set the owner of
 234 the state directory.
 235 .SH ADDITIONAL NOTES
 236 Lock recovery after a reboot is critical to maintaining data integrity
 237 and preventing unnecessary application hangs.
 238 .PP
 239 To help
 240 .B rpc.statd
 241 match SM_NOTIFY requests to NLM requests, a number of best practices
 242 should be observed, including:
 243 .IP
 244 The UTS nodename of your systems should match the DNS names that NFS
 245 peers use to contact them
 246 .IP
 247 The UTS nodenames of your systems should always be fully qualified domain names
 248 .IP
 249 The forward and reverse DNS mapping of the UTS nodenames should be
 250 consistent
 251 .IP
 252 The hostname the client uses to mount the server should match the server's
 253 .I mon_name
 254 in SM_NOTIFY requests it sends
 255 .IP
 256 The use of network addresses as a
 257 .I mon_name
 258 or a
 259 .I my_name
 260 string should be avoided when
 261 interoperating with non-Linux NFS implementations.
 262 .PP
 263 Unmounting an NFS file system does not necessarily stop
 264 either the NFS client or server from monitoring each other.
 265 Both may continue monitoring each other for a time in case subsequent
 266 NFS traffic between the two results in fresh mounts and additional
 267 file locking.
 268 .PP
 269 On Linux, if the
 270 .B lockd
 271 kernel module is unloaded during normal operation,
 272 all remote NFS peers are unmonitored.
 273 This can happen on an NFS client, for example,
 274 if an automounter removes all NFS mount
 275 points due to inactivity.
 276 .SS IPv6 and TI-RPC support
 277 TI-RPC is a pre-requisite for supporting NFS on IPv6.
 278 If TI-RPC support is built into the
 279 .B sm-notify
 280 command ,it will choose an appropriate IPv4 or IPv6 transport
 281 based on the network address returned by DNS for each remote peer.
 282 It should be fully compatible with remote systems
 283 that do not support TI-RPC or IPv6.
 284 .PP
 285 Currently, the
 286 .B sm-notify
 287 command supports sending notification only via datagram transport protocols.
 288 .SH FILES
 289 .TP 2.5i
 290 .I /var/lib/nfs/sm
 291 directory containing monitor list
 292 .TP 2.5i
 293 .I /var/lib/nfs/sm.bak
 294 directory containing notify list
 295 .TP 2.5i
 296 .I /var/lib/nfs/state
 297 NSM state number for this host
 298 .TP 2.5i
 299 .I /proc/sys/fs/nfs/nsm_local_state
 300 kernel's copy of the NSM state number
 301 .SH SEE ALSO
 302 .BR rpc.statd (8),
 303 .BR nfs (5),
 304 .BR uname (2),
 305 .BR hostname (7)
 306 .PP
 307 RFC 1094 - "NFS: Network File System Protocol Specification"
 308 .br
 309 RFC 1813 - "NFS Version 3 Protocol Specification"
 310 .br
 311 OpenGroup Protocols for Interworking: XNFS, Version 3W - Chapter 11
 312 .SH AUTHORS
 313 Olaf Kirch <okir@suse.de>
 314 .br
 315 Chuck Lever <chuck.lever@oracle.com>