1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�17.�File and Record Locking</title><link rel="stylesheet" href="../samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><link rel="home" href="index.html" title="The Official Samba 3.5.x HOWTO and Reference Guide"><link rel="up" href="optional.html" title="Part�III.�Advanced Configuration"><link rel="prev" href="AccessControls.html" title="Chapter�16.�File, Directory, and Share Access Controls"><link rel="next" href="securing-samba.html" title="Chapter�18.�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�17.�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�17.�File and Record Locking</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Jeremy</span> <span class="orgname">Samba Team</span> <span class="surname">Allison</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><code class="email"><<a class="email" href="mailto:jra@samba.org">jra@samba.org</a>></code></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Jelmer</span> <span class="othername">R.</span> <span class="orgname">The Samba Team</span> <span class="surname">Vernooij</span></h3><div class="affiliation"><span class="orgname">The Samba Team<br></span><div class="address"><p><code class="email"><<a class="email" href="mailto:jelmer@samba.org">jelmer@samba.org</a>></code></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">John</span> <span class="othername">H.</span> <span class="orgname">Samba Team</span> <span class="surname">Terpstra</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><code class="email"><<a class="email" href="mailto:jht@samba.org">jht@samba.org</a>></code></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Eric</span> <span class="orgname">HP Oplocks Usage Recommendations Whitepaper</span> <span class="surname">Roseme</span></h3><div class="affiliation"><span class="orgname">HP Oplocks Usage Recommendations Whitepaper<br></span><div class="address"><p><code class="email"><<a class="email" href="mailto:eric.roseme@hp.com">eric.roseme@hp.com</a>></code></p></div></div></div></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="locking.html#id2615570">Features and Benefits</a></span></dt><dt><span class="sect1"><a href="locking.html#id2615667">Discussion</a></span></dt><dd><dl><dt><span class="sect2"><a href="locking.html#id2615926">Opportunistic Locking Overview</a></span></dt></dl></dd><dt><span class="sect1"><a href="locking.html#id2616903">Samba Oplocks Control</a></span></dt><dd><dl><dt><span class="sect2"><a href="locking.html#id2616998">Example Configuration</a></span></dt></dl></dd><dt><span class="sect1"><a href="locking.html#id2617411">MS Windows Oplocks and Caching Controls</a></span></dt><dd><dl><dt><span class="sect2"><a href="locking.html#id2617598">Workstation Service Entries</a></span></dt><dt><span class="sect2"><a href="locking.html#id2617620">Server Service Entries</a></span></dt></dl></dd><dt><span class="sect1"><a href="locking.html#id2617686">Persistent Data Corruption</a></span></dt><dt><span class="sect1"><a href="locking.html#id2617712">Common Errors</a></span></dt><dd><dl><dt><span class="sect2"><a href="locking.html#id2617779">locking.tdb Error Messages</a></span></dt><dt><span class="sect2"><a href="locking.html#id2617810">Problems Saving Files in MS Office on Windows XP</a></span></dt><dt><span class="sect2"><a href="locking.html#id2617834">Long Delays Deleting Files over Network with XP SP1</a></span></dt></dl></dd><dt><span class="sect1"><a href="locking.html#id2617866">Additional Reading</a></span></dt></dl></div><p> 2<a class="indexterm" name="id2615560"></a> 3One area that causes trouble for many network administrators is locking. 4The extent of the problem is readily evident from searches over the Internet. 5</p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2615570"></a>Features and Benefits</h2></div></div></div><p> 6<a class="indexterm" name="id2615578"></a> 7Samba provides all the same locking semantics that MS Windows clients expect 8and that MS Windows NT4/200x servers also provide. 9</p><p> 10<a class="indexterm" name="id2615591"></a> 11The term <span class="emphasis"><em>locking</em></span> has exceptionally broad meaning and covers 12a range of functions that are all categorized under this one term. 13</p><p> 14<a class="indexterm" name="id2615607"></a> 15<a class="indexterm" name="id2615614"></a> 16<a class="indexterm" name="id2615621"></a> 17Opportunistic locking is a desirable feature when it can enhance the 18perceived performance of applications on a networked client. However, the 19opportunistic locking protocol is not robust and therefore can 20encounter problems when invoked beyond a simplistic configuration or 21on extended slow or faulty networks. In these cases, operating 22system management of opportunistic locking and/or recovering from 23repetitive errors can offset the perceived performance advantage that 24it is intended to provide. 25</p><p> 26<a class="indexterm" name="id2615639"></a> 27The MS Windows network administrator needs to be aware that file and record 28locking semantics (behavior) can be controlled either in Samba or by way of registry 29settings on the MS Windows client. 30</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> 31<a class="indexterm" name="id2615655"></a> 32Sometimes it is necessary to disable locking control settings on the Samba 33server as well as on each MS Windows client! 34</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2615667"></a>Discussion</h2></div></div></div><p> 35<a class="indexterm" name="id2615675"></a> 36<a class="indexterm" name="id2615682"></a> 37There are two types of locking that need to be performed by an SMB server. 38The first is <span class="emphasis"><em>record locking</em></span> that allows a client to lock 39a range of bytes in an open file. The second is the <span class="emphasis"><em>deny modes</em></span> 40that are specified when a file is open. 41</p><p> 42<a class="indexterm" name="id2615703"></a> 43<a class="indexterm" name="id2615710"></a> 44<a class="indexterm" name="id2615717"></a> 45<a class="indexterm" name="id2615724"></a> 46<a class="indexterm" name="id2615730"></a> 47Record locking semantics under UNIX are very different from record locking under 48Windows. Versions of Samba before 2.2 have tried to use the native fcntl() UNIX 49system call to implement proper record locking between different Samba clients. 50This cannot be fully correct for several reasons. The simplest is 51that a Windows client is allowed to lock a byte range up to 2^32 or 2^64, 52depending on the client OS. The UNIX locking only supports byte ranges up to 2^31. 53So it is not possible to correctly satisfy a lock request above 2^31. There are 54many more differences, too many to be listed here. 55</p><p> 56<a class="indexterm" name="id2615751"></a> 57<a class="indexterm" name="id2615758"></a> 58Samba 2.2 and above implement record locking completely independently of the 59underlying UNIX system. If a byte-range lock that the client requests happens 60to fall into the range of 0 to 2^31, Samba hands this request down to the UNIX system. 61No other locks can be seen by UNIX, anyway. 62</p><p> 63<a class="indexterm" name="id2615773"></a> 64<a class="indexterm" name="id2615780"></a> 65Strictly speaking, an SMB server should check for locks before every read and write call on 66a file. Unfortunately, with the way fcntl() works, this can be slow and may overstress 67the <code class="literal">rpc.lockd</code>. This is almost always unnecessary because clients are 68independently supposed to make locking calls before reads and writes if locking is 69important to them. By default, Samba only makes locking calls when explicitly asked 70to by a client, but if you set <a class="link" href="smb.conf.5.html#STRICTLOCKING" target="_top">strict locking = yes</a>, it 71will make lock checking calls on <span class="emphasis"><em>every</em></span> read and write call. 72</p><p> 73<a class="indexterm" name="id2615821"></a> 74You can also disable byte-range locking completely by using 75<a class="link" href="smb.conf.5.html#LOCKING" target="_top">locking = no</a>. 76This is useful for those shares that do not support locking or do not need it 77(such as CD-ROMs). In this case, Samba fakes the return codes of locking calls to 78tell clients that everything is okay. 79</p><p> 80<a class="indexterm" name="id2615848"></a> 81<a class="indexterm" name="id2615855"></a> 82<a class="indexterm" name="id2615862"></a> 83<a class="indexterm" name="id2615868"></a> 84<a class="indexterm" name="id2615875"></a> 85<a class="indexterm" name="id2615882"></a> 86<a class="indexterm" name="id2615889"></a> 87The second class of locking is the <span class="emphasis"><em>deny modes</em></span>. These 88are set by an application when it opens a file to determine what types of 89access should be allowed simultaneously with its open. A client may ask for 90<code class="constant">DENY_NONE</code>, <code class="constant">DENY_READ</code>, 91<code class="constant">DENY_WRITE</code>, or <code class="constant">DENY_ALL</code>. There are also special compatibility 92modes called <code class="constant">DENY_FCB</code> and <code class="constant">DENY_DOS</code>. 93</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2615926"></a>Opportunistic Locking Overview</h3></div></div></div><p> 94<a class="indexterm" name="id2615934"></a> 95<a class="indexterm" name="id2615941"></a> 96<a class="indexterm" name="id2615948"></a> 97Opportunistic locking (oplocks) is invoked by the Windows file system 98(as opposed to an API) via registry entries (on the server and the client) 99for the purpose of enhancing network performance when accessing a file 100residing on a server. Performance is enhanced by caching the file 101locally on the client that allows the following: 102</p><div class="variablelist"><dl><dt><span class="term">Read-ahead:</span></dt><dd><p> 103<a class="indexterm" name="id2615971"></a> 104 The client reads the local copy of the file, eliminating network latency. 105 </p></dd><dt><span class="term">Write caching:</span></dt><dd><p> 106<a class="indexterm" name="id2615989"></a> 107 The client writes to the local copy of the file, eliminating network latency. 108 </p></dd><dt><span class="term">Lock caching:</span></dt><dd><p> 109<a class="indexterm" name="id2616008"></a> 110 The client caches application locks locally, eliminating network latency. 111 </p></dd></dl></div><p> 112<a class="indexterm" name="id2616022"></a> 113<a class="indexterm" name="id2616029"></a> 114<a class="indexterm" name="id2616035"></a> 115The performance enhancement of oplocks is due to the opportunity of 116exclusive access to the file even if it is opened with deny-none 117because Windows monitors the file's status for concurrent access from 118other processes. 119</p><div class="variablelist"><p class="title"><b>Windows Defines Four Kinds of Oplocks:</b></p><dl><dt><span class="term">Level1 Oplock</span></dt><dd><p> 120<a class="indexterm" name="id2616067"></a> 121<a class="indexterm" name="id2616073"></a> 122<a class="indexterm" name="id2616080"></a> 123<a class="indexterm" name="id2616087"></a> 124 The redirector sees that the file was opened with deny 125 none (allowing concurrent access), verifies that no 126 other process is accessing the file, checks that 127 oplocks are enabled, then grants deny-all/read-write/exclusive 128 access to the file. The client now performs 129 operations on the cached local file. 130 </p><p> 131<a class="indexterm" name="id2616102"></a> 132<a class="indexterm" name="id2616109"></a> 133<a class="indexterm" name="id2616116"></a> 134<a class="indexterm" name="id2616123"></a> 135 If a second process attempts to open the file, the open 136 is deferred while the redirector "breaks" the original 137 oplock. The oplock break signals the caching client to 138 write the local file back to the server, flush the 139 local locks, and discard read-ahead data. The break is 140 then complete, the deferred open is granted, and the 141 multiple processes can enjoy concurrent file access as 142 dictated by mandatory or byte-range locking options. 143 However, if the original opening process opened the 144 file with a share mode other than deny-none, then the 145 second process is granted limited or no access, despite 146 the oplock break. 147 </p></dd><dt><span class="term">Level2 Oplock</span></dt><dd><p> 148<a class="indexterm" name="id2616151"></a> 149<a class="indexterm" name="id2616158"></a> 150<a class="indexterm" name="id2616165"></a> 151 Performs like a Level1 oplock, except caching is only 152 operative for reads. All other operations are performed 153 on the server disk copy of the file. 154 </p></dd><dt><span class="term">Filter Oplock</span></dt><dd><p> 155<a class="indexterm" name="id2616185"></a> 156 Does not allow write or delete file access. 157 </p></dd><dt><span class="term">Batch Oplock</span></dt><dd><p> 158<a class="indexterm" name="id2616204"></a> 159 Manipulates file openings and closings and allows caching 160 of file attributes. 161 </p></dd></dl></div><p> 162<a class="indexterm" name="id2616218"></a> 163An important detail is that oplocks are invoked by the file system, not 164an application API. Therefore, an application can close an oplocked 165file, but the file system does not relinquish the oplock. When the 166oplock break is issued, the file system then simply closes the file in 167preparation for the subsequent open by the second process. 168</p><p> 169<a class="indexterm" name="id2616234"></a> 170<a class="indexterm" name="id2616241"></a> 171<a class="indexterm" name="id2616248"></a> 172<a class="indexterm" name="id2616255"></a> 173<span class="emphasis"><em>Opportunistic locking</em></span> is actually an improper name for this feature. 174The true benefit of this feature is client-side data caching, and 175oplocks is merely a notification mechanism for writing data back to the 176networked storage disk. The limitation of oplocks is the 177reliability of the mechanism to process an oplock break (notification) 178between the server and the caching client. If this exchange is faulty 179(usually due to timing out for any number of reasons), then the 180client-side caching benefit is negated. 181</p><p> 182<a class="indexterm" name="id2616277"></a> 183The actual decision that a user or administrator should consider is 184whether it is sensible to share among multiple users data that will 185be cached locally on a client. In many cases the answer is no. 186Deciding when to cache or not cache data is the real question, and thus 187oplocks should be treated as a toggle for client-side 188caching. Turn it “<span class="quote">on</span>” when client-side caching is desirable and 189reliable. Turn it “<span class="quote">off</span>” when client-side caching is redundant, 190unreliable, or counterproductive. 191</p><p> 192<a class="indexterm" name="id2616302"></a> 193Oplocks is by default set to “<span class="quote">on</span>” by Samba on all 194configured shares, so careful attention should be given to each case to 195determine if the potential benefit is worth the potential for delays. 196The following recommendations will help to characterize the environment 197where oplocks may be effectively configured. 198</p><p> 199<a class="indexterm" name="id2616320"></a> 200<a class="indexterm" name="id2616327"></a> 201Windows oplocks is a lightweight performance-enhancing 202feature. It is not a robust and reliable protocol. Every 203implementation of oplocks should be evaluated as a 204trade-off between perceived performance and reliability. Reliability 205decreases as each successive rule above is not enforced. Consider a 206share with oplocks enabled, over a wide-area network, to a client on a 207South Pacific atoll, on a high-availability server, serving a 208mission-critical multiuser corporate database during a tropical 209storm. This configuration will likely encounter problems with oplocks. 210</p><p> 211<a class="indexterm" name="id2616347"></a> 212Oplocks can be beneficial to perceived client performance when treated 213as a configuration toggle for client-side data caching. If the data 214caching is likely to be interrupted, then oplock usage should be 215reviewed. Samba enables oplocks by default on all 216shares. Careful attention should be given to the client usage of 217shared data on the server, the server network reliability, and the 218oplocks configuration of each share. 219In mission-critical, high-availability environments, data integrity is 220often a priority. Complex and expensive configurations are implemented 221to ensure that if a client loses connectivity with a file server, a 222failover replacement will be available immediately to provide 223continuous data availability. 224</p><p> 225<a class="indexterm" name="id2616369"></a> 226<a class="indexterm" name="id2616376"></a> 227Windows client failover behavior is more at risk of application 228interruption than other platforms because it is dependent upon an 229established TCP transport connection. If the connection is interrupted 230 as in a file server failover a new session must be established. 231It is rare for Windows client applications to be coded to recover 232correctly from a transport connection loss; therefore, most applications 233will experience some sort of interruption at worst, abort and 234require restarting. 235</p><p> 236<a class="indexterm" name="id2616404"></a> 237<a class="indexterm" name="id2616410"></a> 238<a class="indexterm" name="id2616416"></a> 239If a client session has been caching writes and reads locally due to 240oplocks, it is likely that the data will be lost when the 241application restarts or recovers from the TCP interrupt. When the TCP 242connection drops, the client state is lost. When the file server 243recovers, an oplock break is not sent to the client. In this case, the 244work from the prior session is lost. Observing this scenario with 245oplocks disabled and with the client writing data to the file server 246real-time, the failover will provide the data on disk as it 247existed at the time of the disconnect. 248</p><p> 249In mission-critical, high-availability environments, careful attention 250should be given to oplocks. Ideally, comprehensive 251testing should be done with all affected applications with oplocks 252enabled and disabled. 253</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2616441"></a>Exclusively Accessed Shares</h4></div></div></div><p> 254Oplocks is most effective when it is confined to shares 255that are exclusively accessed by a single user, or by only one user at 256a time. Because the true value of oplocks is the local 257client caching of data, any operation that interrupts the caching 258mechanism will cause a delay. 259</p><p> 260Home directories are the most obvious examples of where the performance 261benefit of oplocks can be safely realized. 262</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2616461"></a>Multiple-Accessed Shares or Files</h4></div></div></div><p> 263As each additional user accesses a file in a share with oplocks 264enabled, the potential for delays and resulting perceived poor 265performance increases. When multiple users are accessing a file on a 266share that has oplocks enabled, the management impact of sending and 267receiving oplock breaks and the resulting latency while other clients 268wait for the caching client to flush data offset the performance gains 269of the caching user. 270</p><p> 271As each additional client attempts to access a file with oplocks set, 272the potential performance improvement is negated and eventually results 273in a performance bottleneck. 274</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2616485"></a>UNIX or NFS Client-Accessed Files</h4></div></div></div><p> 275<a class="indexterm" name="id2616493"></a> 276<a class="indexterm" name="id2616500"></a> 277Local UNIX and NFS clients access files without a mandatory 278file-locking mechanism. Thus, these client platforms are incapable of 279initiating an oplock break request from the server to a Windows client 280that has a file cached. Local UNIX or NFS file access can therefore 281write to a file that has been cached by a Windows client, which 282exposes the file to likely data corruption. 283</p><p> 284If files are shared between Windows clients and either local UNIX 285or NFS users, turn oplocks off. 286</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2616521"></a>Slow and/or Unreliable Networks</h4></div></div></div><p> 287<a class="indexterm" name="id2616529"></a> 288<a class="indexterm" name="id2616536"></a> 289<a class="indexterm" name="id2616542"></a> 290The biggest potential performance improvement for oplocks 291occurs when the client-side caching of reads and writes delivers the 292most differential over sending those reads and writes over the wire. 293This is most likely to occur when the network is extremely slow, 294congested, or distributed (as in a WAN). However, network latency also 295has a high impact on the reliability of the oplock break 296mechanism, and thus increases the likelihood of encountering oplock 297problems that more than offset the potential perceived performance 298gain. Of course, if an oplock break never has to be sent, then this is 299the most advantageous scenario in which to utilize oplocks. 300</p><p> 301If the network is slow, unreliable, or a WAN, then do not configure 302oplocks if there is any chance of multiple users 303regularly opening the same file. 304</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2616568"></a>Multiuser Databases</h4></div></div></div><p> 305<a class="indexterm" name="id2616576"></a> 306<a class="indexterm" name="id2616583"></a> 307<a class="indexterm" name="id2616590"></a> 308Multiuser databases clearly pose a risk due to their very nature they are typically heavily 309accessed by numerous users at random intervals. Placing a multiuser database on a share with oplocks enabled 310will likely result in a locking management bottleneck on the Samba server. Whether the database application is 311developed in-house or a commercially available product, ensure that the share has oplocks disabled. 312</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2616609"></a>PDM Data Shares</h4></div></div></div><p> 313<a class="indexterm" name="id2616617"></a> 314<a class="indexterm" name="id2616624"></a> 315<a class="indexterm" name="id2616631"></a> 316<a class="indexterm" name="id2616638"></a> 317<a class="indexterm" name="id2616645"></a> 318Process data management (PDM) applications such as IMAN, Enovia, and Clearcase are increasing in usage with 319Windows client platforms and therefore with SMB datastores. PDM applications manage multiuser environments for 320critical data security and access. The typical PDM environment is usually associated with sophisticated client 321design applications that will load data locally as demanded. In addition, the PDM application will usually 322monitor the data state of each client. In this case, client-side data caching is best left to the local 323application and PDM server to negotiate and maintain. It is appropriate to eliminate the client OS from any 324caching tasks, and the server from any oplocks management, by disabling oplocks on the share. 325</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2616679"></a>Beware of Force User</h4></div></div></div><p> 326<a class="indexterm" name="id2616687"></a> 327Samba includes an <code class="filename">smb.conf</code> parameter called <a class="link" href="smb.conf.5.html#FORCEUSER" target="_top">force user</a> that changes the user 328accessing a share from the incoming user to whatever user is defined by the <code class="filename">smb.conf</code> variable. If oplocks is 329enabled on a share, the change in user access causes an oplock break to be sent to the client, even if the 330user has not explicitly loaded a file. In cases where the network is slow or unreliable, an oplock break can 331become lost without the user even accessing a file. This can cause apparent performance degradation as the 332client continually reconnects to overcome the lost oplock break. 333</p><p> 334Avoid the combination of the following: 335</p><div class="itemizedlist"><ul type="disc"><li><p> 336 <a class="link" href="smb.conf.5.html#FORCEUSER" target="_top">force user</a> in the <code class="filename">smb.conf</code> share configuration. 337 </p></li><li><p> 338 Slow or unreliable networks. 339 </p></li><li><p> 340 Oplocks enabled. 341 </p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2616767"></a>Advanced Samba Oplocks Parameters</h4></div></div></div><p> 342<a class="indexterm" name="id2616775"></a> 343<a class="indexterm" name="id2616782"></a> 344<a class="indexterm" name="id2616789"></a> 345Samba provides oplock parameters that allow the 346administrator to adjust various properties of the oplock mechanism to 347account for timing and usage levels. These parameters provide good 348versatility for implementing oplocks in environments where they would 349likely cause problems. The parameters are 350<a class="link" href="smb.conf.5.html#OPLOCKBREAKWAITTIME" target="_top">oplock break wait time</a>, and 351<a class="link" href="smb.conf.5.html#OPLOCKCONTENTIONLIMIT" target="_top">oplock contention limit</a>. 352</p><p> 353<a class="indexterm" name="id2616828"></a> 354For most users, administrators, and environments, if these parameters 355are required, then the better option is simply to turn oplocks off. 356The Samba SWAT help text for both parameters reads: “<span class="quote">Do not change 357this parameter unless you have read and understood the Samba oplock code.</span>” 358This is good advice. 359</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2616846"></a>Mission-Critical, High-Availability</h4></div></div></div><p> 360In mission-critical, high-availability environments, data integrity is 361often a priority. Complex and expensive configurations are implemented 362to ensure that if a client loses connectivity with a file server, a 363failover replacement will be available immediately to provide 364continuous data availability. 365</p><p> 366Windows client failover behavior is more at risk of application 367interruption than other platforms because it is dependent upon an 368established TCP transport connection. If the connection is interrupted 369 as in a file server failover a new session must be established. 370It is rare for Windows client applications to be coded to recover 371correctly from a transport connection loss; therefore, most applications 372will experience some sort of interruption at worst, abort and 373require restarting. 374</p><p> 375If a client session has been caching writes and reads locally due to 376oplocks, it is likely that the data will be lost when the 377application restarts or recovers from the TCP interrupt. When the TCP 378connection drops, the client state is lost. When the file server 379recovers, an oplock break is not sent to the client. In this case, the 380work from the prior session is lost. Observing this scenario with 381oplocks disabled, if the client was writing data to the file server 382real-time, then the failover will provide the data on disk as it 383existed at the time of the disconnect. 384</p><p> 385In mission-critical, high-availability environments, careful attention 386should be given to oplocks. Ideally, comprehensive 387testing should be done with all affected applications with oplocks 388enabled and disabled. 389</p></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2616903"></a>Samba Oplocks Control</h2></div></div></div><p> 390Oplocks is a unique Windows file locking feature. It is 391not really file locking, but is included in most discussions of Windows 392file locking, so is considered a de facto locking feature. 393Oplocks is actually part of the Windows client file 394caching mechanism. It is not a particularly robust or reliable feature 395when implemented on the variety of customized networks that exist in 396enterprise computing. 397</p><p> 398Like Windows, Samba implements oplocks as a server-side 399component of the client caching mechanism. Because of the lightweight 400nature of the Windows feature design, effective configuration of 401oplocks requires a good understanding of its limitations, 402and then applying that understanding when configuring data access for 403each particular customized network and client usage state. 404</p><p> 405Oplocks essentially means that the client is allowed to download and cache 406a file on its hard drive while making changes; if a second client wants to access the 407file, the first client receives a break and must synchronize the file back to the server. 408This can give significant performance gains in some cases; some programs insist on 409synchronizing the contents of the entire file back to the server for a single change. 410</p><p> 411Level1 Oplocks (also known as just plain “<span class="quote">oplocks</span>”) is another term for opportunistic locking. 412</p><p> 413Level2 Oplocks provides opportunistic locking for a file that will be treated as 414<span class="emphasis"><em>read only</em></span>. Typically this is used on files that are read-only or 415on files that the client has no initial intention to write to at time of opening the file. 416</p><p> 417Kernel Oplocks are essentially a method that allows the Linux kernel to co-exist with 418Samba's oplocked files, although this has provided better integration of MS Windows network 419file locking with the underlying OS. SGI IRIX and Linux are the only two OSs that are 420oplock-aware at this time. 421</p><p> 422Unless your system supports kernel oplocks, you should disable oplocks if you are 423accessing the same files from both UNIX/Linux and SMB clients. Regardless, oplocks should 424always be disabled if you are sharing a database file (e.g., Microsoft Access) between 425multiple clients, because any break the first client receives will affect synchronization of 426the entire file (not just the single record), which will result in a noticeable performance 427impairment and, more likely, problems accessing the database in the first place. Notably, 428Microsoft Outlook's personal folders (*.pst) react quite badly to oplocks. If in doubt, 429disable oplocks and tune your system from that point. 430</p><p> 431If client-side caching is desirable and reliable on your network, you will benefit from 432turning on oplocks. If your network is slow and/or unreliable, or you are sharing your 433files among other file sharing mechanisms (e.g., NFS) or across a WAN, or multiple people 434will be accessing the same files frequently, you probably will not benefit from the overhead 435of your client sending oplock breaks and will instead want to disable oplocks for the share. 436</p><p> 437Another factor to consider is the perceived performance of file access. If oplocks provide no 438measurable speed benefit on your network, it might not be worth the hassle of dealing with them. 439</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2616998"></a>Example Configuration</h3></div></div></div><p> 440In the following section we examine two distinct aspects of Samba locking controls. 441</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2617008"></a>Disabling Oplocks</h4></div></div></div><p> 442You can disable oplocks on a per-share basis with the following: 443</p><p> 444</p><table class="simplelist" border="0" summary="Simple list"><tr><td> </td></tr><tr><td><em class="parameter"><code>[acctdata]</code></em></td></tr><tr><td><a class="indexterm" name="id2617035"></a><em class="parameter"><code>oplocks = False</code></em></td></tr><tr><td><a class="indexterm" name="id2617047"></a><em class="parameter"><code>level2 oplocks = False</code></em></td></tr></table><p> 445</p><p> 446The default oplock type is Level1. Level2 oplocks are enabled on a per-share basis 447in the <code class="filename">smb.conf</code> file. 448</p><p> 449Alternately, you could disable oplocks on a per-file basis within the share: 450</p><p> 451 </p><table class="simplelist" border="0" summary="Simple list"><tr><td><a class="indexterm" name="id2617083"></a><em class="parameter"><code>veto oplock files = /*.mdb/*.MDB/*.dbf/*.DBF/</code></em></td></tr></table><p> 452</p><p> 453If you are experiencing problems with oplocks, as apparent from Samba's log entries, 454you may want to play it safe and disable oplocks and Level2 oplocks. 455</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2617103"></a>Disabling Kernel Oplocks</h4></div></div></div><p> 456Kernel oplocks is an <code class="filename">smb.conf</code> parameter that notifies Samba (if 457the UNIX kernel has the capability to send a Windows client an oplock 458break) when a UNIX process is attempting to open the file that is 459cached. This parameter addresses sharing files between UNIX and 460Windows with oplocks enabled on the Samba server: the UNIX process 461can open the file that is Oplocked (cached) by the Windows client and 462the smbd process will not send an oplock break, which exposes the file 463to the risk of data corruption. If the UNIX kernel has the ability to 464send an oplock break, then the kernel oplocks parameter enables Samba 465to send the oplock break. Kernel oplocks are enabled on a per-server 466basis in the <code class="filename">smb.conf</code> file. 467</p><p> 468</p><table class="simplelist" border="0" summary="Simple list"><tr><td><a class="indexterm" name="id2617143"></a><em class="parameter"><code>kernel oplocks = yes</code></em></td></tr></table><p> 469The default is no. 470</p><p> 471<span class="emphasis"><em>Veto oplocks</em></span> is an <code class="filename">smb.conf</code> parameter that identifies specific files for 472which oplocks are disabled. When a Windows client opens a file that 473has been configured for veto oplocks, the client will not be granted 474the oplock, and all operations will be executed on the original file on 475disk instead of a client-cached file copy. By explicitly identifying 476files that are shared with UNIX processes and disabling oplocks for 477those files, the server-wide oplock configuration can be enabled to 478allow Windows clients to utilize the performance benefit of file 479caching without the risk of data corruption. Veto oplocks can be 480enabled on a per-share basis, or globally for the entire server, in the 481<code class="filename">smb.conf</code> file as shown in <a class="link" href="locking.html#far1" title="Example�17.1.�Share with Some Files Oplocked">“Share with Some Files Oplocked”</a>. 482</p><p> 483</p><div class="example"><a name="far1"></a><p class="title"><b>Example�17.1.�Share with Some Files Oplocked</b></p><div class="example-contents"><table class="simplelist" border="0" summary="Simple list"><tr><td> </td></tr><tr><td><em class="parameter"><code>[global]</code></em></td></tr><tr><td><a class="indexterm" name="id2617220"></a><em class="parameter"><code>veto oplock files = /filename.htm/*.txt/</code></em></td></tr><tr><td> </td></tr><tr><td><em class="parameter"><code>[share_name]</code></em></td></tr><tr><td><a class="indexterm" name="id2617241"></a><em class="parameter"><code>veto oplock files = /*.exe/filename.ext/</code></em></td></tr></table></div></div><p><br class="example-break"> 484</p><p> 485<a class="link" href="smb.conf.5.html#OPLOCKBREAKWAITTIME" target="_top">oplock break wait time</a> is an <code class="filename">smb.conf</code> parameter 486that adjusts the time interval for Samba to reply to an oplock break request. Samba recommends: 487“<span class="quote">Do not change this parameter unless you have read and understood the Samba oplock code.</span>” 488Oplock break wait time can only be configured globally in the <code class="filename">smb.conf</code> file as shown: 489</p><p> 490 </p><table class="simplelist" border="0" summary="Simple list"><tr><td><a class="indexterm" name="id2617298"></a><em class="parameter"><code>oplock break wait time = 0 (default)</code></em></td></tr></table><p> 491</p><p> 492<span class="emphasis"><em>Oplock break contention limit</em></span> is an <code class="filename">smb.conf</code> parameter that limits the 493response of the Samba server to grant an oplock if the configured 494number of contending clients reaches the limit specified by the parameter. Samba recommends 495“<span class="quote">Do not change this parameter unless you have read and understood the Samba oplock code.</span>” 496Oplock break contention limit can be enabled on a per-share basis, or globally for 497the entire server, in the <code class="filename">smb.conf</code> file as shown in <a class="link" href="locking.html#far3" title="Example�17.2.�Configuration with Oplock Break Contention Limit">“Configuration with Oplock Break Contention Limit”</a>. 498</p><p> 499</p><div class="example"><a name="far3"></a><p class="title"><b>Example�17.2.�Configuration with Oplock Break Contention Limit</b></p><div class="example-contents"><table class="simplelist" border="0" summary="Simple list"><tr><td> </td></tr><tr><td><em class="parameter"><code>[global]</code></em></td></tr><tr><td><a class="indexterm" name="id2617372"></a><em class="parameter"><code>oplock break contention limit = 2 (default)</code></em></td></tr><tr><td> </td></tr><tr><td><em class="parameter"><code>[share_name]</code></em></td></tr><tr><td><a class="indexterm" name="id2617394"></a><em class="parameter"><code>oplock break contention limit = 2 (default)</code></em></td></tr></table></div></div><p><br class="example-break"> 500</p></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2617411"></a>MS Windows Oplocks and Caching Controls</h2></div></div></div><p> 501There is a known issue when running applications (like Norton Antivirus) on a Windows 2000/ XP 502workstation computer that can affect any application attempting to access shared database files 503across a network. This is a result of a default setting configured in the Windows 2000/XP 504operating system. When a workstation 505attempts to access shared data files located on another Windows 2000/XP computer, 506the Windows 2000/XP operating system will attempt to increase performance by locking the 507files and caching information locally. When this occurs, the application is unable to 508properly function, which results in an “<span class="quote">Access Denied</span>” 509 error message being displayed during network operations. 510</p><p> 511All Windows operating systems in the NT family that act as database servers for data files 512(meaning that data files are stored there and accessed by other Windows PCs) may need to 513have oplocks disabled in order to minimize the risk of data file corruption. 514This includes Windows 9x/Me, Windows NT, Windows 200x, and Windows XP. 515<sup>[<a name="id2617444" href="#ftn.id2617444" class="footnote">5</a>]</sup> 516</p><p> 517If you are using a Windows NT family workstation in place of a server, you must also 518disable oplocks on that workstation. For example, if you use a 519PC with the Windows NT Workstation operating system instead of Windows NT Server, and you 520have data files located on it that are accessed from other Windows PCs, you may need to 521disable oplocks on that system. 522</p><p> 523The major difference is the location in the Windows registry where the values for disabling 524oplocks are entered. Instead of the LanManServer location, the LanManWorkstation location 525may be used. 526</p><p> 527You can verify (change or add, if necessary) this registry value using the Windows 528Registry Editor. When you change this registry value, you will have to reboot the PC 529to ensure that the new setting goes into effect. 530</p><p> 531The location of the client registry entry for oplocks has changed in 532Windows 2000 from the earlier location in Microsoft Windows NT. 533</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> 534Windows 2000 will still respect the EnableOplocks registry value used to disable oplocks 535in earlier versions of Windows. 536</p></div><p> 537You can also deny the granting of oplocks by changing the following registry entries: 538</p><p> 539</p><pre class="programlisting"> 540 HKEY_LOCAL_MACHINE\System\ 541 CurrentControlSet\Services\MRXSmb\Parameters\ 542 543 OplocksDisabled REG_DWORD 0 or 1 544 Default: 0 (not disabled) 545</pre><p> 546</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> 547The OplocksDisabled registry value configures Windows clients to either request or not 548request oplocks on a remote file. To disable oplocks, the value of 549 OplocksDisabled must be set to 1. 550</p></div><p> 551</p><pre class="programlisting"> 552 HKEY_LOCAL_MACHINE\System\ 553 CurrentControlSet\Services\LanmanServer\Parameters 554 555 EnableOplocks REG_DWORD 0 or 1 556 Default: 1 (Enabled by Default) 557 558 EnableOpLockForceClose REG_DWORD 0 or 1 559 Default: 0 (Disabled by Default) 560</pre><p> 561</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> 562The EnableOplocks value configures Windows-based servers (including Workstations sharing 563files) to allow or deny oplocks on local files. 564</p></div><p> 565To force closure of open oplocks on close or program exit, EnableOpLockForceClose must be set to 1. 566</p><p> 567An illustration of how Level2 oplocks work follows: 568</p><div class="itemizedlist"><ul type="disc"><li><p> 569 Station 1 opens the file requesting oplock. 570 </p></li><li><p> 571 Since no other station has the file open, the server grants station 1 exclusive oplock. 572 </p></li><li><p> 573 Station 2 opens the file requesting oplock. 574 </p></li><li><p> 575 Since station 1 has not yet written to the file, the server asks station 1 to break 576 to Level2 oplock. 577 </p></li><li><p> 578 Station 1 complies by flushing locally buffered lock information to the server. 579 </p></li><li><p> 580 Station 1 informs the server that it has broken to level2 Oplock (alternately, 581 station 1 could have closed the file). 582 </p></li><li><p> 583 The server responds to station 2's open request, granting it Level2 oplock. 584 Other stations can likewise open the file and obtain Level2 oplock. 585 </p></li><li><p> 586 Station 2 (or any station that has the file open) sends a write request SMB. 587 The server returns the write response. 588 </p></li><li><p> 589 The server asks all stations that have the file open to break to none, meaning no 590 station holds any oplock on the file. Because the workstations can have no cached 591 writes or locks at this point, they need not respond to the break-to-none advisory; 592 all they need do is invalidate locally cashed read-ahead data. 593 </p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2617598"></a>Workstation Service Entries</h3></div></div></div><pre class="programlisting"> 594 \HKEY_LOCAL_MACHINE\System\ 595 CurrentControlSet\Services\LanmanWorkstation\Parameters 596 597 UseOpportunisticLocking REG_DWORD 0 or 1 598 Default: 1 (true) 599</pre><p> 600This indicates whether the redirector should use oplocks performance 601enhancement. This parameter should be disabled only to isolate problems. 602</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2617620"></a>Server Service Entries</h3></div></div></div><pre class="programlisting"> 603 \HKEY_LOCAL_MACHINE\System\ 604 CurrentControlSet\Services\LanmanServer\Parameters 605 606 EnableOplocks REG_DWORD 0 or 1 607 Default: 1 (true) 608</pre><p> 609This specifies whether the server allows clients to use oplocks on files. Oplocks are a 610significant performance enhancement, but have the potential to cause lost cached 611data on some networks, particularly WANs. 612</p><pre class="programlisting"> 613 MinLinkThroughput REG_DWORD 0 to infinite bytes per second 614 Default: 0 615</pre><p> 616This specifies the minimum link throughput allowed by the server before it disables 617raw I/O and oplocks for this connection. 618</p><pre class="programlisting"> 619 MaxLinkDelay REG_DWORD 0 to 100,000 seconds 620 Default: 60 621</pre><p> 622This specifies the maximum time allowed for a link delay. If delays exceed this number, 623the server disables raw I/O and oplocks for this connection. 624</p><pre class="programlisting"> 625 OplockBreakWait REG_DWORD 10 to 180 seconds 626 Default: 35 627</pre><p> 628This specifies the time that the server waits for a client to respond to an oplock break 629request. Smaller values can allow detection of crashed clients more quickly but can 630potentially cause loss of cached data. 631</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2617686"></a>Persistent Data Corruption</h2></div></div></div><p> 632If you have applied all of the settings discussed in this chapter but data corruption problems 633and other symptoms persist, here are some additional things to check out. 634</p><p> 635We have credible reports from developers that faulty network hardware, such as a single 636faulty network card, can cause symptoms similar to read caching and data corruption. 637If you see persistent data corruption even after repeated re-indexing, you may have to 638rebuild the data files in question. This involves creating a new data file with the 639same definition as the file to be rebuilt and transferring the data from the old file 640to the new one. There are several known methods for doing this that can be found in 641our knowledge base. 642</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2617712"></a>Common Errors</h2></div></div></div><p> 643In some sites locking problems surface as soon as a server is installed; in other sites 644locking problems may not surface for a long time. Almost without exception, when a locking 645problem does surface, it will cause embarrassment and potential data corruption. 646</p><p> 647Over the past few years there have been a number of complaints on the Samba mailing lists 648that have claimed that Samba caused data corruption. Three causes have been identified 649so far: 650</p><div class="itemizedlist"><ul type="disc"><li><p> 651 Incorrect configuration of oplocks (incompatible with the application 652 being used). This is a common problem even where MS Windows NT4 or MS Windows 653 200x-based servers were in use. It is imperative that the software application vendors' 654 instructions for configuration of file locking should be followed. If in doubt, 655 disable oplocks on both the server and the client. Disabling of all forms of file 656 caching on the MS Windows client may be necessary also. 657 </p></li><li><p> 658 Defective network cards, cables, or hubs/switches. This is generally a more 659 prevalent factor with low-cost networking hardware, although occasionally there 660 have also been problems with incompatibilities in more up-market hardware. 661 </p></li><li><p> 662 There have been some random reports of Samba log files being written over data 663 files. This has been reported by very few sites (about five in the past 3 years) 664 and all attempts to reproduce the problem have failed. The Samba Team has been 665 unable to catch this happening and thus unable to isolate any particular 666 cause. Considering the millions of systems that use Samba, for the sites that have 667 been affected by this as well as for the Samba Team, this is a frustrating and 668 vexing challenge. If you see this type of thing happening, please create a bug 669 report on Samba <a class="ulink" href="https://bugzilla.samba.org" target="_top">Bugzilla</a> without delay. 670 Make sure that you give as much information as you possibly can to help isolate the 671 cause and to allow replication of the problem (an essential step in problem isolation and correction). 672 </p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2617779"></a>locking.tdb Error Messages</h3></div></div></div><p> 673 “<span class="quote"> 674 We are seeing lots of errors in the Samba logs, like: 675 </span>” 676</p><pre class="programlisting"> 677tdb(/usr/local/samba_2.2.7/var/locks/locking.tdb): rec_read bad magic 678 0x4d6f4b61 at offset=36116 679</pre><p> 680 681 “<span class="quote"> 682 What do these mean? 683 </span>” 684 </p><p> 685 This error indicates a corrupted tdb. Stop all instances of smbd, delete locking.tdb, and restart smbd. 686 </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2617810"></a>Problems Saving Files in MS Office on Windows XP</h3></div></div></div><a class="indexterm" name="id2617816"></a><p>This is a bug in Windows XP. More information can be 687 found in <a class="ulink" href="http://support.microsoft.com/?id=812937" target="_top">Microsoft Knowledge Base article 812937</a></p>. 688 689 </div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2617834"></a>Long Delays Deleting Files over Network with XP SP1</h3></div></div></div><p>“<span class="quote">It sometimes takes approximately 35 seconds to delete files over the network after XP SP1 has been applied.</span>”</p><a class="indexterm" name="id2617847"></a><p>This is a bug in Windows XP. More information can be found in <a class="ulink" href="http://support.microsoft.com/?id=811492" target="_top"> 690 Microsoft Knowledge Base article 811492</a></p>. 691 </div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2617866"></a>Additional Reading</h2></div></div></div><p> 692You may want to check for an updated documentation regarding file and record locking issues on the Microsoft 693<a class="ulink" href="http://support.microsoft.com/" target="_top">Support</a> web site. Additionally, search for the word 694<code class="literal">locking</code> on the Samba <a class="ulink" href="http://www.samba.org/" target="_top">web</a> site. 695</p><p> 696Section of the Microsoft MSDN Library on opportunistic locking: 697</p><p> 698<a class="indexterm" name="id2617902"></a> 699Microsoft Knowledge Base, “<span class="quote">Maintaining Transactional Integrity with OPLOCKS</span>”, 700Microsoft Corporation, April 1999, <a class="ulink" href="http://support.microsoft.com/?id=224992" target="_top">Microsoft 701KB Article 224992</a>. 702</p><p> 703<a class="indexterm" name="id2617926"></a> 704Microsoft Knowledge Base, “<span class="quote">Configuring Opportunistic Locking in Windows 2000</span>”, 705Microsoft Corporation, April 2001 <a class="ulink" href="http://support.microsoft.com/?id=296264" target="_top">Microsoft KB Article 296264</a>. 706</p><p> 707<a class="indexterm" name="id2617950"></a> 708Microsoft Knowledge Base, “<span class="quote">PC Ext: Explanation of Opportunistic Locking on Windows NT</span>”, 709Microsoft Corporation, April 1995 <a class="ulink" href="http://support.microsoft.com/?id=129202" target="_top">Microsoft 710KB Article 129202</a>. 711</p></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.id2617444" href="#id2617444" class="para">5</a>] </sup>Microsoft has documented this in Knowledge Base article 300216.</p></div></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�16.�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�18.�Securing Samba</td></tr></table></div></body></html> 712