utils/statd/sm-notify.man

   1 .\"
   2 .\" sm-notify(8)
   3 .\"
   4 .\" Copyright (C) 2004 Olaf Kirch <okir@suse.de>
   5 .TH sm-notify 8 "19 Mar 2007
   6 .SH NAME
   7 sm-notify \- Send out NSM reboot notifications
   8 .SH SYNOPSIS
   9 .BI "/sbin/sm-notify [-dfq] [-m " time "] [-p " port "] [-P " path "] [-v " my_name " ]
  10 .SH DESCRIPTION
  11 File locking over NFS (v2 and v3) requires a facility to notify peers in
  12 case of a reboot, so that clients can reclaim locks after
  13 a server crash, and/or
  14 servers can release locks held by the rebooted client.
  15 .PP
  16 This is a two-step process: during normal
  17 operations, a mechanism is required to keep track of which
  18 hosts need to be informed of a reboot. And of course,
  19 notifications need to be sent out during reboot.
  20 The protocol used for this is called NSM, for
  21 .IR "Network Status Monitor" .
  22 .PP
  23 This implementation separates these into separate program.
  24 .B rpc.statd
  25 tracks hosts which need to be notified and this
  26 .B sm-notify
  27 performs the notification.  When
  28 .B rpc.statd
  29 is started it will typically started
  30 .B sm-notify
  31 but this is configurable.
  32 .SS Operation
  33 For each NFS client or server machine to be monitored,
  34 .B rpc.statd
  35 creates a file in
  36 .BR /var/lib/nfs/sm ", "
  37 and removes the file if monitoring is no longer required.
  38 .PP
  39 When the machine is rebooted,
  40 .B sm-notify
  41 iterates through these files and notifies the peer
  42 .B statd
  43 server on those machines.
  44 .PP
  45 Each machine has an
  46 .I "NSM state" ,
  47 which is basically an integer counter that is incremented
  48 each time the machine reboots. This counter is stored
  49 in
  50 .BR /var/lib/nfs/state ,
  51 and updated by
  52 .BR sm-notify .
  53 .SS Security
  54 .B sm-notify
  55 has little need for root privileges and so drops them as soon as
  56 possible.
  57 It continues to need to make changes to the
  58 .B sm
  59 and
  60 .B sm.bak
  61 directories so to be able to drop privileges, these must be writable
  62 by a non-privileged user.  If these directories are owned by a
  63 non-root user,
  64 .B sm-notify
  65 will drop privilege to match that user once it has created sockets for
  66 sending out request (for which it needs privileged) but before it
  67 processes any reply (which is the most likely source of possible
  68 privilege abuse).
  69 .SH OPTIONS
  70 .TP
  71 .BI -m " failtime
  72 When notifying hosts,
  73 .B sm-notify
  74 will try to contact each host for up to 15 minutes,
  75 and will give up if unable to reach it within this time
  76 frame.
  77 .IP
  78 Using the
  79 .B -m
  80 option, you can override this. A value of 0 tells
  81 sm-notify to retry indefinitely; any other value is
  82 interpreted as the maximum retry time in minutes.
  83 .TP
  84 .BI -v " ipaddr-or-hostname
  85 This option tells
  86 .B sm-notify
  87 to bind to the specified
  88 .IR ipaddr ,
  89 (or the ipaddr of the given
  90 .IR hostname )
  91 so that all notification packets originate from this address.
  92 This is useful for NFS failover.  The given name is also used as the
  93 .I name
  94 of this host in the NSM request.
  95 .TP
  96 .BI -p " port
  97 instructs
  98 .B sm-notify
  99 to bind to the indicated IP
 100 .IR port
 101 number. If this option is not given, it will try to bind to
 102 a randomly chosen privileged port below 1024.
 103 .TP
 104 .B -q
 105 Be quiet. This suppresses all messages except error
 106 messages while collecting the list of hosts.
 107 .TP
 108 .BI -P " /path/to/state/directory
 109 If
 110 .B sm-notify
 111 should look in a no-standard place of state file, the path can be
 112 given here.  The directories
 113 .B sm
 114 and
 115 .B sm.bak
 116 and the file
 117 .B state
 118 must exist in that directory with the standard names.
 119 .TP
 120 .B -f
 121 If the state path has not been reset with
 122 .BR -P ,
 123 .B sm-notify
 124 will normally create a file in
 125 .B /var/run
 126 to indicate that it has been
 127 run.  If this file is found when
 128 .B sm-notify
 129 starts, it will not run again (as it is normally only needed once per
 130 reboot).
 131 If
 132 .B -f
 133 (for
 134 .BR force )
 135 is given,
 136 .B sm-notify
 137 will run even if the file in
 138 .B /var/run
 139 is present.
 140 .TP
 141 .B -n
 142 Do not update the NSM state. This is for testing only.  Setting this
 143 flag implies
 144 .BR -f .
 145 .TP
 146 .B -d
 147 Enables debugging.
 148 By default,
 149 .B sm-notify
 150 forks and puts itself in the background after obtaining the
 151 list of hosts from
 152 .BR /var/lib/nfs/sm .
 153 .SH FILES
 154 .BR /var/lib/nfs/state
 155 .br
 156 .BR /var/lib/nfs/sm/*
 157 .br
 158 .BR /var/lib/nfs/sm.bak/*
 159 .br
 160 .BR /var/run/sm-notify.pid
 161 .SH SEE ALSO
 162 .BR rpc.nfsd(8),
 163 .BR portmap(8)
 164 .SH AUTHORS
 165 .br
 166 Olaf Kirch <okir@suse.de>