474 lines
12 KiB
HTML
474 lines
12 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of SM-NOTIFY</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>SM-NOTIFY</H1>
|
|
Section: Maintenance Commands (8)<BR>Updated: 1 November 2009<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
sm-notify - send reboot notifications to NFS peers
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>/usr/sbin/sm-notify [-dfn] [-m </B><I>minutes</I><B>] [-v </B><I>name</I><B>] [-p </B><I>notify-port</I><B>] [-P </B><I>path</I><B>]</B>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
File locks are not part of persistent file system state.
|
|
Lock state is thus lost when a host reboots.
|
|
<P>
|
|
|
|
Network file systems must also detect when lock state is lost
|
|
because a remote host has rebooted.
|
|
After an NFS client reboots, an NFS server must release all file locks
|
|
held by applications that were running on that client.
|
|
After a server reboots, a client must remind the
|
|
server of file locks held by applications running on that client.
|
|
<P>
|
|
|
|
For NFS version 2 and version 3, the
|
|
<I>Network Status Monitor</I>
|
|
|
|
protocol (or NSM for short)
|
|
is used to notify NFS peers of reboots.
|
|
On Linux, two separate user-space components constitute the NSM service:
|
|
<DL COMPACT>
|
|
<DT id="1"><B>sm-notify</B>
|
|
|
|
<DD>
|
|
A helper program that notifies NFS peers after the local system reboots
|
|
<DT id="2"><B>rpc.statd</B>
|
|
|
|
<DD>
|
|
A daemon that listens for reboot notifications from other hosts, and
|
|
manages the list of hosts to be notified when the local system reboots
|
|
</DL>
|
|
<P>
|
|
|
|
The local NFS lock manager alerts its local
|
|
<B>rpc.statd</B>
|
|
|
|
of each remote peer that should be monitored.
|
|
When the local system reboots, the
|
|
<B>sm-notify</B>
|
|
|
|
command notifies the NSM service on monitored peers of the reboot.
|
|
When a remote reboots, that peer notifies the local
|
|
<B>rpc.statd</B>,
|
|
|
|
which in turn passes the reboot notification
|
|
back to the local NFS lock manager.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>NSM OPERATION IN DETAIL</H2>
|
|
|
|
The first file locking interaction between an NFS client and server causes
|
|
the NFS lock managers on both peers to contact their local NSM service to
|
|
store information about the opposite peer.
|
|
On Linux, the local lock manager contacts
|
|
<B>rpc.statd</B>.
|
|
|
|
<P>
|
|
|
|
<B>rpc.statd</B>
|
|
|
|
records information about each monitored NFS peer on persistent storage.
|
|
This information describes how to contact a remote peer
|
|
in case the local system reboots,
|
|
how to recognize which monitored peer is reporting a reboot,
|
|
and how to notify the local lock manager when a monitored peer
|
|
indicates it has rebooted.
|
|
<P>
|
|
|
|
An NFS client sends a hostname, known as the client's
|
|
<I>caller_name</I>,
|
|
|
|
in each file lock request.
|
|
An NFS server can use this hostname to send asynchronous GRANT
|
|
calls to a client, or to notify the client it has rebooted.
|
|
<P>
|
|
|
|
The Linux NFS server can provide the client's
|
|
<I>caller_name</I>
|
|
|
|
or the client's network address to
|
|
<B>rpc.statd</B>.
|
|
|
|
For the purposes of the NSM protocol,
|
|
this name or address is known as the monitored peer's
|
|
<I>mon_name</I>.
|
|
|
|
In addition, the local lock manager tells
|
|
<B>rpc.statd</B>
|
|
|
|
what it thinks its own hostname is.
|
|
For the purposes of the NSM protocol,
|
|
this hostname is known as
|
|
<I>my_name</I>.
|
|
|
|
<P>
|
|
|
|
There is no equivalent interaction between an NFS server and a client
|
|
to inform the client of the server's
|
|
<I>caller_name</I>.
|
|
|
|
Therefore NFS clients do not actually know what
|
|
<I>mon_name</I>
|
|
|
|
an NFS server might use in an SM_NOTIFY request.
|
|
The Linux NFS client records the server's hostname used on the mount command
|
|
to identify rebooting NFS servers.
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Reboot notification</H3>
|
|
|
|
When the local system reboots, the
|
|
<B>sm-notify</B>
|
|
|
|
command reads the list of monitored peers from persistent storage and
|
|
sends an SM_NOTIFY request to the NSM service on each listed remote peer.
|
|
It uses the
|
|
<I>mon_name</I>
|
|
|
|
string as the destination.
|
|
To identify which host has rebooted, the
|
|
<B>sm-notify</B>
|
|
|
|
command normally sends
|
|
<I>my_name</I>
|
|
|
|
string recorded when that remote was monitored.
|
|
The remote
|
|
<B>rpc.statd</B>
|
|
|
|
matches incoming SM_NOTIFY requests using this string,
|
|
or the caller's network address,
|
|
to one or more peers on its own monitor list.
|
|
<P>
|
|
|
|
If
|
|
<B>rpc.statd</B>
|
|
|
|
does not find a peer on its monitor list that matches
|
|
an incoming SM_NOTIFY request,
|
|
the notification is not forwarded to the local lock manager.
|
|
In addition, each peer has its own
|
|
<I>NSM state number</I>,
|
|
|
|
a 32-bit integer that is bumped after each reboot by the
|
|
<B>sm-notify</B>
|
|
|
|
command.
|
|
<B>rpc.statd</B>
|
|
|
|
uses this number to distinguish between actual reboots
|
|
and replayed notifications.
|
|
<P>
|
|
|
|
Part of NFS lock recovery is rediscovering
|
|
which peers need to be monitored again.
|
|
The
|
|
<B>sm-notify</B>
|
|
|
|
command clears the monitor list on persistent storage after each reboot.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="3"><B>-d</B>
|
|
|
|
<DD>
|
|
Keeps
|
|
<B>sm-notify</B>
|
|
|
|
attached to its controlling terminal and running in the foreground
|
|
so that notification progress may be monitored directly.
|
|
<DT id="4"><B>-f</B>
|
|
|
|
<DD>
|
|
Send notifications even if
|
|
<B>sm-notify</B>
|
|
|
|
has already run since the last system reboot.
|
|
<DT id="5"><B>-m</B><I> retry-time</I>
|
|
|
|
<DD>
|
|
Specifies the length of time, in minutes, to continue retrying
|
|
notifications to unresponsive hosts.
|
|
If this option is not specified,
|
|
<B>sm-notify</B>
|
|
|
|
attempts to send notifications for 15 minutes.
|
|
Specifying a value of 0 causes
|
|
<B>sm-notify</B>
|
|
|
|
to continue sending notifications to unresponsive peers
|
|
until it is manually killed.
|
|
<DT id="6"><DD>
|
|
Notifications are retried if sending fails,
|
|
the remote does not respond,
|
|
the remote's NSM service is not registered,
|
|
or if there is a DNS failure
|
|
which prevents the remote's
|
|
<I>mon_name</I>
|
|
|
|
from being resolved to an address.
|
|
<DT id="7"><DD>
|
|
Hosts are not removed from the notification list until a valid
|
|
reply has been received.
|
|
However, the SM_NOTIFY procedure has a void result.
|
|
There is no way for
|
|
<B>sm-notify</B>
|
|
|
|
to tell if the remote recognized the sender and has started
|
|
appropriate lock recovery.
|
|
<DT id="8"><B>-n</B>
|
|
|
|
<DD>
|
|
Prevents
|
|
<B>sm-notify</B>
|
|
|
|
from updating the local system's NSM state number.
|
|
<DT id="9"><B>-p</B><I> port</I>
|
|
|
|
<DD>
|
|
Specifies the source port number
|
|
<B>sm-notify</B>
|
|
|
|
should use when sending reboot notifications.
|
|
If this option is not specified, a randomly chosen ephemeral port is used.
|
|
<DT id="10"><DD>
|
|
This option can be used to traverse a firewall between client and server.
|
|
<DT id="11"><B>-P, </B><I></I><B>--state-directory-path</B><I> pathname</I>
|
|
|
|
<DD>
|
|
Specifies the pathname of the parent directory
|
|
where NSM state information resides.
|
|
If this option is not specified,
|
|
<B>sm-notify</B>
|
|
|
|
uses
|
|
<I>/var/lib/nfs</I>
|
|
|
|
by default.
|
|
<DT id="12"><DD>
|
|
After starting,
|
|
<B>sm-notify</B>
|
|
|
|
attempts to set its effective UID and GID to the owner
|
|
and group of the subdirectory
|
|
<B>sm</B>
|
|
|
|
of this directory. After changing the effective ids,
|
|
<B>sm-notify</B>
|
|
|
|
only needs to access files in
|
|
<B>sm</B>
|
|
|
|
and
|
|
<B>sm.bak</B>
|
|
|
|
within the state-directory-path.
|
|
<DT id="13"><B>-v</B><I> ipaddr </I><B>|</B><I> hostname</I>
|
|
|
|
<DD>
|
|
Specifies the network address from which to send reboot notifications,
|
|
and the
|
|
<I>mon_name</I>
|
|
|
|
argument to use when sending SM_NOTIFY requests.
|
|
If this option is not specified,
|
|
<B>sm-notify</B>
|
|
|
|
uses a wildcard address as the transport bind address,
|
|
and uses the
|
|
<I>my_name</I>
|
|
|
|
recorded when the remote was monitored as the
|
|
<I>mon_name</I>
|
|
|
|
argument when sending SM_NOTIFY requests.
|
|
<DT id="14"><DD>
|
|
The
|
|
<I>ipaddr</I>
|
|
|
|
form can be expressed as either an IPv4 or an IPv6 presentation address.
|
|
If the
|
|
<I>ipaddr</I>
|
|
|
|
form is used, the
|
|
<B>sm-notify</B>
|
|
|
|
command converts this address to a hostname for use as the
|
|
<I>mon_name</I>
|
|
|
|
argument when sending SM_NOTIFY requests.
|
|
<DT id="15"><DD>
|
|
This option can be useful in multi-homed configurations where
|
|
the remote requires notification from a specific network address.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>SECURITY</H2>
|
|
|
|
The
|
|
<B>sm-notify</B>
|
|
|
|
command must be started as root to acquire privileges needed
|
|
to access the state information database.
|
|
It drops root privileges
|
|
as soon as it starts up to reduce the risk of a privilege escalation attack.
|
|
<P>
|
|
|
|
During normal operation,
|
|
the effective user ID it chooses is the owner of the state directory.
|
|
This allows it to continue to access files in that directory after it
|
|
has dropped its root privileges.
|
|
To control which user ID
|
|
<B>rpc.statd</B>
|
|
|
|
chooses, simply use
|
|
<B><A HREF="/cgi-bin/man/man2html?1+chown">chown</A></B>(1)
|
|
|
|
to set the owner of
|
|
the state directory.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>ADDITIONAL NOTES</H2>
|
|
|
|
Lock recovery after a reboot is critical to maintaining data integrity
|
|
and preventing unnecessary application hangs.
|
|
<P>
|
|
|
|
To help
|
|
<B>rpc.statd</B>
|
|
|
|
match SM_NOTIFY requests to NLM requests, a number of best practices
|
|
should be observed, including:
|
|
<DL COMPACT>
|
|
<DT id="16"><DD>
|
|
The UTS nodename of your systems should match the DNS names that NFS
|
|
peers use to contact them
|
|
<DT id="17"><DD>
|
|
The UTS nodenames of your systems should always be fully qualified domain names
|
|
<DT id="18"><DD>
|
|
The forward and reverse DNS mapping of the UTS nodenames should be
|
|
consistent
|
|
<DT id="19"><DD>
|
|
The hostname the client uses to mount the server should match the server's
|
|
<I>mon_name</I>
|
|
|
|
in SM_NOTIFY requests it sends
|
|
</DL>
|
|
<P>
|
|
|
|
Unmounting an NFS file system does not necessarily stop
|
|
either the NFS client or server from monitoring each other.
|
|
Both may continue monitoring each other for a time in case subsequent
|
|
NFS traffic between the two results in fresh mounts and additional
|
|
file locking.
|
|
<P>
|
|
|
|
On Linux, if the
|
|
<B>lockd</B>
|
|
|
|
kernel module is unloaded during normal operation,
|
|
all remote NFS peers are unmonitored.
|
|
This can happen on an NFS client, for example,
|
|
if an automounter removes all NFS mount
|
|
points due to inactivity.
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>IPv6 and TI-RPC support</H3>
|
|
|
|
TI-RPC is a pre-requisite for supporting NFS on IPv6.
|
|
If TI-RPC support is built into the
|
|
<B>sm-notify</B>
|
|
|
|
command ,it will choose an appropriate IPv4 or IPv6 transport
|
|
based on the network address returned by DNS for each remote peer.
|
|
It should be fully compatible with remote systems
|
|
that do not support TI-RPC or IPv6.
|
|
<P>
|
|
|
|
Currently, the
|
|
<B>sm-notify</B>
|
|
|
|
command supports sending notification only via datagram transport protocols.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>FILES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="20"><I>/var/lib/nfs/sm</I>
|
|
|
|
<DD>
|
|
directory containing monitor list
|
|
<DT id="21"><I>/var/lib/nfs/sm.bak</I>
|
|
|
|
<DD>
|
|
directory containing notify list
|
|
<DT id="22"><I>/var/lib/nfs/state</I>
|
|
|
|
<DD>
|
|
NSM state number for this host
|
|
<DT id="23"><I>/proc/sys/fs/nfs/nsm_local_state</I>
|
|
|
|
<DD>
|
|
kernel's copy of the NSM state number
|
|
</DL>
|
|
<A NAME="lbAL"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?8+rpc.statd">rpc.statd</A></B>(8),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?5+nfs">nfs</A></B>(5),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+uname">uname</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+hostname">hostname</A></B>(7)
|
|
|
|
<P>
|
|
|
|
RFC 1094 - "NFS: Network File System Protocol Specification"
|
|
<BR>
|
|
|
|
RFC 1813 - "NFS Version 3 Protocol Specification"
|
|
<BR>
|
|
|
|
OpenGroup Protocols for Interworking: XNFS, Version 3W - Chapter 11
|
|
<A NAME="lbAM"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
Olaf Kirch <<A HREF="mailto:okir@suse.de">okir@suse.de</A>>
|
|
<BR>
|
|
|
|
Chuck Lever <<A HREF="mailto:chuck.lever@oracle.com">chuck.lever@oracle.com</A>>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="24"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="25"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="26"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="27"><A HREF="#lbAE">NSM OPERATION IN DETAIL</A><DD>
|
|
<DL>
|
|
<DT id="28"><A HREF="#lbAF">Reboot notification</A><DD>
|
|
</DL>
|
|
<DT id="29"><A HREF="#lbAG">OPTIONS</A><DD>
|
|
<DT id="30"><A HREF="#lbAH">SECURITY</A><DD>
|
|
<DT id="31"><A HREF="#lbAI">ADDITIONAL NOTES</A><DD>
|
|
<DL>
|
|
<DT id="32"><A HREF="#lbAJ">IPv6 and TI-RPC support</A><DD>
|
|
</DL>
|
|
<DT id="33"><A HREF="#lbAK">FILES</A><DD>
|
|
<DT id="34"><A HREF="#lbAL">SEE ALSO</A><DD>
|
|
<DT id="35"><A HREF="#lbAM">AUTHORS</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:16 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|