1<?xml version="1.0" encoding="iso-8859-1"?> 2<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> 3<chapter id="locking"> 4<chapterinfo> 5 &author.jeremy; 6 &author.jelmer; 7 &author.jht; 8 &author.eroseme; 9</chapterinfo> 10<title>File and Record Locking</title> 11 12<para> 13<indexterm><primary>locking</primary></indexterm> 14One area that causes trouble for many network administrators is locking. 15The extent of the problem is readily evident from searches over the Internet. 16</para> 17 18<sect1> 19<title>Features and Benefits</title> 20 21<para> 22<indexterm><primary>locking semantics</primary></indexterm> 23Samba provides all the same locking semantics that MS Windows clients expect 24and that MS Windows NT4/200x servers also provide. 25</para> 26 27<para> 28<indexterm><primary>locking</primary></indexterm> 29The term <emphasis>locking</emphasis> has exceptionally broad meaning and covers 30a range of functions that are all categorized under this one term. 31</para> 32 33<para> 34<indexterm><primary>opportunistic locking</primary></indexterm> 35<indexterm><primary>locking protocol</primary></indexterm> 36<indexterm><primary>performance advantage</primary></indexterm> 37Opportunistic locking is a desirable feature when it can enhance the 38perceived performance of applications on a networked client. However, the 39opportunistic locking protocol is not robust and therefore can 40encounter problems when invoked beyond a simplistic configuration or 41on extended slow or faulty networks. In these cases, operating 42system management of opportunistic locking and/or recovering from 43repetitive errors can offset the perceived performance advantage that 44it is intended to provide. 45</para> 46 47<para> 48<indexterm><primary>registry</primary></indexterm> 49The MS Windows network administrator needs to be aware that file and record 50locking semantics (behavior) can be controlled either in Samba or by way of registry 51settings on the MS Windows client. 52</para> 53 54<note> 55<para> 56<indexterm><primary>disable locking</primary></indexterm> 57Sometimes it is necessary to disable locking control settings on the Samba 58server as well as on each MS Windows client! 59</para> 60</note> 61 62</sect1> 63 64<sect1> 65<title>Discussion</title> 66 67<para> 68<indexterm><primary>record locking</primary></indexterm> 69<indexterm><primary>deny modes</primary></indexterm> 70There are two types of locking that need to be performed by an SMB server. 71The first is <emphasis>record locking</emphasis> that allows a client to lock 72a range of bytes in an open file. The second is the <emphasis>deny modes</emphasis> 73that are specified when a file is open. 74</para> 75 76<para> 77<indexterm><primary>locking semantics</primary></indexterm> 78<indexterm><primary>record locking</primary></indexterm> 79<indexterm><primary>locking</primary></indexterm> 80<indexterm><primary>byte ranges</primary></indexterm> 81<indexterm><primary>UNIX locking</primary></indexterm> 82Record locking semantics under UNIX are very different from record locking under 83Windows. Versions of Samba before 2.2 have tried to use the native fcntl() UNIX 84system call to implement proper record locking between different Samba clients. 85This cannot be fully correct for several reasons. The simplest is 86that a Windows client is allowed to lock a byte range up to 2^32 or 2^64, 87depending on the client OS. The UNIX locking only supports byte ranges up to 2^31. 88So it is not possible to correctly satisfy a lock request above 2^31. There are 89many more differences, too many to be listed here. 90</para> 91 92<para> 93<indexterm><primary>record locking</primary></indexterm> 94<indexterm><primary>byte-range lock</primary></indexterm> 95Samba 2.2 and above implement record locking completely independently of the 96underlying UNIX system. If a byte-range lock that the client requests happens 97to fall into the range of 0 to 2^31, Samba hands this request down to the UNIX system. 98No other locks can be seen by UNIX, anyway. 99</para> 100 101<para> 102<indexterm><primary>check for locks</primary></indexterm> 103<indexterm><primary>rpc.lockd</primary></indexterm> 104Strictly speaking, an SMB server should check for locks before every read and write call on 105a file. Unfortunately, with the way fcntl() works, this can be slow and may overstress 106the <command>rpc.lockd</command>. This is almost always unnecessary because clients are 107independently supposed to make locking calls before reads and writes if locking is 108important to them. By default, Samba only makes locking calls when explicitly asked 109to by a client, but if you set <smbconfoption name="strict locking">yes</smbconfoption>, it 110will make lock checking calls on <emphasis>every</emphasis> read and write call. 111</para> 112 113<para> 114<indexterm><primary>byte-range locking</primary></indexterm> 115You can also disable byte-range locking completely by using 116<smbconfoption name="locking">no</smbconfoption>. 117This is useful for those shares that do not support locking or do not need it 118(such as CD-ROMs). In this case, Samba fakes the return codes of locking calls to 119tell clients that everything is okay. 120</para> 121 122<para> 123<indexterm><primary>deny modes</primary></indexterm> 124<indexterm><primary>DENY_NONE</primary></indexterm> 125<indexterm><primary>DENY_READ</primary></indexterm> 126<indexterm><primary>DENY_WRITE</primary></indexterm> 127<indexterm><primary>DENY_ALL</primary></indexterm> 128<indexterm><primary>DENY_FCB</primary></indexterm> 129<indexterm><primary>DENY_DOS</primary></indexterm> 130The second class of locking is the <emphasis>deny modes</emphasis>. These 131are set by an application when it opens a file to determine what types of 132access should be allowed simultaneously with its open. A client may ask for 133<constant>DENY_NONE</constant>, <constant>DENY_READ</constant>, 134<constant>DENY_WRITE</constant>, or <constant>DENY_ALL</constant>. There are also special compatibility 135modes called <constant>DENY_FCB</constant> and <constant>DENY_DOS</constant>. 136</para> 137 138<sect2> 139<title>Opportunistic Locking Overview</title> 140 141<para> 142<indexterm><primary>opportunistic locking</primary></indexterm> 143<indexterm><primary>oplocks</primary></indexterm> 144<indexterm><primary>caching</primary></indexterm> 145Opportunistic locking (oplocks) is invoked by the Windows file system 146(as opposed to an API) via registry entries (on the server and the client) 147for the purpose of enhancing network performance when accessing a file 148residing on a server. Performance is enhanced by caching the file 149locally on the client that allows the following: 150</para> 151 152<variablelist> 153 <varlistentry><term>Read-ahead:</term> 154 <listitem><para> 155<indexterm><primary>Read-ahead</primary></indexterm> 156 The client reads the local copy of the file, eliminating network latency. 157 </para></listitem> 158 </varlistentry> 159 160 <varlistentry><term>Write caching:</term> 161 <listitem><para> 162<indexterm><primary>Write caching</primary></indexterm> 163 The client writes to the local copy of the file, eliminating network latency. 164 </para></listitem> 165 </varlistentry> 166 167 <varlistentry><term>Lock caching:</term> 168 <listitem><para> 169<indexterm><primary>Lock caching</primary></indexterm> 170 The client caches application locks locally, eliminating network latency. 171 </para></listitem> 172 </varlistentry> 173</variablelist> 174 175<para> 176<indexterm><primary>performance enhancement</primary></indexterm> 177<indexterm><primary>oplocks</primary></indexterm> 178<indexterm><primary>deny-none</primary></indexterm> 179The performance enhancement of oplocks is due to the opportunity of 180exclusive access to the file &smbmdash; even if it is opened with deny-none &smbmdash; 181because Windows monitors the file's status for concurrent access from 182other processes. 183</para> 184 185<variablelist> 186<title>Windows Defines Four Kinds of Oplocks:</title> 187 188 <varlistentry><term>Level1 Oplock</term> 189 <listitem><para> 190<indexterm><primary>Level1 Oplock</primary></indexterm> 191<indexterm><primary>redirector</primary></indexterm> 192<indexterm><primary>concurrent access</primary></indexterm> 193<indexterm><primary>cached local file</primary></indexterm> 194 The redirector sees that the file was opened with deny 195 none (allowing concurrent access), verifies that no 196 other process is accessing the file, checks that 197 oplocks are enabled, then grants deny-all/read-write/exclusive 198 access to the file. The client now performs 199 operations on the cached local file. 200 </para> 201 202 <para> 203<indexterm><primary>oplock break</primary></indexterm> 204<indexterm><primary>flush local locks</primary></indexterm> 205<indexterm><primary>deferred open</primary></indexterm> 206<indexterm><primary>byte-range locking</primary></indexterm> 207 If a second process attempts to open the file, the open 208 is deferred while the redirector "breaks" the original 209 oplock. The oplock break signals the caching client to 210 write the local file back to the server, flush the 211 local locks, and discard read-ahead data. The break is 212 then complete, the deferred open is granted, and the 213 multiple processes can enjoy concurrent file access as 214 dictated by mandatory or byte-range locking options. 215 However, if the original opening process opened the 216 file with a share mode other than deny-none, then the 217 second process is granted limited or no access, despite 218 the oplock break. 219 </para></listitem> 220 </varlistentry> 221 222 <varlistentry><term>Level2 Oplock</term> 223 <listitem><para> 224<indexterm><primary>Level2 Oplock</primary></indexterm> 225<indexterm><primary>Level1 oplock</primary></indexterm> 226<indexterm><primary>caching</primary></indexterm> 227 Performs like a Level1 oplock, except caching is only 228 operative for reads. All other operations are performed 229 on the server disk copy of the file. 230 </para></listitem> 231 </varlistentry> 232 233 <varlistentry><term>Filter Oplock</term> 234 <listitem><para> 235<indexterm><primary>Filter Oplock</primary></indexterm> 236 Does not allow write or delete file access. 237 </para></listitem> 238 </varlistentry> 239 240 <varlistentry><term>Batch Oplock</term> 241 <listitem><para> 242<indexterm><primary>Batch Oplock</primary></indexterm> 243 Manipulates file openings and closings and allows caching 244 of file attributes. 245 </para></listitem> 246 </varlistentry> 247</variablelist> 248 249<para> 250<indexterm><primary>oplocks</primary></indexterm> 251An important detail is that oplocks are invoked by the file system, not 252an application API. Therefore, an application can close an oplocked 253file, but the file system does not relinquish the oplock. When the 254oplock break is issued, the file system then simply closes the file in 255preparation for the subsequent open by the second process. 256</para> 257 258<para> 259<indexterm><primary>Opportunistic locking</primary></indexterm> 260<indexterm><primary>client-side data caching</primary></indexterm> 261<indexterm><primary>data caching</primary></indexterm> 262<indexterm><primary>oplock break</primary></indexterm> 263<emphasis>Opportunistic locking</emphasis> is actually an improper name for this feature. 264The true benefit of this feature is client-side data caching, and 265oplocks is merely a notification mechanism for writing data back to the 266networked storage disk. The limitation of oplocks is the 267reliability of the mechanism to process an oplock break (notification) 268between the server and the caching client. If this exchange is faulty 269(usually due to timing out for any number of reasons), then the 270client-side caching benefit is negated. 271</para> 272 273<para> 274<indexterm><primary>client-side caching</primary></indexterm> 275The actual decision that a user or administrator should consider is 276whether it is sensible to share among multiple users data that will 277be cached locally on a client. In many cases the answer is no. 278Deciding when to cache or not cache data is the real question, and thus 279oplocks should be treated as a toggle for client-side 280caching. Turn it <quote>on</quote> when client-side caching is desirable and 281reliable. Turn it <quote>off</quote> when client-side caching is redundant, 282unreliable, or counterproductive. 283</para> 284 285<para> 286<indexterm><primary>oplocks</primary></indexterm> 287Oplocks is by default set to <quote>on</quote> by Samba on all 288configured shares, so careful attention should be given to each case to 289determine if the potential benefit is worth the potential for delays. 290The following recommendations will help to characterize the environment 291where oplocks may be effectively configured. 292</para> 293 294<para> 295<indexterm><primary>oplocks</primary></indexterm> 296<indexterm><primary>high-availability</primary></indexterm> 297Windows oplocks is a lightweight performance-enhancing 298feature. It is not a robust and reliable protocol. Every 299implementation of oplocks should be evaluated as a 300trade-off between perceived performance and reliability. Reliability 301decreases as each successive rule above is not enforced. Consider a 302share with oplocks enabled, over a wide-area network, to a client on a 303South Pacific atoll, on a high-availability server, serving a 304mission-critical multiuser corporate database during a tropical 305storm. This configuration will likely encounter problems with oplocks. 306</para> 307 308<para> 309<indexterm><primary>mission-critical</primary></indexterm> 310Oplocks can be beneficial to perceived client performance when treated 311as a configuration toggle for client-side data caching. If the data 312caching is likely to be interrupted, then oplock usage should be 313reviewed. Samba enables oplocks by default on all 314shares. Careful attention should be given to the client usage of 315shared data on the server, the server network reliability, and the 316oplocks configuration of each share. 317In mission-critical, high-availability environments, data integrity is 318often a priority. Complex and expensive configurations are implemented 319to ensure that if a client loses connectivity with a file server, a 320failover replacement will be available immediately to provide 321continuous data availability. 322</para> 323 324<para> 325<indexterm><primary>Windows client failover</primary></indexterm> 326<indexterm><primary>transport connection loss</primary></indexterm> 327Windows client failover behavior is more at risk of application 328interruption than other platforms because it is dependent upon an 329established TCP transport connection. If the connection is interrupted 330&smbmdash; as in a file server failover &smbmdash; a new session must be established. 331It is rare for Windows client applications to be coded to recover 332correctly from a transport connection loss; therefore, most applications 333will experience some sort of interruption &smbmdash; at worst, abort and 334require restarting. 335</para> 336 337<para> 338<indexterm><primary>caching writes</primary></indexterm> 339<indexterm><primary>caching reads</primary></indexterm> 340<indexterm><primary>oplock break</primary></indexterm> 341If a client session has been caching writes and reads locally due to 342oplocks, it is likely that the data will be lost when the 343application restarts or recovers from the TCP interrupt. When the TCP 344connection drops, the client state is lost. When the file server 345recovers, an oplock break is not sent to the client. In this case, the 346work from the prior session is lost. Observing this scenario with 347oplocks disabled and with the client writing data to the file server 348real-time, the failover will provide the data on disk as it 349existed at the time of the disconnect. 350</para> 351 352<para> 353In mission-critical, high-availability environments, careful attention 354should be given to oplocks. Ideally, comprehensive 355testing should be done with all affected applications with oplocks 356enabled and disabled. 357</para> 358 359<sect3> 360<title>Exclusively Accessed Shares</title> 361 362<para> 363Oplocks is most effective when it is confined to shares 364that are exclusively accessed by a single user, or by only one user at 365a time. Because the true value of oplocks is the local 366client caching of data, any operation that interrupts the caching 367mechanism will cause a delay. 368</para> 369 370<para> 371Home directories are the most obvious examples of where the performance 372benefit of oplocks can be safely realized. 373</para> 374 375</sect3> 376 377<sect3> 378<title>Multiple-Accessed Shares or Files</title> 379 380<para> 381As each additional user accesses a file in a share with oplocks 382enabled, the potential for delays and resulting perceived poor 383performance increases. When multiple users are accessing a file on a 384share that has oplocks enabled, the management impact of sending and 385receiving oplock breaks and the resulting latency while other clients 386wait for the caching client to flush data offset the performance gains 387of the caching user. 388</para> 389 390<para> 391As each additional client attempts to access a file with oplocks set, 392the potential performance improvement is negated and eventually results 393in a performance bottleneck. 394</para> 395 396</sect3> 397 398<sect3> 399<title>UNIX or NFS Client-Accessed Files</title> 400 401<para> 402<indexterm><primary>NFS clients</primary></indexterm> 403<indexterm><primary>data corruption</primary></indexterm> 404Local UNIX and NFS clients access files without a mandatory 405file-locking mechanism. Thus, these client platforms are incapable of 406initiating an oplock break request from the server to a Windows client 407that has a file cached. Local UNIX or NFS file access can therefore 408write to a file that has been cached by a Windows client, which 409exposes the file to likely data corruption. 410</para> 411 412<para> 413If files are shared between Windows clients and either local UNIX 414or NFS users, turn oplocks off. 415</para> 416 417</sect3> 418 419<sect3> 420<title>Slow and/or Unreliable Networks</title> 421 422<para> 423<indexterm><primary>performance improvement</primary></indexterm> 424<indexterm><primary>WAN</primary></indexterm> 425<indexterm><primary>latency</primary></indexterm> 426The biggest potential performance improvement for oplocks 427occurs when the client-side caching of reads and writes delivers the 428most differential over sending those reads and writes over the wire. 429This is most likely to occur when the network is extremely slow, 430congested, or distributed (as in a WAN). However, network latency also 431has a high impact on the reliability of the oplock break 432mechanism, and thus increases the likelihood of encountering oplock 433problems that more than offset the potential perceived performance 434gain. Of course, if an oplock break never has to be sent, then this is 435the most advantageous scenario in which to utilize oplocks. 436</para> 437 438<para> 439If the network is slow, unreliable, or a WAN, then do not configure 440oplocks if there is any chance of multiple users 441regularly opening the same file. 442</para> 443 444</sect3> 445 446<sect3> 447<title>Multiuser Databases</title> 448 449<para> 450<indexterm><primary>Multiuser databases</primary></indexterm> 451<indexterm><primary>management bottleneck</primary></indexterm> 452<indexterm><primary>oplocks disabled</primary></indexterm> 453Multiuser databases clearly pose a risk due to their very nature &smbmdash; they are typically heavily 454accessed by numerous users at random intervals. Placing a multiuser database on a share with oplocks enabled 455will likely result in a locking management bottleneck on the Samba server. Whether the database application is 456developed in-house or a commercially available product, ensure that the share has oplocks disabled. 457</para> 458 459</sect3> 460 461<sect3> 462<title>PDM Data Shares</title> 463 464<para> 465<indexterm><primary>PDM</primary></indexterm> 466<indexterm><primary>Process data management</primary></indexterm> 467<indexterm><primary>client-side data caching</primary></indexterm> 468<indexterm><primary>oplocks management</primary></indexterm> 469<indexterm><primary>disabling oplocks</primary></indexterm> 470Process data management (PDM) applications such as IMAN, Enovia, and Clearcase are increasing in usage with 471Windows client platforms and therefore with SMB datastores. PDM applications manage multiuser environments for 472critical data security and access. The typical PDM environment is usually associated with sophisticated client 473design applications that will load data locally as demanded. In addition, the PDM application will usually 474monitor the data state of each client. In this case, client-side data caching is best left to the local 475application and PDM server to negotiate and maintain. It is appropriate to eliminate the client OS from any 476caching tasks, and the server from any oplocks management, by disabling oplocks on the share. 477</para> 478 479</sect3> 480 481<sect3> 482<title>Beware of Force User</title> 483 484<para> 485<indexterm><primary>oplock break</primary></indexterm> 486Samba includes an &smb.conf; parameter called <smbconfoption name="force user"/> that changes the user 487accessing a share from the incoming user to whatever user is defined by the &smb.conf; variable. If oplocks is 488enabled on a share, the change in user access causes an oplock break to be sent to the client, even if the 489user has not explicitly loaded a file. In cases where the network is slow or unreliable, an oplock break can 490become lost without the user even accessing a file. This can cause apparent performance degradation as the 491client continually reconnects to overcome the lost oplock break. 492</para> 493 494<para> 495Avoid the combination of the following: 496</para> 497 498<itemizedlist> 499 <listitem><para> 500 <smbconfoption name="force user"/> in the &smb.conf; share configuration. 501 </para></listitem> 502 503 <listitem><para> 504 Slow or unreliable networks. 505 </para></listitem> 506 507 <listitem><para> 508 Oplocks enabled. 509 </para></listitem> 510</itemizedlist> 511 512</sect3> 513 514<sect3> 515<title>Advanced Samba Oplocks Parameters</title> 516 517<para> 518<indexterm><primary>oplock parameters</primary></indexterm> 519<indexterm><primary>oplock mechanism</primary></indexterm> 520<indexterm><primary>implementing oplocks</primary></indexterm> 521Samba provides oplock parameters that allow the 522administrator to adjust various properties of the oplock mechanism to 523account for timing and usage levels. These parameters provide good 524versatility for implementing oplocks in environments where they would 525likely cause problems. The parameters are 526<smbconfoption name="oplock break wait time"/>, and 527<smbconfoption name="oplock contention limit"/>. 528</para> 529 530<para> 531<indexterm><primary>turn oplocks off</primary></indexterm> 532For most users, administrators, and environments, if these parameters 533are required, then the better option is simply to turn oplocks off. 534The Samba SWAT help text for both parameters reads: <quote>Do not change 535this parameter unless you have read and understood the Samba oplock code.</quote> 536This is good advice. 537</para> 538 539</sect3> 540 541<sect3> 542<title>Mission-Critical, High-Availability</title> 543 544<para> 545In mission-critical, high-availability environments, data integrity is 546often a priority. Complex and expensive configurations are implemented 547to ensure that if a client loses connectivity with a file server, a 548failover replacement will be available immediately to provide 549continuous data availability. 550</para> 551 552<para> 553Windows client failover behavior is more at risk of application 554interruption than other platforms because it is dependent upon an 555established TCP transport connection. If the connection is interrupted 556&smbmdash; as in a file server failover &smbmdash; a new session must be established. 557It is rare for Windows client applications to be coded to recover 558correctly from a transport connection loss; therefore, most applications 559will experience some sort of interruption &smbmdash; at worst, abort and 560require restarting. 561</para> 562 563<para> 564If a client session has been caching writes and reads locally due to 565oplocks, it is likely that the data will be lost when the 566application restarts or recovers from the TCP interrupt. When the TCP 567connection drops, the client state is lost. When the file server 568recovers, an oplock break is not sent to the client. In this case, the 569work from the prior session is lost. Observing this scenario with 570oplocks disabled, if the client was writing data to the file server 571real-time, then the failover will provide the data on disk as it 572existed at the time of the disconnect. 573</para> 574 575<para> 576In mission-critical, high-availability environments, careful attention 577should be given to oplocks. Ideally, comprehensive 578testing should be done with all affected applications with oplocks 579enabled and disabled. 580</para> 581 582</sect3> 583</sect2> 584</sect1> 585 586<sect1> 587<title>Samba Oplocks Control</title> 588 589<para> 590Oplocks is a unique Windows file locking feature. It is 591not really file locking, but is included in most discussions of Windows 592file locking, so is considered a de facto locking feature. 593Oplocks is actually part of the Windows client file 594caching mechanism. It is not a particularly robust or reliable feature 595when implemented on the variety of customized networks that exist in 596enterprise computing. 597</para> 598 599<para> 600Like Windows, Samba implements oplocks as a server-side 601component of the client caching mechanism. Because of the lightweight 602nature of the Windows feature design, effective configuration of 603oplocks requires a good understanding of its limitations, 604and then applying that understanding when configuring data access for 605each particular customized network and client usage state. 606</para> 607 608<para> 609Oplocks essentially means that the client is allowed to download and cache 610a file on its hard drive while making changes; if a second client wants to access the 611file, the first client receives a break and must synchronize the file back to the server. 612This can give significant performance gains in some cases; some programs insist on 613synchronizing the contents of the entire file back to the server for a single change. 614</para> 615 616<para> 617Level1 Oplocks (also known as just plain <quote>oplocks</quote>) is another term for opportunistic locking. 618</para> 619 620<para> 621Level2 Oplocks provides opportunistic locking for a file that will be treated as 622<emphasis>read only</emphasis>. Typically this is used on files that are read-only or 623on files that the client has no initial intention to write to at time of opening the file. 624</para> 625 626<para> 627Kernel Oplocks are essentially a method that allows the Linux kernel to co-exist with 628Samba's oplocked files, although this has provided better integration of MS Windows network 629file locking with the underlying OS. SGI IRIX and Linux are the only two OSs that are 630oplock-aware at this time. 631</para> 632 633<para> 634Unless your system supports kernel oplocks, you should disable oplocks if you are 635accessing the same files from both UNIX/Linux and SMB clients. Regardless, oplocks should 636always be disabled if you are sharing a database file (e.g., Microsoft Access) between 637multiple clients, because any break the first client receives will affect synchronization of 638the entire file (not just the single record), which will result in a noticeable performance 639impairment and, more likely, problems accessing the database in the first place. Notably, 640Microsoft Outlook's personal folders (*.pst) react quite badly to oplocks. If in doubt, 641disable oplocks and tune your system from that point. 642</para> 643 644<para> 645If client-side caching is desirable and reliable on your network, you will benefit from 646turning on oplocks. If your network is slow and/or unreliable, or you are sharing your 647files among other file sharing mechanisms (e.g., NFS) or across a WAN, or multiple people 648will be accessing the same files frequently, you probably will not benefit from the overhead 649of your client sending oplock breaks and will instead want to disable oplocks for the share. 650</para> 651 652<para> 653Another factor to consider is the perceived performance of file access. If oplocks provide no 654measurable speed benefit on your network, it might not be worth the hassle of dealing with them. 655</para> 656 657<sect2> 658<title>Example Configuration</title> 659 660<para> 661In the following section we examine two distinct aspects of Samba locking controls. 662</para> 663 664<sect3> 665<title>Disabling Oplocks</title> 666 667<para> 668You can disable oplocks on a per-share basis with the following: 669</para> 670 671<para> 672<smbconfblock> 673<smbconfsection name="[acctdata]"/> 674<smbconfoption name="oplocks">False</smbconfoption> 675<smbconfoption name="level2 oplocks">False</smbconfoption> 676</smbconfblock> 677</para> 678 679<para> 680The default oplock type is Level1. Level2 oplocks are enabled on a per-share basis 681in the &smb.conf; file. 682</para> 683 684<para> 685Alternately, you could disable oplocks on a per-file basis within the share: 686</para> 687 688<para> 689 <smbconfblock> 690<smbconfoption name="veto oplock files">/*.mdb/*.MDB/*.dbf/*.DBF/</smbconfoption> 691</smbconfblock> 692</para> 693 694<para> 695If you are experiencing problems with oplocks, as apparent from Samba's log entries, 696you may want to play it safe and disable oplocks and Level2 oplocks. 697</para> 698 699</sect3> 700 701<sect3> 702<title>Disabling Kernel Oplocks</title> 703 704<para> 705Kernel oplocks is an &smb.conf; parameter that notifies Samba (if 706the UNIX kernel has the capability to send a Windows client an oplock 707break) when a UNIX process is attempting to open the file that is 708cached. This parameter addresses sharing files between UNIX and 709Windows with oplocks enabled on the Samba server: the UNIX process 710can open the file that is Oplocked (cached) by the Windows client and 711the smbd process will not send an oplock break, which exposes the file 712to the risk of data corruption. If the UNIX kernel has the ability to 713send an oplock break, then the kernel oplocks parameter enables Samba 714to send the oplock break. Kernel oplocks are enabled on a per-server 715basis in the &smb.conf; file. 716</para> 717 718<para> 719<smbconfblock> 720<smbconfoption name="kernel oplocks">yes</smbconfoption> 721</smbconfblock> 722The default is no. 723</para> 724 725<para> 726<emphasis>Veto oplocks</emphasis> is an &smb.conf; parameter that identifies specific files for 727which oplocks are disabled. When a Windows client opens a file that 728has been configured for veto oplocks, the client will not be granted 729the oplock, and all operations will be executed on the original file on 730disk instead of a client-cached file copy. By explicitly identifying 731files that are shared with UNIX processes and disabling oplocks for 732those files, the server-wide oplock configuration can be enabled to 733allow Windows clients to utilize the performance benefit of file 734caching without the risk of data corruption. Veto oplocks can be 735enabled on a per-share basis, or globally for the entire server, in the 736&smb.conf; file as shown in <link linkend="far1"/>. 737</para> 738 739<para> 740<example id="far1"> 741<title>Share with Some Files Oplocked</title> 742<smbconfblock> 743<smbconfsection name="[global]"/> 744<smbconfoption name="veto oplock files">/filename.htm/*.txt/</smbconfoption> 745 746<smbconfsection name="[share_name]"/> 747<smbconfoption name="veto oplock files">/*.exe/filename.ext/</smbconfoption> 748</smbconfblock> 749</example> 750</para> 751 752<para> 753<smbconfoption name="oplock break wait time"/> is an &smb.conf; parameter 754that adjusts the time interval for Samba to reply to an oplock break request. Samba recommends: 755<quote>Do not change this parameter unless you have read and understood the Samba oplock code.</quote> 756Oplock break wait time can only be configured globally in the &smb.conf; file as shown: 757</para> 758 759<para> 760 <smbconfblock> 761<smbconfoption name="oplock break wait time"> 0 (default)</smbconfoption> 762</smbconfblock> 763</para> 764 765<para> 766<emphasis>Oplock break contention limit</emphasis> is an &smb.conf; parameter that limits the 767response of the Samba server to grant an oplock if the configured 768number of contending clients reaches the limit specified by the parameter. Samba recommends 769<quote>Do not change this parameter unless you have read and understood the Samba oplock code.</quote> 770Oplock break contention limit can be enabled on a per-share basis, or globally for 771the entire server, in the &smb.conf; file as shown in <link linkend="far3"/>. 772</para> 773 774<para> 775<example id="far3"> 776<title>Configuration with Oplock Break Contention Limit</title> 777<smbconfblock> 778<smbconfsection name="[global]"/> 779<smbconfoption name="oplock break contention limit"> 2 (default)</smbconfoption> 780 781<smbconfsection name="[share_name]"/> 782<smbconfoption name="oplock break contention limit"> 2 (default)</smbconfoption> 783</smbconfblock> 784</example> 785</para> 786 787</sect3> 788</sect2> 789 790</sect1> 791 792<sect1> 793<title>MS Windows Oplocks and Caching Controls</title> 794 795<para> 796There is a known issue when running applications (like Norton Antivirus) on a Windows 2000/ XP 797workstation computer that can affect any application attempting to access shared database files 798across a network. This is a result of a default setting configured in the Windows 2000/XP 799operating system. When a workstation 800attempts to access shared data files located on another Windows 2000/XP computer, 801the Windows 2000/XP operating system will attempt to increase performance by locking the 802files and caching information locally. When this occurs, the application is unable to 803properly function, which results in an <quote>Access Denied</quote> 804 error message being displayed during network operations. 805</para> 806 807<para> 808All Windows operating systems in the NT family that act as database servers for data files 809(meaning that data files are stored there and accessed by other Windows PCs) may need to 810have oplocks disabled in order to minimize the risk of data file corruption. 811This includes Windows 9x/Me, Windows NT, Windows 200x, and Windows XP. 812<footnote><para>Microsoft has documented this in Knowledge Base article 300216.</para></footnote> 813</para> 814 815<para> 816If you are using a Windows NT family workstation in place of a server, you must also 817disable oplocks on that workstation. For example, if you use a 818PC with the Windows NT Workstation operating system instead of Windows NT Server, and you 819have data files located on it that are accessed from other Windows PCs, you may need to 820disable oplocks on that system. 821</para> 822 823<para> 824The major difference is the location in the Windows registry where the values for disabling 825oplocks are entered. Instead of the LanManServer location, the LanManWorkstation location 826may be used. 827</para> 828 829<para> 830You can verify (change or add, if necessary) this registry value using the Windows 831Registry Editor. When you change this registry value, you will have to reboot the PC 832to ensure that the new setting goes into effect. 833</para> 834 835<para> 836The location of the client registry entry for oplocks has changed in 837Windows 2000 from the earlier location in Microsoft Windows NT. 838</para> 839 840<note><para> 841Windows 2000 will still respect the EnableOplocks registry value used to disable oplocks 842in earlier versions of Windows. 843</para></note> 844 845<para> 846You can also deny the granting of oplocks by changing the following registry entries: 847</para> 848 849<para> 850<programlisting> 851 HKEY_LOCAL_MACHINE\System\ 852 CurrentControlSet\Services\MRXSmb\Parameters\ 853 854 OplocksDisabled REG_DWORD 0 or 1 855 Default: 0 (not disabled) 856</programlisting> 857</para> 858 859<note><para> 860The OplocksDisabled registry value configures Windows clients to either request or not 861request oplocks on a remote file. To disable oplocks, the value of 862 OplocksDisabled must be set to 1. 863</para></note> 864 865<para> 866<programlisting> 867 HKEY_LOCAL_MACHINE\System\ 868 CurrentControlSet\Services\LanmanServer\Parameters 869 870 EnableOplocks REG_DWORD 0 or 1 871 Default: 1 (Enabled by Default) 872 873 EnableOpLockForceClose REG_DWORD 0 or 1 874 Default: 0 (Disabled by Default) 875</programlisting> 876</para> 877 878<note><para> 879The EnableOplocks value configures Windows-based servers (including Workstations sharing 880files) to allow or deny oplocks on local files. 881</para></note> 882 883<para> 884To force closure of open oplocks on close or program exit, EnableOpLockForceClose must be set to 1. 885</para> 886 887<para> 888An illustration of how Level2 oplocks work follows: 889</para> 890 891<itemizedlist> 892 <listitem><para> 893 Station 1 opens the file requesting oplock. 894 </para></listitem> 895 <listitem><para> 896 Since no other station has the file open, the server grants station 1 exclusive oplock. 897 </para></listitem> 898 <listitem><para> 899 Station 2 opens the file requesting oplock. 900 </para></listitem> 901 <listitem><para> 902 Since station 1 has not yet written to the file, the server asks station 1 to break 903 to Level2 oplock. 904 </para></listitem> 905 <listitem><para> 906 Station 1 complies by flushing locally buffered lock information to the server. 907 </para></listitem> 908 <listitem><para> 909 Station 1 informs the server that it has broken to level2 Oplock (alternately, 910 station 1 could have closed the file). 911 </para></listitem> 912 <listitem><para> 913 The server responds to station 2's open request, granting it Level2 oplock. 914 Other stations can likewise open the file and obtain Level2 oplock. 915 </para></listitem> 916 <listitem><para> 917 Station 2 (or any station that has the file open) sends a write request SMB. 918 The server returns the write response. 919 </para></listitem> 920 <listitem><para> 921 The server asks all stations that have the file open to break to none, meaning no 922 station holds any oplock on the file. Because the workstations can have no cached 923 writes or locks at this point, they need not respond to the break-to-none advisory; 924 all they need do is invalidate locally cashed read-ahead data. 925 </para></listitem> 926</itemizedlist> 927 928<sect2> 929<title>Workstation Service Entries</title> 930 931<para><programlisting> 932 \HKEY_LOCAL_MACHINE\System\ 933 CurrentControlSet\Services\LanmanWorkstation\Parameters 934 935 UseOpportunisticLocking REG_DWORD 0 or 1 936 Default: 1 (true) 937</programlisting></para> 938 939<para> 940This indicates whether the redirector should use oplocks performance 941enhancement. This parameter should be disabled only to isolate problems. 942</para> 943 944</sect2> 945<sect2> 946<title>Server Service Entries</title> 947 948<para><programlisting> 949 \HKEY_LOCAL_MACHINE\System\ 950 CurrentControlSet\Services\LanmanServer\Parameters 951 952 EnableOplocks REG_DWORD 0 or 1 953 Default: 1 (true) 954</programlisting></para> 955 956<para> 957This specifies whether the server allows clients to use oplocks on files. Oplocks are a 958significant performance enhancement, but have the potential to cause lost cached 959data on some networks, particularly WANs. 960</para> 961 962<para><programlisting> 963 MinLinkThroughput REG_DWORD 0 to infinite bytes per second 964 Default: 0 965</programlisting></para> 966 967<para> 968This specifies the minimum link throughput allowed by the server before it disables 969raw I/O and oplocks for this connection. 970</para> 971 972<para><programlisting> 973 MaxLinkDelay REG_DWORD 0 to 100,000 seconds 974 Default: 60 975</programlisting></para> 976 977<para> 978This specifies the maximum time allowed for a link delay. If delays exceed this number, 979the server disables raw I/O and oplocks for this connection. 980</para> 981 982<para><programlisting> 983 OplockBreakWait REG_DWORD 10 to 180 seconds 984 Default: 35 985</programlisting></para> 986 987<para> 988This specifies the time that the server waits for a client to respond to an oplock break 989request. Smaller values can allow detection of crashed clients more quickly but can 990potentially cause loss of cached data. 991</para> 992 993</sect2> 994</sect1> 995 996<sect1> 997<title>Persistent Data Corruption</title> 998 999<para> 1000If you have applied all of the settings discussed in this chapter but data corruption problems 1001and other symptoms persist, here are some additional things to check out. 1002</para> 1003 1004<para> 1005We have credible reports from developers that faulty network hardware, such as a single 1006faulty network card, can cause symptoms similar to read caching and data corruption. 1007If you see persistent data corruption even after repeated re-indexing, you may have to 1008rebuild the data files in question. This involves creating a new data file with the 1009same definition as the file to be rebuilt and transferring the data from the old file 1010to the new one. There are several known methods for doing this that can be found in 1011our knowledge base. 1012</para> 1013 1014</sect1> 1015 1016<sect1> 1017<title>Common Errors</title> 1018 1019<para> 1020In some sites locking problems surface as soon as a server is installed; in other sites 1021locking problems may not surface for a long time. Almost without exception, when a locking 1022problem does surface, it will cause embarrassment and potential data corruption. 1023</para> 1024 1025<para> 1026Over the past few years there have been a number of complaints on the Samba mailing lists 1027that have claimed that Samba caused data corruption. Three causes have been identified 1028so far: 1029</para> 1030 1031<itemizedlist> 1032 <listitem><para> 1033 Incorrect configuration of oplocks (incompatible with the application 1034 being used). This is a common problem even where MS Windows NT4 or MS Windows 1035 200x-based servers were in use. It is imperative that the software application vendors' 1036 instructions for configuration of file locking should be followed. If in doubt, 1037 disable oplocks on both the server and the client. Disabling of all forms of file 1038 caching on the MS Windows client may be necessary also. 1039 </para></listitem> 1040 1041 <listitem><para> 1042 Defective network cards, cables, or hubs/switches. This is generally a more 1043 prevalent factor with low-cost networking hardware, although occasionally there 1044 have also been problems with incompatibilities in more up-market hardware. 1045 </para></listitem> 1046 1047 <listitem><para> 1048 There have been some random reports of Samba log files being written over data 1049 files. This has been reported by very few sites (about five in the past 3 years) 1050 and all attempts to reproduce the problem have failed. The Samba Team has been 1051 unable to catch this happening and thus unable to isolate any particular 1052 cause. Considering the millions of systems that use Samba, for the sites that have 1053 been affected by this as well as for the Samba Team, this is a frustrating and 1054 vexing challenge. If you see this type of thing happening, please create a bug 1055 report on Samba <ulink url="https://bugzilla.samba.org">Bugzilla</ulink> without delay. 1056 Make sure that you give as much information as you possibly can to help isolate the 1057 cause and to allow replication of the problem (an essential step in problem isolation and correction). 1058 </para></listitem> 1059</itemizedlist> 1060 1061 <sect2> 1062 <title>locking.tdb Error Messages</title> 1063 1064 <para> 1065 <quote> 1066 We are seeing lots of errors in the Samba logs, like: 1067 </quote> 1068<programlisting> 1069tdb(/usr/local/samba_2.2.7/var/locks/locking.tdb): rec_read bad magic 1070 0x4d6f4b61 at offset=36116 1071</programlisting> 1072 1073 <quote> 1074 What do these mean? 1075 </quote> 1076 </para> 1077 1078 <para> 1079 This error indicates a corrupted tdb. Stop all instances of smbd, delete locking.tdb, and restart smbd. 1080 </para> 1081 1082 </sect2> 1083 1084 <sect2> 1085 <title>Problems Saving Files in MS Office on Windows XP</title> 1086 1087<indexterm><primary>KB 812937</primary></indexterm> 1088 <para>This is a bug in Windows XP. More information can be 1089 found in <ulink url="http://support.microsoft.com/?id=812937">Microsoft Knowledge Base article 812937</ulink></para>. 1090 1091 </sect2> 1092 1093 <sect2> 1094 <title>Long Delays Deleting Files over Network with XP SP1</title> 1095 1096 <para><quote>It sometimes takes approximately 35 seconds to delete files over the network after XP SP1 has been applied.</quote></para> 1097 1098<indexterm><primary>KB 811492</primary></indexterm> 1099 <para>This is a bug in Windows XP. More information can be found in <ulink url="http://support.microsoft.com/?id=811492"> 1100 Microsoft Knowledge Base article 811492</ulink></para>. 1101 </sect2> 1102 1103</sect1> 1104 1105<sect1> 1106<title>Additional Reading</title> 1107 1108<para> 1109You may want to check for an updated documentation regarding file and record locking issues on the Microsoft 1110<ulink url="http://support.microsoft.com/">Support</ulink> web site. Additionally, search for the word 1111<literal>locking</literal> on the Samba <ulink url="http://www.samba.org/">web</ulink> site. 1112</para> 1113 1114<para> 1115Section of the Microsoft MSDN Library on opportunistic locking: 1116</para> 1117 1118<para> 1119<indexterm><primary>KB 224992</primary></indexterm> 1120Microsoft Knowledge Base, <quote>Maintaining Transactional Integrity with OPLOCKS</quote>, 1121Microsoft Corporation, April 1999, <ulink noescape="1" url="http://support.microsoft.com/?id=224992">Microsoft 1122KB Article 224992</ulink>. 1123</para> 1124 1125<para> 1126<indexterm><primary>KB 296264</primary></indexterm> 1127Microsoft Knowledge Base, <quote>Configuring Opportunistic Locking in Windows 2000</quote>, 1128Microsoft Corporation, April 2001 <ulink noescape="1" url="http://support.microsoft.com/?id=296264">Microsoft KB Article 296264</ulink>. 1129</para> 1130 1131<para> 1132<indexterm><primary>KB 129202</primary></indexterm> 1133Microsoft Knowledge Base, <quote>PC Ext: Explanation of Opportunistic Locking on Windows NT</quote>, 1134Microsoft Corporation, April 1995 <ulink noescape="1" url="http://support.microsoft.com/?id=129202">Microsoft 1135KB Article 129202</ulink>. 1136</para> 1137 1138</sect1> 1139</chapter> 1140