sm-notify - drop privileges before receiving packets from network.
[nfs-utils.git] / utils / statd / sm-notify.8
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>