1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 14. File and Record Locking</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="SAMBA Project Documentation"><link rel="up" href="optional.html" title="Part III. Advanced Configuration"><link rel="previous" href="AccessControls.html" title="Chapter 13. File, Directory and Share Access Controls"><link rel="next" href="securing-samba.html" title="Chapter 15. Securing Samba"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 14. File and Record Locking</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="AccessControls.html">Prev</a> </td><th width="60%" align="center">Part III. Advanced Configuration</th><td width="20%" align="right"> <a accesskey="n" href="securing-samba.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="locking"></a>Chapter 14. File and Record Locking</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Jeremy</span> <span class="surname">Allison</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><tt class="email"><<a href="mailto:jra@samba.org">jra@samba.org</a>></tt></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Jelmer</span> <span class="othername">R.</span> <span class="surname">Vernooij</span></h3><div class="affiliation"><span class="orgname">The Samba Team<br></span><div class="address"><p><tt class="email"><<a href="mailto:jelmer@samba.org">jelmer@samba.org</a>></tt></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">John</span> <span class="othername">H.</span> <span class="surname">Terpstra</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><tt class="email"><<a href="mailto:jht@samba.org">jht@samba.org</a>></tt></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Eric</span> <span class="surname">Roseme</span></h3><div class="affiliation"><span class="orgname">HP Oplocks Usage Recommendations Whitepaper<br></span><div class="address"><p><tt class="email"><<a href="mailto:eric.roseme@hp.com">eric.roseme@hp.com</a>></tt></p></div></div></div></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="locking.html#id2928216">Features and Benefits</a></dt><dt><a href="locking.html#id2928272">Discussion</a></dt><dd><dl><dt><a href="locking.html#id2928403">Opportunistic Locking Overview</a></dt></dl></dd><dt><a href="locking.html#id2929049">Samba Opportunistic Locking Control</a></dt><dd><dl><dt><a href="locking.html#id2929159">Example Configuration</a></dt></dl></dd><dt><a href="locking.html#id2929419">MS Windows Opportunistic Locking and Caching Controls</a></dt><dd><dl><dt><a href="locking.html#id2929649">Workstation Service Entries</a></dt><dt><a href="locking.html#id2929676">Server Service Entries</a></dt></dl></dd><dt><a href="locking.html#id2929755">Persistent Data Corruption</a></dt><dt><a href="locking.html#id2929785">Common Errors</a></dt><dd><dl><dt><a href="locking.html#id2929859">locking.tdb error messages</a></dt></dl></dd><dt><a href="locking.html#id2929890">Additional Reading</a></dt></dl></div><p>
2 One area which causes trouble for many network administrators is locking.
3 The extent of the problem is readily evident from searches over the internet.
4 </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2928216"></a>Features and Benefits</h2></div></div><div></div></div><p>
5 Samba provides all the same locking semantics that MS Windows clients expect
6 and that MS Windows NT4 / 200x servers provide also.
8 The term <span class="emphasis"><em>locking</em></span> has exceptionally broad meaning and covers
9 a range of functions that are all categorized under this one term.
11 Opportunistic locking is a desirable feature when it can enhance the
12 perceived performance of applications on a networked client. However, the
13 opportunistic locking protocol is not robust, and therefore can
14 encounter problems when invoked beyond a simplistic configuration, or
15 on extended, slow, or faulty networks. In these cases, operating
16 system management of opportunistic locking and/or recovering from
17 repetitive errors can offset the perceived performance advantage that
18 it is intended to provide.
20 The MS Windows network administrator needs to be aware that file and record
21 locking semantics (behaviour) can be controlled either in Samba or by way of registry
22 settings on the MS Windows client.
23 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
24 Sometimes it is necessary to disable locking control settings BOTH on the Samba
25 server as well as on each MS Windows client!
26 </p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2928272"></a>Discussion</h2></div></div><div></div></div><p>
27 There are two types of locking which need to be performed by a SMB server.
28 The first is <span class="emphasis"><em>record locking</em></span> which allows a client to lock
29 a range of bytes in a open file. The second is the <span class="emphasis"><em>deny modes</em></span>
30 that are specified when a file is open.
32 Record locking semantics under Unix is very different from record locking under
33 Windows. Versions of Samba before 2.2 have tried to use the native fcntl() unix
34 system call to implement proper record locking between different Samba clients.
35 This can not be fully correct due to several reasons. The simplest is the fact
36 that a Windows client is allowed to lock a byte range up to 2^32 or 2^64,
37 depending on the client OS. The unix locking only supports byte ranges up to 2^31.
38 So it is not possible to correctly satisfy a lock request above 2^31. There are
39 many more differences, too many to be listed here.
41 Samba 2.2 and above implements record locking completely independent of the
42 underlying unix system. If a byte range lock that the client requests happens
43 to fall into the range 0-2^31, Samba hands this request down to the Unix system.
44 All other locks can not be seen by unix anyway.
46 Strictly a SMB server should check for locks before every read and write call on
47 a file. Unfortunately with the way fcntl() works this can be slow and may overstress
48 the <b class="command">rpc.lockd</b>. It is also almost always unnecessary as clients are supposed to
49 independently make locking calls before reads and writes anyway if locking is
50 important to them. By default Samba only makes locking calls when explicitly asked
51 to by a client, but if you set <i class="parameter"><tt>strict locking = yes</tt></i> then it
52 will make lock checking calls on every read and write.
54 You can also disable by range locking completely using <i class="parameter"><tt>locking = no</tt></i>.
55 This is useful for those shares that don't support locking or don't need it
56 (such as cdroms). In this case Samba fakes the return codes of locking calls to
57 tell clients that everything is OK.
59 The second class of locking is the <i class="parameter"><tt>deny modes</tt></i>. These
60 are set by an application when it opens a file to determine what types of
61 access should be allowed simultaneously with its open. A client may ask for
62 <tt class="constant">DENY_NONE</tt>, <tt class="constant">DENY_READ</tt>,
63 <tt class="constant">DENY_WRITE</tt> or <tt class="constant">DENY_ALL</tt>. There are also special compatibility
64 modes called <tt class="constant">DENY_FCB</tt> and <tt class="constant">DENY_DOS</tt>.
65 </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2928403"></a>Opportunistic Locking Overview</h3></div></div><div></div></div><p>
66 Opportunistic locking (Oplocks) is invoked by the Windows file system
67 (as opposed to an API) via registry entries (on the server AND client)
68 for the purpose of enhancing network performance when accessing a file
69 residing on a server. Performance is enhanced by caching the file
70 locally on the client which allows:
71 </p><div class="variablelist"><dl><dt><span class="term">Read-ahead:</span></dt><dd><p>
72 The client reads the local copy of the file, eliminating network latency
73 </p></dd><dt><span class="term">Write caching:</span></dt><dd><p>
74 The client writes to the local copy of the file, eliminating network latency
75 </p></dd><dt><span class="term">Lock caching:</span></dt><dd><p>
76 The client caches application locks locally, eliminating network latency
77 </p></dd></dl></div><p>
78 The performance enhancement of oplocks is due to the opportunity of
79 exclusive access to the file - even if it is opened with deny-none -
80 because Windows monitors the file's status for concurrent access from
82 </p><div class="variablelist"><p class="title"><b>Windows defines 4 kinds of Oplocks:</b></p><dl><dt><span class="term">Level1 Oplock:</span></dt><dd><p>
83 The redirector sees that the file was opened with deny
84 none (allowing concurrent access), verifies that no
85 other process is accessing the file, checks that
86 oplocks are enabled, then grants deny-all/read-write/exclusive
87 access to the file. The client now performs
88 operations on the cached local file.
90 If a second process attempts to open the file, the open
91 is deferred while the redirector "breaks" the original
92 oplock. The oplock break signals the caching client to
93 write the local file back to the server, flush the
94 local locks, and discard read-ahead data. The break is
95 then complete, the deferred open is granted, and the
96 multiple processes can enjoy concurrent file access as
97 dictated by mandatory or byte-range locking options.
98 However, if the original opening process opened the
99 file with a share mode other than deny-none, then the
100 second process is granted limited or no access, despite
102 </p></dd><dt><span class="term">Level2 Oplock:</span></dt><dd><p>
103 Performs like a level1 oplock, except caching is only
104 operative for reads. All other operations are performed
105 on the server disk copy of the file.
106 </p></dd><dt><span class="term">Filter Oplock:</span></dt><dd><p>
107 Does not allow write or delete file access
108 </p></dd><dt><span class="term">Batch Oplock:</span></dt><dd><p>
109 Manipulates file openings and closings - allows caching
111 </p></dd></dl></div><p>
112 An important detail is that oplocks are invoked by the file system, not
113 an application API. Therefore, an application can close an oplocked
114 file, but the file system does not relinquish the oplock. When the
115 oplock break is issued, the file system then simply closes the file in
116 preparation for the subsequent open by the second process.
118 <span class="emphasis"><em>Opportunistic Locking</em></span> is actually an improper name for this feature.
119 The true benefit of this feature is client-side data caching, and
120 oplocks is merely a notification mechanism for writing data back to the
121 networked storage disk. The limitation of opportunistic locking is the
122 reliability of the mechanism to process an oplock break (notification)
123 between the server and the caching client. If this exchange is faulty
124 (usually due to timing out for any number of reasons) then the
125 client-side caching benefit is negated.
127 The actual decision that a user or administrator should consider is
128 whether it is sensible to share amongst multiple users data that will
129 be cached locally on a client. In many cases the answer is no.
130 Deciding when to cache or not cache data is the real question, and thus
131 "opportunistic locking" should be treated as a toggle for client-side
132 caching. Turn it "ON" when client-side caching is desirable and
133 reliable. Turn it "OFF" when client-side caching is redundant,
134 unreliable, or counter-productive.
136 Opportunistic locking is by default set to "on" by Samba on all
137 configured shares, so careful attention should be given to each case to
138 determine if the potential benefit is worth the potential for delays.
139 The following recommendations will help to characterize the environment
140 where opportunistic locking may be effectively configured.
142 Windows Opportunistic Locking is a lightweight performance-enhancing
143 feature. It is not a robust and reliable protocol. Every
144 implementation of Opportunistic Locking should be evaluated as a
145 tradeoff between perceived performance and reliability. Reliability
146 decreases as each successive rule above is not enforced. Consider a
147 share with oplocks enabled, over a wide area network, to a client on a
148 South Pacific atoll, on a high-availability server, serving a
149 mission-critical multi-user corporate database, during a tropical
150 storm. This configuration will likely encounter problems with oplocks.
152 Oplocks can be beneficial to perceived client performance when treated
153 as a configuration toggle for client-side data caching. If the data
154 caching is likely to be interrupted, then oplock usage should be
155 reviewed. Samba enables opportunistic locking by default on all
156 shares. Careful attention should be given to the client usage of
157 shared data on the server, the server network reliability, and the
158 opportunistic locking configuration of each share.
159 n mission critical high availability environments, data integrity is
160 often a priority. Complex and expensive configurations are implemented
161 to ensure that if a client loses connectivity with a file server, a
162 failover replacement will be available immediately to provide
163 continuous data availability.
165 Windows client failover behavior is more at risk of application
166 interruption than other platforms because it is dependant upon an
167 established TCP transport connection. If the connection is interrupted
168 - as in a file server failover - a new session must be established.
169 It is rare for Windows client applications to be coded to recover
170 correctly from a transport connection loss, therefore most applications
171 will experience some sort of interruption - at worst, abort and
174 If a client session has been caching writes and reads locally due to
175 opportunistic locking, it is likely that the data will be lost when the
176 application restarts, or recovers from the TCP interrupt. When the TCP
177 connection drops, the client state is lost. When the file server
178 recovers, an oplock break is not sent to the client. In this case, the
179 work from the prior session is lost. Observing this scenario with
180 oplocks disabled, and the client was writing data to the file server
181 real-time, then the failover will provide the data on disk as it
182 existed at the time of the disconnect.
184 In mission critical high availability environments, careful attention
185 should be given to opportunistic locking. Ideally, comprehensive
186 testing should be done with all affected applications with oplocks
187 enabled and disabled.
188 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2928695"></a>Exclusively Accessed Shares</h4></div></div><div></div></div><p>
189 Opportunistic locking is most effective when it is confined to shares
190 that are exclusively accessed by a single user, or by only one user at
191 a time. Because the true value of opportunistic locking is the local
192 client caching of data, any operation that interrupts the caching
193 mechanism will cause a delay.
195 Home directories are the most obvious examples of where the performance
196 benefit of opportunistic locking can be safely realized.
197 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2928719"></a>Multiple-Accessed Shares or Files</h4></div></div><div></div></div><p>
198 As each additional user accesses a file in a share with opportunistic
199 locking enabled, the potential for delays and resulting perceived poor
200 performance increases. When multiple users are accessing a file on a
201 share that has oplocks enabled, the management impact of sending and
202 receiving oplock breaks, and the resulting latency while other clients
203 wait for the caching client to flush data, offset the performance gains
206 As each additional client attempts to access a file with oplocks set,
207 the potential performance improvement is negated and eventually results
208 in a performance bottleneck.
209 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2928748"></a>Unix or NFS Client Accessed Files</h4></div></div><div></div></div><p>
210 Local Unix and NFS clients access files without a mandatory
211 file locking mechanism. Thus, these client platforms are incapable of
212 initiating an oplock break request from the server to a Windows client
213 that has a file cached. Local Unix or NFS file access can therefore
214 write to a file that has been cached by a Windows client, which
215 exposes the file to likely data corruption.
217 If files are shared between Windows clients, and either local Unix
218 or NFS users, then turn opportunistic locking off.
219 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2928775"></a>Slow and/or Unreliable Networks</h4></div></div><div></div></div><p>
220 The biggest potential performance improvement for opportunistic locking
221 occurs when the client-side caching of reads and writes delivers the
222 most differential over sending those reads and writes over the wire.
223 This is most likely to occur when the network is extremely slow,
224 congested, or distributed (as in a WAN). However, network latency also
225 has a very high impact on the reliability of the oplock break
226 mechanism, and thus increases the likelihood of encountering oplock
227 problems that more than offset the potential perceived performance
228 gain. Of course, if an oplock break never has to be sent, then this is
229 the most advantageous scenario to utilize opportunistic locking.
231 If the network is slow, unreliable, or a WAN, then do not configure
232 opportunistic locking if there is any chance of multiple users
233 regularly opening the same file.
234 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2928808"></a>Multi-User Databases</h4></div></div><div></div></div><p>
235 Multi-user databases clearly pose a risk due to their very nature -
236 they are typically heavily accessed by numerous users at random
237 intervals. Placing a multi-user database on a share with opportunistic
238 locking enabled will likely result in a locking management bottleneck
239 on the Samba server. Whether the database application is developed
240 in-house or a commercially available product, ensure that the share
241 has opportunistic locking disabled.
242 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2928829"></a>PDM Data Shares</h4></div></div><div></div></div><p>
243 Process Data Management (PDM) applications such as IMAN, Enovia, and
244 Clearcase, are increasing in usage with Windows client platforms, and
245 therefore SMB data stores. PDM applications manage multi-user
246 environments for critical data security and access. The typical PDM
247 environment is usually associated with sophisticated client design
248 applications that will load data locally as demanded. In addition, the
249 PDM application will usually monitor the data-state of each client.
250 In this case, client-side data caching is best left to the local
251 application and PDM server to negotiate and maintain. It is
252 appropriate to eliminate the client OS from any caching tasks, and the
253 server from any oplock management, by disabling opportunistic locking on
255 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2928870"></a>Beware of Force User</h4></div></div><div></div></div><p>
256 Samba includes an <tt class="filename">smb.conf</tt> parameter called <i class="parameter"><tt>force user</tt></i> that changes
257 the user accessing a share from the incoming user to whatever user is
258 defined by the smb.conf variable. If opportunistic locking is enabled
259 on a share, the change in user access causes an oplock break to be sent
260 to the client, even if the user has not explicitly loaded a file. In
261 cases where the network is slow or unreliable, an oplock break can
262 become lost without the user even accessing a file. This can cause
263 apparent performance degradation as the client continually reconnects
264 to overcome the lost oplock break.
266 Avoid the combination of the following:
267 </p><div class="itemizedlist"><ul type="disc"><li><p>
268 <i class="parameter"><tt>force user</tt></i> in the <tt class="filename">smb.conf</tt> share configuration.
270 Slow or unreliable networks
272 Opportunistic Locking Enabled
273 </p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2928948"></a>Advanced Samba Opportunistic Locking Parameters</h4></div></div><div></div></div><p>
274 Samba provides opportunistic locking parameters that allow the
275 administrator to adjust various properties of the oplock mechanism to
276 account for timing and usage levels. These parameters provide good
277 versatility for implementing oplocks in environments where they would
278 likely cause problems. The parameters are:
279 <i class="parameter"><tt>oplock break wait time</tt></i>,
280 <i class="parameter"><tt>oplock contention limit</tt></i>.
282 For most users, administrators, and environments, if these parameters
283 are required, then the better option is to simply turn oplocks off.
284 The samba SWAT help text for both parameters reads "DO NOT CHANGE THIS
285 PARAMETER UNLESS YOU HAVE READ AND UNDERSTOOD THE SAMBA OPLOCK CODE."
287 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2928991"></a>Mission Critical High Availability</h4></div></div><div></div></div><p>
288 In mission critical high availability environments, data integrity is
289 often a priority. Complex and expensive configurations are implemented
290 to ensure that if a client loses connectivity with a file server, a
291 failover replacement will be available immediately to provide
292 continuous data availability.
294 Windows client failover behavior is more at risk of application
295 interruption than other platforms because it is dependant upon an
296 established TCP transport connection. If the connection is interrupted
297 - as in a file server failover - a new session must be established.
298 It is rare for Windows client applications to be coded to recover
299 correctly from a transport connection loss, therefore most applications
300 will experience some sort of interruption - at worst, abort and
303 If a client session has been caching writes and reads locally due to
304 opportunistic locking, it is likely that the data will be lost when the
305 application restarts, or recovers from the TCP interrupt. When the TCP
306 connection drops, the client state is lost. When the file server
307 recovers, an oplock break is not sent to the client. In this case, the
308 work from the prior session is lost. Observing this scenario with
309 oplocks disabled, and the client was writing data to the file server
310 real-time, then the failover will provide the data on disk as it
311 existed at the time of the disconnect.
313 In mission critical high availability environments, careful attention
314 should be given to opportunistic locking. Ideally, comprehensive
315 testing should be done with all affected applications with oplocks
316 enabled and disabled.
317 </p></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2929049"></a>Samba Opportunistic Locking Control</h2></div></div><div></div></div><p>
318 Opportunistic Locking is a unique Windows file locking feature. It is
319 not really file locking, but is included in most discussions of Windows
320 file locking, so is considered a defacto locking feature.
321 Opportunistic Locking is actually part of the Windows client file
322 caching mechanism. It is not a particularly robust or reliable feature
323 when implemented on the variety of customized networks that exist in
324 enterprise computing.
326 Like Windows, Samba implements Opportunistic Locking as a server-side
327 component of the client caching mechanism. Because of the lightweight
328 nature of the Windows feature design, effective configuration of
329 Opportunistic Locking requires a good understanding of its limitations,
330 and then applying that understanding when configuring data access for
331 each particular customized network and client usage state.
333 Opportunistic locking essentially means that the client is allowed to download and cache
334 a file on their hard drive while making changes; if a second client wants to access the
335 file, the first client receives a break and must synchronise the file back to the server.
336 This can give significant performance gains in some cases; some programs insist on
337 synchronising the contents of the entire file back to the server for a single change.
339 Level1 Oplocks (aka just plain "oplocks") is another term for opportunistic locking.
341 Level2 Oplocks provides opportunistic locking for a file that will be treated as
342 <span class="emphasis"><em>read only</em></span>. Typically this is used on files that are read-only or
343 on files that the client has no initial intention to write to at time of opening the file.
345 Kernel Oplocks are essentially a method that allows the Linux kernel to co-exist with
346 Samba's oplocked files, although this has provided better integration of MS Windows network
347 file locking with the under lying OS, SGI IRIX and Linux are the only two OS's that are
348 oplock aware at this time.
350 Unless your system supports kernel oplocks, you should disable oplocks if you are
351 accessing the same files from both Unix/Linux and SMB clients. Regardless, oplocks should
352 always be disabled if you are sharing a database file (e.g., Microsoft Access) between
353 multiple clients, as any break the first client receives will affect synchronisation of
354 the entire file (not just the single record), which will result in a noticeable performance
355 impairment and, more likely, problems accessing the database in the first place. Notably,
356 Microsoft Outlook's personal folders (*.pst) react very badly to oplocks. If in doubt,
357 disable oplocks and tune your system from that point.
359 If client-side caching is desirable and reliable on your network, you will benefit from
360 turning on oplocks. If your network is slow and/or unreliable, or you are sharing your
361 files among other file sharing mechanisms (e.g., NFS) or across a WAN, or multiple people
362 will be accessing the same files frequently, you probably will not benefit from the overhead
363 of your client sending oplock breaks and will instead want to disable oplocks for the share.
365 Another factor to consider is the perceived performance of file access. If oplocks provide no
366 measurable speed benefit on your network, it might not be worth the hassle of dealing with them.
367 </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2929159"></a>Example Configuration</h3></div></div><div></div></div><p>
368 In the following we examine two distinct aspects of Samba locking controls.
369 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2929172"></a>Disabling Oplocks</h4></div></div><div></div></div><p>
370 You can disable oplocks on a per-share basis with the following:
372 </p><pre class="programlisting">
375 level2 oplocks = False
378 The default oplock type is Level1. Level2 Oplocks are enabled on a per-share basis
379 in the <tt class="filename">smb.conf</tt> file.
381 Alternately, you could disable oplocks on a per-file basis within the share:
383 </p><pre class="programlisting">
384 veto oplock files = /*.mdb/*.MDB/*.dbf/*.DBF/
387 If you are experiencing problems with oplocks as apparent from Samba's log entries,
388 you may want to play it safe and disable oplocks and level2 oplocks.
389 </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2929235"></a>Disabling Kernel OpLocks</h4></div></div><div></div></div><p>
390 Kernel OpLocks is an <tt class="filename">smb.conf</tt> parameter that notifies Samba (if
391 the UNIX kernel has the capability to send a Windows client an oplock
392 break) when a UNIX process is attempting to open the file that is
393 cached. This parameter addresses sharing files between UNIX and
394 Windows with Oplocks enabled on the Samba server: the UNIX process
395 can open the file that is Oplocked (cached) by the Windows client and
396 the smbd process will not send an oplock break, which exposes the file
397 to the risk of data corruption. If the UNIX kernel has the ability to
398 send an oplock break, then the kernel oplocks parameter enables Samba
399 to send the oplock break. Kernel oplocks are enabled on a per-server
400 basis in the <tt class="filename">smb.conf</tt> file.
402 </p><pre class="programlisting">
406 The default is "no".
408 Veto OpLocks is an <tt class="filename">smb.conf</tt> parameter that identifies specific files for
409 which Oplocks are disabled. When a Windows client opens a file that
410 has been configured for veto oplocks, the client will not be granted
411 the oplock, and all operations will be executed on the original file on
412 disk instead of a client-cached file copy. By explicitly identifying
413 files that are shared with UNIX processes, and disabling oplocks for
414 those files, the server-wide Oplock configuration can be enabled to
415 allow Windows clients to utilize the performance benefit of file
416 caching without the risk of data corruption. Veto Oplocks can be
417 enabled on a per-share basis, or globally for the entire server, in the
418 <tt class="filename">smb.conf</tt> file:
420 </p><pre class="programlisting"><font color="red"><title>Example Veto OpLock Settings</title></font>
422 veto oplock files = /filename.htm/*.txt/
425 veto oplock files = /*.exe/filename.ext/
428 <span class="emphasis"><em>Oplock break wait time</em></span> is an <tt class="filename">smb.conf</tt> parameter that adjusts the time
429 interval for Samba to reply to an oplock break request. Samba
430 recommends "DO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ AND
431 UNDERSTOOD THE SAMBA OPLOCK CODE." Oplock Break Wait Time can only be
432 configured globally in the <tt class="filename">smb.conf</tt> file:
434 </p><pre class="programlisting">
436 oplock break wait time = 0 (default)
439 <span class="emphasis"><em>Oplock break contention limit</em></span> is an <tt class="filename">smb.conf</tt> parameter that limits the
440 response of the Samba server to grant an oplock if the configured
441 number of contending clients reaches the limit specified by the
442 parameter. Samba recommends "DO NOT CHANGE THIS PARAMETER UNLESS YOU
443 HAVE READ AND UNDERSTOOD THE SAMBA OPLOCK CODE." Oplock Break
444 Contention Limit can be enable on a per-share basis, or globally for
445 the entire server, in the <tt class="filename">smb.conf</tt> file:
447 </p><pre class="programlisting">
449 oplock break contention limit = 2 (default)
452 oplock break contention limit = 2 (default)
454 </p></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2929419"></a>MS Windows Opportunistic Locking and Caching Controls</h2></div></div><div></div></div><p>
455 There is a known issue when running applications (like Norton Anti-Virus) on a Windows 2000/ XP
456 workstation computer that can affect any application attempting to access shared database files
457 across a network. This is a result of a default setting configured in the Windows 2000/XP
458 operating system known as <span class="emphasis"><em>Opportunistic Locking</em></span>. When a workstation
459 attempts to access shared data files located on another Windows 2000/XP computer,
460 the Windows 2000/XP operating system will attempt to increase performance by locking the
461 files and caching information locally. When this occurs, the application is unable to
462 properly function, which results in an <span class="errorname">Access Denied</span>
463 error message being displayed during network operations.
465 All Windows operating systems in the NT family that act as database servers for data files
466 (meaning that data files are stored there and accessed by other Windows PCs) may need to
467 have opportunistic locking disabled in order to minimize the risk of data file corruption.
468 This includes Windows 9x/Me, Windows NT, Windows 200x and Windows XP.
470 If you are using a Windows NT family workstation in place of a server, you must also
471 disable opportunistic locking (oplocks) on that workstation. For example, if you use a
472 PC with the Windows NT Workstation operating system instead of Windows NT Server, and you
473 have data files located on it that are accessed from other Windows PCs, you may need to
474 disable oplocks on that system.
476 The major difference is the location in the Windows registry where the values for disabling
477 oplocks are entered. Instead of the LanManServer location, the LanManWorkstation location
480 You can verify (or change or add, if necessary) this Registry value using the Windows
481 Registry Editor. When you change this registry value, you will have to reboot the PC
482 to ensure that the new setting goes into effect.
484 The location of the client registry entry for opportunistic locking has changed in
485 Windows 2000 from the earlier location in Microsoft Windows NT.
486 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
487 Windows 2000 will still respect the EnableOplocks registry value used to disable oplocks
488 in earlier versions of Windows.
490 You can also deny the granting of opportunistic locks by changing the following registry entries:
492 </p><pre class="programlisting">
493 HKEY_LOCAL_MACHINE\System\
494 CurrentControlSet\Services\MRXSmb\Parameters\
496 OplocksDisabled REG_DWORD 0 or 1
497 Default: 0 (not disabled)
499 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
500 The OplocksDisabled registry value configures Windows clients to either request or not
501 request opportunistic locks on a remote file. To disable oplocks, the value of
502 OplocksDisabled must be set to 1.
504 </p><pre class="programlisting">
505 HKEY_LOCAL_MACHINE\System\
506 CurrentControlSet\Services\LanmanServer\Parameters
508 EnableOplocks REG_DWORD 0 or 1
509 Default: 1 (Enabled by Default)
511 EnableOpLockForceClose REG_DWORD 0 or 1
512 Default: 0 (Disabled by Default)
514 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
515 The EnableOplocks value configures Windows-based servers (including Workstations sharing
516 files) to allow or deny opportunistic locks on local files.
518 To force closure of open oplocks on close or program exit EnableOpLockForceClose must be set to 1.
520 An illustration of how level II oplocks work:
521 </p><div class="itemizedlist"><ul type="disc"><li><p>
522 Station 1 opens the file, requesting oplock.
524 Since no other station has the file open, the server grants station 1 exclusive oplock.
526 Station 2 opens the file, requesting oplock.
528 Since station 1 has not yet written to the file, the server asks station 1 to Break
531 Station 1 complies by flushing locally buffered lock information to the server.
533 Station 1 informs the server that it has Broken to Level II Oplock (alternatively,
534 station 1 could have closed the file).
536 The server responds to station 2's open request, granting it level II oplock.
537 Other stations can likewise open the file and obtain level II oplock.
539 Station 2 (or any station that has the file open) sends a write request SMB.
540 The server returns the write response.
542 The server asks all stations that have the file open to Break to None, meaning no
543 station holds any oplock on the file. Because the workstations can have no cached
544 writes or locks at this point, they need not respond to the break-to-none advisory;
545 all they need do is invalidate locally cashed read-ahead data.
546 </p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2929649"></a>Workstation Service Entries</h3></div></div><div></div></div><pre class="programlisting">
547 \HKEY_LOCAL_MACHINE\System\
548 CurrentControlSet\Services\LanmanWorkstation\Parameters
550 UseOpportunisticLocking REG_DWORD 0 or 1
553 Indicates whether the redirector should use opportunistic-locking (oplock) performance
554 enhancement. This parameter should be disabled only to isolate problems.
555 </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2929676"></a>Server Service Entries</h3></div></div><div></div></div><pre class="programlisting">
556 \HKEY_LOCAL_MACHINE\System\
557 CurrentControlSet\Services\LanmanServer\Parameters
559 EnableOplocks REG_DWORD 0 or 1
562 Specifies whether the server allows clients to use oplocks on files. Oplocks are a
563 significant performance enhancement, but have the potential to cause lost cached
564 data on some networks, particularly wide-area networks.
565 </p><pre class="programlisting">
566 MinLinkThroughput REG_DWORD 0 to infinite bytes per second
569 Specifies the minimum link throughput allowed by the server before it disables
570 raw and opportunistic locks for this connection.
571 </p><pre class="programlisting">
572 MaxLinkDelay REG_DWORD 0 to 100,000 seconds
575 Specifies the maximum time allowed for a link delay. If delays exceed this number,
576 the server disables raw I/O and opportunistic locking for this connection.
577 </p><pre class="programlisting">
578 OplockBreakWait REG_DWORD 10 to 180 seconds
581 Specifies the time that the server waits for a client to respond to an oplock break
582 request. Smaller values can allow detection of crashed clients more quickly but can
583 potentially cause loss of cached data.
584 </p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2929755"></a>Persistent Data Corruption</h2></div></div><div></div></div><p>
585 If you have applied all of the settings discussed in this paper but data corruption problems
586 and other symptoms persist, here are some additional things to check out:
588 We have credible reports from developers that faulty network hardware, such as a single
589 faulty network card, can cause symptoms similar to read caching and data corruption.
590 If you see persistent data corruption even after repeated reindexing, you may have to
591 rebuild the data files in question. This involves creating a new data file with the
592 same definition as the file to be rebuilt and transferring the data from the old file
593 to the new one. There are several known methods for doing this that can be found in
595 </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2929785"></a>Common Errors</h2></div></div><div></div></div><p>
596 In some sites locking problems surface as soon as a server is installed, in other sites
597 locking problems may not surface for a long time. Almost without exception, when a locking
598 problem does surface it will cause embarrassment and potential data corruption.
600 Over the past few years there have been a number of complaints on the samba mailing lists
601 that have claimed that samba caused data corruption. Three causes have been identified
603 </p><div class="itemizedlist"><ul type="disc"><li><p>
604 Incorrect configuration of opportunistic locking (incompatible with the application
605 being used. This is a VERY common problem even where MS Windows NT4 or MS Windows 200x
606 based servers were in use. It is imperative that the software application vendors'
607 instructions for configuration of file locking should be followed. If in doubt,
608 disable oplocks on both the server and the client. Disabling of all forms of file
609 caching on the MS Windows client may be necessary also.
611 Defective network cards, cables, or HUBs / Switched. This is generally a more
612 prevalent factor with low cost networking hardware, though occasionally there
613 have been problems with incompatibilities in more up market hardware also.
615 There have been some random reports of samba log files being written over data
616 files. This has been reported by very few sites (about 5 in the past 3 years)
617 and all attempts to reproduce the problem have failed. The Samba-Team has been
618 unable to catch this happening and thus has NOT been able to isolate any particular
619 cause. Considering the millions of systems that use samba, for the sites that have
620 been affected by this as well as for the Samba-Team this is a frustrating and
621 a vexing challenge. If you see this type of thing happening please create a bug
622 report on https://bugzilla.samba.org without delay. Make sure that you give as much
623 information as you possibly can to help isolate the cause and to allow reproduction
624 of the problem (an essential step in problem isolation and correction).
625 </p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2929859"></a>locking.tdb error messages</h3></div></div><div></div></div><p>
626 </p><pre class="screen">
627 > We are seeing lots of errors in the samba logs like:
629 > tdb(/usr/local/samba_2.2.7/var/locks/locking.tdb): rec_read bad magic
630 > 0x4d6f4b61 at offset=36116
632 > What do these mean?
635 Corrupted tdb. Stop all instances of smbd, delete locking.tdb, restart smbd.
636 </p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2929890"></a>Additional Reading</h2></div></div><div></div></div><p>
637 You may want to check for an updated version of this white paper on our Web site from
638 time to time. Many of our white papers are updated as information changes. For those papers,
639 the Last Edited date is always at the top of the paper.
641 Section of the Microsoft MSDN Library on opportunistic locking:
643 Opportunistic Locks, Microsoft Developer Network (MSDN), Windows Development >
644 Windows Base Services > Files and I/O > SDK Documentation > File Storage > File Systems
645 > About File Systems > Opportunistic Locks, Microsoft Corporation.
646 <a href="http://msdn.microsoft.com/library/en-us/fileio/storage_5yk3.asp" target="_top">http://msdn.microsoft.com/library/en-us/fileio/storage_5yk3.asp</a>
648 Microsoft Knowledge Base Article Q224992 "Maintaining Transactional Integrity with OPLOCKS",
649 Microsoft Corporation, April 1999, <a href="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q224992" target="_top">http://support.microsoft.com/default.aspx?scid=kb;en-us;Q224992</a>.
651 Microsoft Knowledge Base Article Q296264 "Configuring Opportunistic Locking in Windows 2000",
652 Microsoft Corporation, April 2001, <a href="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q296264" target="_top">http://support.microsoft.com/default.aspx?scid=kb;en-us;Q296264</a>.
654 Microsoft Knowledge Base Article Q129202 "PC Ext: Explanation of Opportunistic Locking on Windows NT",
655 Microsoft Corporation, April 1995, <a href="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q129202" target="_top">http://support.microsoft.com/default.aspx?scid=kb;en-us;Q129202</a>.
656 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="AccessControls.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="optional.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="securing-samba.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 13. File, Directory and Share Access Controls </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 15. Securing Samba</td></tr></table></div></body></html>
git.samba.org / ira / wip.git / blob