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