• Home
  • History
  • Annotate
  • Line#
  • Navigate
  • Raw
  • Download
  • only in /asuswrt-rt-n18u-9.0.0.4.380.2695/release/src/router/samba-3.5.8/docs-xml/Samba3-HOWTO/
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