1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
5 <!-- entities files to use -->
6 <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
11 <chapter id="locking">
18 <title>File and Record Locking</title>
21 One area that causes trouble for many network administrators is locking.
22 The extent of the problem is readily evident from searches over the Internet.
26 <title>Features and Benefits</title>
29 Samba provides all the same locking semantics that MS Windows clients expect
30 and that MS Windows NT4/200x servers also provide.
34 The term <emphasis>locking</emphasis> has exceptionally broad meaning and covers
35 a range of functions that are all categorized under this one term.
39 Opportunistic locking is a desirable feature when it can enhance the
40 perceived performance of applications on a networked client. However, the
41 opportunistic locking protocol is not robust and, therefore, can
42 encounter problems when invoked beyond a simplistic configuration or
43 on extended slow or faulty networks. In these cases, operating
44 system management of opportunistic locking and/or recovering from
45 repetitive errors can offset the perceived performance advantage that
46 it is intended to provide.
50 The MS Windows network administrator needs to be aware that file and record
51 locking semantics (behavior) can be controlled either in Samba or by way of registry
52 settings on the MS Windows client.
57 Sometimes it is necessary to disable locking control settings on both the Samba
58 server as well as on each MS Windows client!
65 <title>Discussion</title>
68 There are two types of locking that need to be performed by an SMB server.
69 The first is <emphasis>record locking</emphasis> that allows a client to lock
70 a range of bytes in a open file. The second is the <emphasis>deny modes</emphasis>
71 that are specified when a file is open.
75 Record locking semantics under UNIX are very different from record locking under
76 Windows. Versions of Samba before 2.2 have tried to use the native fcntl() UNIX
77 system call to implement proper record locking between different Samba clients.
78 This cannot be fully correct for several reasons. The simplest is the fact
79 that a Windows client is allowed to lock a byte range up to 2^32 or 2^64,
80 depending on the client OS. The UNIX locking only supports byte ranges up to 2^31.
81 So it is not possible to correctly satisfy a lock request above 2^31. There are
82 many more differences, too many to be listed here.
86 Samba 2.2 and above implements record locking completely independent of the
87 underlying UNIX system. If a byte range lock that the client requests happens
88 to fall into the range of 0-2^31, Samba hands this request down to the UNIX system.
89 All other locks cannot be seen by UNIX, anyway.
93 Strictly speaking, an SMB server should check for locks before every read and write call on
94 a file. Unfortunately with the way fcntl() works, this can be slow and may overstress
95 the <command>rpc.lockd</command>. This is almost always unnecessary as clients are supposed to
96 independently make locking calls before reads and writes if locking is
97 important to them. By default, Samba only makes locking calls when explicitly asked
98 to by a client, but if you set <smbconfoption><name>strict locking</name><value>yes</value></smbconfoption>, it
99 will make lock checking calls on <emphasis>every</emphasis> read and write call.
103 You can also disable byte range locking completely by using
104 <smbconfoption><name>locking</name><value>no</value></smbconfoption>.
105 This is useful for those shares that do not support locking or do not need it
106 (such as CDROMs). In this case, Samba fakes the return codes of locking calls to
107 tell clients that everything is okay.
111 The second class of locking is the <emphasis>deny modes</emphasis>. These
112 are set by an application when it opens a file to determine what types of
113 access should be allowed simultaneously with its open. A client may ask for
114 <constant>DENY_NONE</constant>, <constant>DENY_READ</constant>,
115 <constant>DENY_WRITE</constant>, or <constant>DENY_ALL</constant>. There are also special compatibility
116 modes called <constant>DENY_FCB</constant> and <constant>DENY_DOS</constant>.
120 <title>Opportunistic Locking Overview</title>
123 Opportunistic locking (Oplocks) is invoked by the Windows file system
124 (as opposed to an API) via registry entries (on the server and the client)
125 for the purpose of enhancing network performance when accessing a file
126 residing on a server. Performance is enhanced by caching the file
127 locally on the client that allows:
131 <varlistentry><term>Read-ahead:</term>
133 The client reads the local copy of the file, eliminating network latency.
137 <varlistentry><term>Write caching:</term>
139 The client writes to the local copy of the file, eliminating network latency.
143 <varlistentry><term>Lock caching:</term>
145 The client caches application locks locally, eliminating network latency.
151 The performance enhancement of oplocks is due to the opportunity of
152 exclusive access to the file &smbmdash; even if it is opened with deny-none &smbmdash;
153 because Windows monitors the file's status for concurrent access from
158 <title>Windows defines 4 kinds of Oplocks:</title>
160 <varlistentry><term>Level1 Oplock</term>
162 The redirector sees that the file was opened with deny
163 none (allowing concurrent access), verifies that no
164 other process is accessing the file, checks that
165 oplocks are enabled, then grants deny-all/read-write/exclusive
166 access to the file. The client now performs
167 operations on the cached local file.
171 If a second process attempts to open the file, the open
172 is deferred while the redirector <quote>breaks</quote> the original
173 oplock. The oplock break signals the caching client to
174 write the local file back to the server, flush the
175 local locks and discard read-ahead data. The break is
176 then complete, the deferred open is granted, and the
177 multiple processes can enjoy concurrent file access as
178 dictated by mandatory or byte-range locking options.
179 However, if the original opening process opened the
180 file with a share mode other than deny-none, then the
181 second process is granted limited or no access, despite
186 <varlistentry><term>Level2 Oplock</term>
188 Performs like a Level1 oplock, except caching is only
189 operative for reads. All other operations are performed
190 on the server disk copy of the file.
194 <varlistentry><term>Filter Oplock</term>
196 Does not allow write or delete file access.
200 <varlistentry><term>Batch Oplock</term>
202 Manipulates file openings and closings and allows caching
209 An important detail is that oplocks are invoked by the file system, not
210 an application API. Therefore, an application can close an oplocked
211 file, but the file system does not relinquish the oplock. When the
212 oplock break is issued, the file system then simply closes the file in
213 preparation for the subsequent open by the second process.
217 <emphasis>Opportunistic locking</emphasis> is actually an improper name for this feature.
218 The true benefit of this feature is client-side data caching, and
219 oplocks is merely a notification mechanism for writing data back to the
220 networked storage disk. The limitation of opportunistic locking is the
221 reliability of the mechanism to process an oplock break (notification)
222 between the server and the caching client. If this exchange is faulty
223 (usually due to timing out for any number of reasons), then the
224 client-side caching benefit is negated.
228 The actual decision that a user or administrator should consider is
229 whether it is sensible to share among multiple users data that will
230 be cached locally on a client. In many cases the answer is no.
231 Deciding when to cache or not cache data is the real question, and thus
232 <quote>opportunistic locking</quote> should be treated as a toggle for client-side
233 caching. Turn it <quote>on</quote> when client-side caching is desirable and
234 reliable. Turn it <quote>off</quote> when client-side caching is redundant,
235 unreliable or counter-productive.
239 Opportunistic locking is by default set to <quote>on</quote> by Samba on all
240 configured shares, so careful attention should be given to each case to
241 determine if the potential benefit is worth the potential for delays.
242 The following recommendations will help to characterize the environment
243 where opportunistic locking may be effectively configured.
247 Windows opportunistic locking is a lightweight performance-enhancing
248 feature. It is not a robust and reliable protocol. Every
249 implementation of opportunistic locking should be evaluated as a
250 tradeoff between perceived performance and reliability. Reliability
251 decreases as each successive rule above is not enforced. Consider a
252 share with oplocks enabled, over a wide area network, to a client on a
253 South Pacific atoll, on a high-availability server, serving a
254 mission-critical multi-user corporate database during a tropical
255 storm. This configuration will likely encounter problems with oplocks.
259 Oplocks can be beneficial to perceived client performance when treated
260 as a configuration toggle for client-side data caching. If the data
261 caching is likely to be interrupted, then oplock usage should be
262 reviewed. Samba enables opportunistic locking by default on all
263 shares. Careful attention should be given to the client usage of
264 shared data on the server, the server network reliability and the
265 opportunistic locking configuration of each share.
266 In mission critical high availability environments, data integrity is
267 often a priority. Complex and expensive configurations are implemented
268 to ensure that if a client loses connectivity with a file server, a
269 fail-over replacement will be available immediately to provide
270 continuous data availability.
274 Windows client fail-over behavior is more at risk of application
275 interruption than other platforms because it is dependent upon an
276 established TCP transport connection. If the connection is interrupted
277 &smbmdash; as in a file server fail-over &smbmdash; a new session must be established.
278 It is rare for Windows client applications to be coded to recover
279 correctly from a transport connection loss, therefore, most applications
280 will experience some sort of interruption &smbmdash; at worst, abort and
285 If a client session has been caching writes and reads locally due to
286 opportunistic locking, it is likely that the data will be lost when the
287 application restarts or recovers from the TCP interrupt. When the TCP
288 connection drops, the client state is lost. When the file server
289 recovers, an oplock break is not sent to the client. In this case, the
290 work from the prior session is lost. Observing this scenario with
291 oplocks disabled and with the client writing data to the file server
292 real-time, the fail-over will provide the data on disk as it
293 existed at the time of the disconnect.
297 In mission-critical high-availability environments, careful attention
298 should be given to opportunistic locking. Ideally, comprehensive
299 testing should be done with all affected applications with oplocks
300 enabled and disabled.
304 <title>Exclusively Accessed Shares</title>
307 Opportunistic locking is most effective when it is confined to shares
308 that are exclusively accessed by a single user, or by only one user at
309 a time. Because the true value of opportunistic locking is the local
310 client caching of data, any operation that interrupts the caching
311 mechanism will cause a delay.
315 Home directories are the most obvious examples of where the performance
316 benefit of opportunistic locking can be safely realized.
322 <title>Multiple-Accessed Shares or Files</title>
325 As each additional user accesses a file in a share with opportunistic
326 locking enabled, the potential for delays and resulting perceived poor
327 performance increases. When multiple users are accessing a file on a
328 share that has oplocks enabled, the management impact of sending and
329 receiving oplock breaks and the resulting latency while other clients
330 wait for the caching client to flush data offset the performance gains
335 As each additional client attempts to access a file with oplocks set,
336 the potential performance improvement is negated and eventually results
337 in a performance bottleneck.
343 <title>UNIX or NFS Client-Accessed Files</title>
346 Local UNIX and NFS clients access files without a mandatory
347 file-locking mechanism. Thus, these client platforms are incapable of
348 initiating an oplock break request from the server to a Windows client
349 that has a file cached. Local UNIX or NFS file access can therefore
350 write to a file that has been cached by a Windows client, which
351 exposes the file to likely data corruption.
355 If files are shared between Windows clients, and either local UNIX
356 or NFS users, turn opportunistic locking off.
362 <title>Slow and/or Unreliable Networks</title>
365 The biggest potential performance improvement for opportunistic locking
366 occurs when the client-side caching of reads and writes delivers the
367 most differential over sending those reads and writes over the wire.
368 This is most likely to occur when the network is extremely slow,
369 congested, or distributed (as in a WAN). However, network latency also
370 has a high impact on the reliability of the oplock break
371 mechanism, and thus increases the likelihood of encountering oplock
372 problems that more than offset the potential perceived performance
373 gain. Of course, if an oplock break never has to be sent, then this is
374 the most advantageous scenario to utilize opportunistic locking.
378 If the network is slow, unreliable, or a WAN, then do not configure
379 opportunistic locking if there is any chance of multiple users
380 regularly opening the same file.
386 <title>Multi-User Databases</title>
389 Multi-user databases clearly pose a risk due to their very nature &smbmdash;
390 they are typically heavily accessed by numerous users at random
391 intervals. Placing a multi-user database on a share with opportunistic
392 locking enabled will likely result in a locking management bottleneck
393 on the Samba server. Whether the database application is developed
394 in-house or a commercially available product, ensure that the share
395 has opportunistic locking disabled.
401 <title>PDM Data Shares</title>
404 Process Data Management (PDM) applications such as IMAN, Enovia and
405 Clearcase are increasing in usage with Windows client platforms, and
406 therefore SMB data-stores. PDM applications manage multi-user
407 environments for critical data security and access. The typical PDM
408 environment is usually associated with sophisticated client design
409 applications that will load data locally as demanded. In addition, the
410 PDM application will usually monitor the data-state of each client.
411 In this case, client-side data caching is best left to the local
412 application and PDM server to negotiate and maintain. It is
413 appropriate to eliminate the client OS from any caching tasks, and the
414 server from any oplock management, by disabling opportunistic locking on
421 <title>Beware of Force User</title>
424 Samba includes an &smb.conf; parameter called
425 <smbconfoption><name>force user</name></smbconfoption> that changes
426 the user accessing a share from the incoming user to whatever user is
427 defined by the smb.conf variable. If opportunistic locking is enabled
428 on a share, the change in user access causes an oplock break to be sent
429 to the client, even if the user has not explicitly loaded a file. In
430 cases where the network is slow or unreliable, an oplock break can
431 become lost without the user even accessing a file. This can cause
432 apparent performance degradation as the client continually reconnects
433 to overcome the lost oplock break.
437 Avoid the combination of the following:
442 <smbconfoption><name>force user</name></smbconfoption> in the &smb.conf; share configuration.
446 Slow or unreliable networks
450 Opportunistic locking enabled
457 <title>Advanced Samba Opportunistic Locking Parameters</title>
460 Samba provides opportunistic locking parameters that allow the
461 administrator to adjust various properties of the oplock mechanism to
462 account for timing and usage levels. These parameters provide good
463 versatility for implementing oplocks in environments where they would
464 likely cause problems. The parameters are:
465 <smbconfoption><name>oplock break wait time</name></smbconfoption>,
466 <smbconfoption><name>oplock contention limit</name></smbconfoption>.
470 For most users, administrators and environments, if these parameters
471 are required, then the better option is to simply turn oplocks off.
472 The Samba SWAT help text for both parameters reads: <quote>Do not change
473 this parameter unless you have read and understood the Samba oplock code.</quote>
480 <title>Mission-Critical High-Availability</title>
483 In mission-critical high-availability environments, data integrity is
484 often a priority. Complex and expensive configurations are implemented
485 to ensure that if a client loses connectivity with a file server, a
486 fail-over replacement will be available immediately to provide
487 continuous data availability.
491 Windows client fail-over behavior is more at risk of application
492 interruption than other platforms because it is dependant upon an
493 established TCP transport connection. If the connection is interrupted
494 &smbmdash; as in a file server fail-over &smbmdash; a new session must be established.
495 It is rare for Windows client applications to be coded to recover
496 correctly from a transport connection loss, therefore, most applications
497 will experience some sort of interruption &smbmdash; at worst, abort and
502 If a client session has been caching writes and reads locally due to
503 opportunistic locking, it is likely that the data will be lost when the
504 application restarts, or recovers from the TCP interrupt. When the TCP
505 connection drops, the client state is lost. When the file server
506 recovers, an oplock break is not sent to the client. In this case, the
507 work from the prior session is lost. Observing this scenario with
508 oplocks disabled, and the client was writing data to the file server
509 real-time, then the fail-over will provide the data on disk as it
510 existed at the time of the disconnect.
514 In mission-critical high-availability environments, careful attention
515 should be given to opportunistic locking. Ideally, comprehensive
516 testing should be done with all effected applications with oplocks
517 enabled and disabled.
525 <title>Samba Opportunistic Locking Control</title>
528 Opportunistic locking is a unique Windows file locking feature. It is
529 not really file locking, but is included in most discussions of Windows
530 file locking, so is considered a de facto locking feature.
531 Opportunistic locking is actually part of the Windows client file
532 caching mechanism. It is not a particularly robust or reliable feature
533 when implemented on the variety of customized networks that exist in
534 enterprise computing.
538 Like Windows, Samba implements opportunistic locking as a server-side
539 component of the client caching mechanism. Because of the lightweight
540 nature of the Windows feature design, effective configuration of
541 opportunistic locking requires a good understanding of its limitations,
542 and then applying that understanding when configuring data access for
543 each particular customized network and client usage state.
547 Opportunistic locking essentially means that the client is allowed to download and cache
548 a file on their hard drive while making changes; if a second client wants to access the
549 file, the first client receives a break and must synchronize the file back to the server.
550 This can give significant performance gains in some cases; some programs insist on
551 synchronizing the contents of the entire file back to the server for a single change.
555 Level1 Oplocks (also known as just plain <quote>oplocks</quote>) is another term for opportunistic locking.
559 Level2 Oplocks provides opportunistic locking for a file that will be treated as
560 <emphasis>read only</emphasis>. Typically this is used on files that are read-only or
561 on files that the client has no initial intention to write to at time of opening the file.
565 Kernel Oplocks are essentially a method that allows the Linux kernel to co-exist with
566 Samba's oplocked files, although this has provided better integration of MS Windows network
567 file locking with the underlying OS, SGI IRIX and Linux are the only two OSs that are
568 oplock-aware at this time.
572 Unless your system supports kernel oplocks, you should disable oplocks if you are
573 accessing the same files from both UNIX/Linux and SMB clients. Regardless, oplocks should
574 always be disabled if you are sharing a database file (e.g., Microsoft Access) between
575 multiple clients, as any break the first client receives will affect synchronization of
576 the entire file (not just the single record), which will result in a noticeable performance
577 impairment and, more likely, problems accessing the database in the first place. Notably,
578 Microsoft Outlook's personal folders (*.pst) react quite badly to oplocks. If in doubt,
579 disable oplocks and tune your system from that point.
583 If client-side caching is desirable and reliable on your network, you will benefit from
584 turning on oplocks. If your network is slow and/or unreliable, or you are sharing your
585 files among other file sharing mechanisms (e.g., NFS) or across a WAN, or multiple people
586 will be accessing the same files frequently, you probably will not benefit from the overhead
587 of your client sending oplock breaks and will instead want to disable oplocks for the share.
591 Another factor to consider is the perceived performance of file access. If oplocks provide no
592 measurable speed benefit on your network, it might not be worth the hassle of dealing with them.
596 <title>Example Configuration</title>
599 In the following section we examine two distinct aspects of Samba locking controls.
603 <title>Disabling Oplocks</title>
606 You can disable oplocks on a per-share basis with the following:
611 <smbconfsection>[acctdata]</smbconfsection>
612 <smbconfoption><name>oplocks</name><value>False</value></smbconfoption>
613 <smbconfoption><name>level2 oplocks</name><value>False</value></smbconfoption>
618 The default oplock type is Level1. Level2 oplocks are enabled on a per-share basis
619 in the &smb.conf; file.
623 Alternately, you could disable oplocks on a per-file basis within the share:
628 <smbconfoption><name>veto oplock files</name><value>/*.mdb/*.MDB/*.dbf/*.DBF/</value></smbconfoption>
633 If you are experiencing problems with oplocks as apparent from Samba's log entries,
634 you may want to play it safe and disable oplocks and Level2 oplocks.
640 <title>Disabling Kernel Oplocks</title>
643 Kernel oplocks is an &smb.conf; parameter that notifies Samba (if
644 the UNIX kernel has the capability to send a Windows client an oplock
645 break) when a UNIX process is attempting to open the file that is
646 cached. This parameter addresses sharing files between UNIX and
647 Windows with oplocks enabled on the Samba server: the UNIX process
648 can open the file that is Oplocked (cached) by the Windows client and
649 the smbd process will not send an oplock break, which exposes the file
650 to the risk of data corruption. If the UNIX kernel has the ability to
651 send an oplock break, then the kernel oplocks parameter enables Samba
652 to send the oplock break. Kernel oplocks are enabled on a per-server
653 basis in the &smb.conf; file.
658 <smbconfoption><name>kernel oplocks</name><value>yes</value></smbconfoption>
664 Veto opLocks is an &smb.conf; parameter that identifies specific files for
665 which oplocks are disabled. When a Windows client opens a file that
666 has been configured for veto oplocks, the client will not be granted
667 the oplock, and all operations will be executed on the original file on
668 disk instead of a client-cached file copy. By explicitly identifying
669 files that are shared with UNIX processes and disabling oplocks for
670 those files, the server-wide Oplock configuration can be enabled to
671 allow Windows clients to utilize the performance benefit of file
672 caching without the risk of data corruption. Veto Oplocks can be
673 enabled on a per-share basis, or globally for the entire server, in the
674 &smb.conf; file as shown in <link linkend="far1"/>.
678 <smbconfexample id="far1">
679 <title>Share with some files oplocked</title>
680 <smbconfsection>[global]</smbconfsection>
681 <smbconfoption><name>veto oplock files</name><value>/filename.htm/*.txt/</value></smbconfoption>
683 <smbconfsection>[share_name]</smbconfsection>
684 <smbconfoption><name>veto oplock files</name><value>/*.exe/filename.ext/</value></smbconfoption>
689 <smbconfoption><name>oplock break wait time</name></smbconfoption> is an &smb.conf; parameter
690 that adjusts the time interval for Samba to reply to an oplock break request. Samba recommends:
691 <quote>Do not change this parameter unless you have read and understood the Samba oplock code.</quote>
692 Oplock break Wait Time can only be configured globally in the &smb.conf; file as shown below.
697 <smbconfoption><name>oplock break wait time</name><value> 0 (default)</value></smbconfoption>
702 <emphasis>Oplock break contention limit</emphasis> is an &smb.conf; parameter that limits the
703 response of the Samba server to grant an oplock if the configured
704 number of contending clients reaches the limit specified by the parameter. Samba recommends
705 <quote>Do not change this parameter unless you have read and understood the Samba oplock code.</quote>
706 Oplock break Contention Limit can be enable on a per-share basis, or globally for
707 the entire server, in the &smb.conf; file as shown in <link linkend="far3"/>.
711 <smbconfexample id="far3">
712 <title>Configuration with oplock break contention limit</title>
713 <smbconfsection>[global]</smbconfsection>
714 <smbconfoption><name>oplock break contention limit</name><value> 2 (default)</value></smbconfoption>
716 <smbconfsection>[share_name]</smbconfsection>
717 <smbconfoption><name>oplock break contention limit</name><value> 2 (default)</value></smbconfoption>
727 <title>MS Windows Opportunistic Locking and Caching Controls</title>
730 There is a known issue when running applications (like Norton Anti-Virus) on a Windows 2000/ XP
731 workstation computer that can affect any application attempting to access shared database files
732 across a network. This is a result of a default setting configured in the Windows 2000/XP
733 operating system known as <emphasis>opportunistic locking</emphasis>. When a workstation
734 attempts to access shared data files located on another Windows 2000/XP computer,
735 the Windows 2000/XP operating system will attempt to increase performance by locking the
736 files and caching information locally. When this occurs, the application is unable to
737 properly function, which results in an <quote>Access Denied</quote>
738 error message being displayed during network operations.
742 All Windows operating systems in the NT family that act as database servers for data files
743 (meaning that data files are stored there and accessed by other Windows PCs) may need to
744 have opportunistic locking disabled in order to minimize the risk of data file corruption.
745 This includes Windows 9x/Me, Windows NT, Windows 200x, and Windows XP.
746 <footnote><para>Microsoft has documented this in Knowledge Base article 300216.</para></footnote>
750 If you are using a Windows NT family workstation in place of a server, you must also
751 disable opportunistic locking (oplocks) on that workstation. For example, if you use a
752 PC with the Windows NT Workstation operating system instead of Windows NT Server, and you
753 have data files located on it that are accessed from other Windows PCs, you may need to
754 disable oplocks on that system.
758 The major difference is the location in the Windows registry where the values for disabling
759 oplocks are entered. Instead of the LanManServer location, the LanManWorkstation location
764 You can verify (change or add, if necessary) this registry value using the Windows
765 Registry Editor. When you change this registry value, you will have to reboot the PC
766 to ensure that the new setting goes into effect.
770 The location of the client registry entry for opportunistic locking has changed in
771 Windows 2000 from the earlier location in Microsoft Windows NT.
775 Windows 2000 will still respect the EnableOplocks registry value used to disable oplocks
776 in earlier versions of Windows.
780 You can also deny the granting of opportunistic locks by changing the following registry entries:
785 HKEY_LOCAL_MACHINE\System\
786 CurrentControlSet\Services\MRXSmb\Parameters\
788 OplocksDisabled REG_DWORD 0 or 1
789 Default: 0 (not disabled)
794 The OplocksDisabled registry value configures Windows clients to either request or not
795 request opportunistic locks on a remote file. To disable oplocks, the value of
796 OplocksDisabled must be set to 1.
801 HKEY_LOCAL_MACHINE\System\
802 CurrentControlSet\Services\LanmanServer\Parameters
804 EnableOplocks REG_DWORD 0 or 1
805 Default: 1 (Enabled by Default)
807 EnableOpLockForceClose REG_DWORD 0 or 1
808 Default: 0 (Disabled by Default)
813 The EnableOplocks value configures Windows-based servers (including Workstations sharing
814 files) to allow or deny opportunistic locks on local files.
818 To force closure of open oplocks on close or program exit, EnableOpLockForceClose must be set to 1.
822 An illustration of how Level2 oplocks work:
827 Station 1 opens the file requesting oplock.
830 Since no other station has the file open, the server grants station 1 exclusive oplock.
833 Station 2 opens the file requesting oplock.
836 Since station 1 has not yet written to the file, the server asks station 1 to break
840 Station 1 complies by flushing locally buffered lock information to the server.
843 Station 1 informs the server that it has Broken to Level2 Oplock (alternately,
844 station 1 could have closed the file).
847 The server responds to station 2's open request, granting it Level2 oplock.
848 Other stations can likewise open the file and obtain Level2 oplock.
851 Station 2 (or any station that has the file open) sends a write request SMB.
852 The server returns the write response.
855 The server asks all stations that have the file open to break to none, meaning no
856 station holds any oplock on the file. Because the workstations can have no cached
857 writes or locks at this point, they need not respond to the break-to-none advisory;
858 all they need do is invalidate locally cashed read-ahead data.
863 <title>Workstation Service Entries</title>
865 <para><programlisting>
866 \HKEY_LOCAL_MACHINE\System\
867 CurrentControlSet\Services\LanmanWorkstation\Parameters
869 UseOpportunisticLocking REG_DWORD 0 or 1
871 </programlisting></para>
874 This indicates whether the redirector should use opportunistic-locking (oplock) performance
875 enhancement. This parameter should be disabled only to isolate problems.
880 <title>Server Service Entries</title>
882 <para><programlisting>
883 \HKEY_LOCAL_MACHINE\System\
884 CurrentControlSet\Services\LanmanServer\Parameters
886 EnableOplocks REG_DWORD 0 or 1
888 </programlisting></para>
891 This specifies whether the server allows clients to use oplocks on files. Oplocks are a
892 significant performance enhancement, but have the potential to cause lost cached
893 data on some networks, particularly wide area networks.
896 <para><programlisting>
897 MinLinkThroughput REG_DWORD 0 to infinite bytes per second
899 </programlisting></para>
902 This specifies the minimum link throughput allowed by the server before it disables
903 raw and opportunistic locks for this connection.
906 <para><programlisting>
907 MaxLinkDelay REG_DWORD 0 to 100,000 seconds
909 </programlisting></para>
912 This specifies the maximum time allowed for a link delay. If delays exceed this number,
913 the server disables raw I/O and opportunistic locking for this connection.
916 <para><programlisting>
917 OplockBreakWait REG_DWORD 10 to 180 seconds
919 </programlisting></para>
922 This specifies the time that the server waits for a client to respond to an oplock break
923 request. Smaller values can allow detection of crashed clients more quickly but can
924 potentially cause loss of cached data.
931 <title>Persistent Data Corruption</title>
934 If you have applied all of the settings discussed in this chapter but data corruption problems
935 and other symptoms persist, here are some additional things to check out.
939 We have credible reports from developers that faulty network hardware, such as a single
940 faulty network card, can cause symptoms similar to read caching and data corruption.
941 If you see persistent data corruption even after repeated re-indexing, you may have to
942 rebuild the data files in question. This involves creating a new data file with the
943 same definition as the file to be rebuilt and transferring the data from the old file
944 to the new one. There are several known methods for doing this that can be found in
951 <title>Common Errors</title>
954 In some sites, locking problems surface as soon as a server is installed; in other sites
955 locking problems may not surface for a long time. Almost without exception, when a locking
956 problem does surface it will cause embarrassment and potential data corruption.
960 Over the past few years there have been a number of complaints on the Samba mailing lists
961 that have claimed that Samba caused data corruption. Three causes have been identified
967 Incorrect configuration of opportunistic locking (incompatible with the application
968 being used. This is a common problem even where MS Windows NT4 or MS Windows
969 200x-based servers were in use. It is imperative that the software application vendors'
970 instructions for configuration of file locking should be followed. If in doubt,
971 disable oplocks on both the server and the client. Disabling of all forms of file
972 caching on the MS Windows client may be necessary also.
976 Defective network cards, cables, or HUBs/Switched. This is generally a more
977 prevalent factor with low cost networking hardware, although occasionally there
978 have also been problems with incompatibilities in more up-market hardware.
982 There have been some random reports of Samba log files being written over data
983 files. This has been reported by very few sites (about five in the past three years)
984 and all attempts to reproduce the problem have failed. The Samba Team has been
985 unable to catch this happening and thus has not been able to isolate any particular
986 cause. Considering the millions of systems that use Samba, for the sites that have
987 been affected by this as well as for the Samba Team this is a frustrating and
988 a vexing challenge. If you see this type of thing happening, please create a bug
989 report on Samba <ulink url="https://bugzilla.samba.org">Bugzilla</ulink> without delay.
990 Make sure that you give as much information as you possibly can help isolate the
991 cause and to allow replication of the problem (an essential step in problem isolation and correction).
996 <title>locking.tdb Error Messages</title>
1000 We are seeing lots of errors in the Samba logs, like:
1002 tdb(/usr/local/samba_2.2.7/var/locks/locking.tdb): rec_read bad magic
1003 0x4d6f4b61 at offset=36116
1011 This error indicated a corrupted tdb. Stop all instances of smbd, delete locking.tdb, and restart smbd.
1017 <title>Problems Saving Files in MS Office on Windows XP</title>
1019 <para>This is a bug in Windows XP. More information can be
1020 found in <ulink url="http://support.microsoft.com/?id=812937">Microsoft Knowledge Base article 812937.</ulink></para>
1026 <title>Long Delays Deleting Files Over Network with XP SP1</title>
1028 <para><quote>It sometimes takes approximately 35 seconds to delete files over the network after XP SP1 has been applied.</quote></para>
1030 <para>This is a bug in Windows XP. More information can be found in <ulink url="http://support.microsoft.com/?id=811492">
1031 Microsoft Knowledge Base article 811492.</ulink></para>
1037 <title>Additional Reading</title>
1040 You may want to check for an updated version of this white paper on our Web site from
1041 time to time. Many of our white papers are updated as information changes. For those papers,
1042 the last edited date is always at the top of the paper.
1046 Section of the Microsoft MSDN Library on opportunistic locking:
1050 Opportunistic Locks, Microsoft Developer Network (MSDN), Windows Development >
1051 Windows Base Services > Files and I/O > SDK Documentation > File Storage > File Systems
1052 > About File Systems > Opportunistic Locks, Microsoft Corporation.
1053 <ulink noescape="1" url="http://msdn.microsoft.com/library/en-us/fileio/storage_5yk3.asp">http://msdn.microsoft.com/library/en-us/fileio/storage_5yk3.asp</ulink>
1057 Microsoft Knowledge Base Article Q224992 <?latex \linebreak ?><quote>Maintaining Transactional Integrity
1058 with OPLOCKS</quote>,
1059 Microsoft Corporation, April 1999, <ulink noescape="1" url="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q224992">http://support.microsoft.com/default.aspx?scid=kb;en-us;Q224992</ulink>.
1063 Microsoft Knowledge Base Article Q296264 <quote>Configuring Opportunistic Locking in Windows 2000</quote>,
1064 Microsoft Corporation, April 2001, <ulink noescape="1" url="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q296264">http://support.microsoft.com/default.aspx?scid=kb;en-us;Q296264</ulink>.
1068 Microsoft Knowledge Base Article Q129202 <quote>PC Ext: Explanation of Opportunistic Locking on Windows NT</quote>,
1069 Microsoft Corporation, April 1995, <ulink noescape="1" url="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q129202">http://support.microsoft.com/default.aspx?scid=kb;en-us;Q129202</ulink>.