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