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">
10
<title>File and Record Locking</title>
13
<indexterm><primary>locking</primary></indexterm>
14
One area that causes trouble for many network administrators is locking.
15
The extent of the problem is readily evident from searches over the Internet.
19
<title>Features and Benefits</title>
22
<indexterm><primary>locking semantics</primary></indexterm>
23
Samba provides all the same locking semantics that MS Windows clients expect
24
and that MS Windows NT4/200x servers also provide.
28
<indexterm><primary>locking</primary></indexterm>
29
The term <emphasis>locking</emphasis> has exceptionally broad meaning and covers
30
a range of functions that are all categorized under this one term.
34
<indexterm><primary>opportunistic locking</primary></indexterm>
35
<indexterm><primary>locking protocol</primary></indexterm>
36
<indexterm><primary>performance advantage</primary></indexterm>
37
Opportunistic locking is a desirable feature when it can enhance the
38
perceived performance of applications on a networked client. However, the
39
opportunistic locking protocol is not robust and therefore can
40
encounter problems when invoked beyond a simplistic configuration or
41
on extended slow or faulty networks. In these cases, operating
42
system management of opportunistic locking and/or recovering from
43
repetitive errors can offset the perceived performance advantage that
44
it is intended to provide.
48
<indexterm><primary>registry</primary></indexterm>
49
The MS Windows network administrator needs to be aware that file and record
50
locking semantics (behavior) can be controlled either in Samba or by way of registry
51
settings on the MS Windows client.
56
<indexterm><primary>disable locking</primary></indexterm>
57
Sometimes it is necessary to disable locking control settings on the Samba
58
server as well as on each MS Windows client!
65
<title>Discussion</title>
68
<indexterm><primary>record locking</primary></indexterm>
69
<indexterm><primary>deny modes</primary></indexterm>
70
There are two types of locking that need to be performed by an SMB server.
71
The first is <emphasis>record locking</emphasis> that allows a client to lock
72
a range of bytes in an open file. The second is the <emphasis>deny modes</emphasis>
73
that are specified when a file is open.
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>
82
Record locking semantics under UNIX are very different from record locking under
83
Windows. Versions of Samba before 2.2 have tried to use the native fcntl() UNIX
84
system call to implement proper record locking between different Samba clients.
85
This cannot be fully correct for several reasons. The simplest is
86
that a Windows client is allowed to lock a byte range up to 2^32 or 2^64,
87
depending on the client OS. The UNIX locking only supports byte ranges up to 2^31.
88
So it is not possible to correctly satisfy a lock request above 2^31. There are
89
many more differences, too many to be listed here.
93
<indexterm><primary>record locking</primary></indexterm>
94
<indexterm><primary>byte-range lock</primary></indexterm>
95
Samba 2.2 and above implement record locking completely independently of the
96
underlying UNIX system. If a byte-range lock that the client requests happens
97
to fall into the range of 0 to 2^31, Samba hands this request down to the UNIX system.
98
No other locks can be seen by UNIX, anyway.
102
<indexterm><primary>check for locks</primary></indexterm>
103
<indexterm><primary>rpc.lockd</primary></indexterm>
104
Strictly speaking, an SMB server should check for locks before every read and write call on
105
a file. Unfortunately, with the way fcntl() works, this can be slow and may overstress
106
the <command>rpc.lockd</command>. This is almost always unnecessary because clients are
107
independently supposed to make locking calls before reads and writes if locking is
108
important to them. By default, Samba only makes locking calls when explicitly asked
109
to by a client, but if you set <smbconfoption name="strict locking">yes</smbconfoption>, it
110
will make lock checking calls on <emphasis>every</emphasis> read and write call.
114
<indexterm><primary>byte-range locking</primary></indexterm>
115
You can also disable byte-range locking completely by using
116
<smbconfoption name="locking">no</smbconfoption>.
117
This 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
119
tell clients that everything is okay.
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>
130
The second class of locking is the <emphasis>deny modes</emphasis>. These
131
are set by an application when it opens a file to determine what types of
132
access 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
135
modes called <constant>DENY_FCB</constant> and <constant>DENY_DOS</constant>.
139
<title>Opportunistic Locking Overview</title>
142
<indexterm><primary>opportunistic locking</primary></indexterm>
143
<indexterm><primary>oplocks</primary></indexterm>
144
<indexterm><primary>caching</primary></indexterm>
145
Opportunistic locking (oplocks) is invoked by the Windows file system
146
(as opposed to an API) via registry entries (on the server and the client)
147
for the purpose of enhancing network performance when accessing a file
148
residing on a server. Performance is enhanced by caching the file
149
locally on the client that allows the following:
153
<varlistentry><term>Read-ahead:</term>
155
<indexterm><primary>Read-ahead</primary></indexterm>
156
The client reads the local copy of the file, eliminating network latency.
160
<varlistentry><term>Write caching:</term>
162
<indexterm><primary>Write caching</primary></indexterm>
163
The client writes to the local copy of the file, eliminating network latency.
167
<varlistentry><term>Lock caching:</term>
169
<indexterm><primary>Lock caching</primary></indexterm>
170
The client caches application locks locally, eliminating network latency.
176
<indexterm><primary>performance enhancement</primary></indexterm>
177
<indexterm><primary>oplocks</primary></indexterm>
178
<indexterm><primary>deny-none</primary></indexterm>
179
The performance enhancement of oplocks is due to the opportunity of
180
exclusive access to the file &smbmdash; even if it is opened with deny-none &smbmdash;
181
because Windows monitors the file's status for concurrent access from
186
<title>Windows Defines Four Kinds of Oplocks:</title>
188
<varlistentry><term>Level1 Oplock</term>
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.
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
222
<varlistentry><term>Level2 Oplock</term>
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.
233
<varlistentry><term>Filter Oplock</term>
235
<indexterm><primary>Filter Oplock</primary></indexterm>
236
Does not allow write or delete file access.
240
<varlistentry><term>Batch Oplock</term>
242
<indexterm><primary>Batch Oplock</primary></indexterm>
243
Manipulates file openings and closings and allows caching
250
<indexterm><primary>oplocks</primary></indexterm>
251
An important detail is that oplocks are invoked by the file system, not
252
an application API. Therefore, an application can close an oplocked
253
file, but the file system does not relinquish the oplock. When the
254
oplock break is issued, the file system then simply closes the file in
255
preparation for the subsequent open by the second process.
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.
264
The true benefit of this feature is client-side data caching, and
265
oplocks is merely a notification mechanism for writing data back to the
266
networked storage disk. The limitation of oplocks is the
267
reliability of the mechanism to process an oplock break (notification)
268
between the server and the caching client. If this exchange is faulty
269
(usually due to timing out for any number of reasons), then the
270
client-side caching benefit is negated.
274
<indexterm><primary>client-side caching</primary></indexterm>
275
The actual decision that a user or administrator should consider is
276
whether it is sensible to share among multiple users data that will
277
be cached locally on a client. In many cases the answer is no.
278
Deciding when to cache or not cache data is the real question, and thus
279
oplocks should be treated as a toggle for client-side
280
caching. Turn it <quote>on</quote> when client-side caching is desirable and
281
reliable. Turn it <quote>off</quote> when client-side caching is redundant,
282
unreliable, or counterproductive.
286
<indexterm><primary>oplocks</primary></indexterm>
287
Oplocks is by default set to <quote>on</quote> by Samba on all
288
configured shares, so careful attention should be given to each case to
289
determine if the potential benefit is worth the potential for delays.
290
The following recommendations will help to characterize the environment
291
where oplocks may be effectively configured.
295
<indexterm><primary>oplocks</primary></indexterm>
296
<indexterm><primary>high-availability</primary></indexterm>
297
Windows oplocks is a lightweight performance-enhancing
298
feature. It is not a robust and reliable protocol. Every
299
implementation of oplocks should be evaluated as a
300
trade-off between perceived performance and reliability. Reliability
301
decreases as each successive rule above is not enforced. Consider a
302
share with oplocks enabled, over a wide-area network, to a client on a
303
South Pacific atoll, on a high-availability server, serving a
304
mission-critical multiuser corporate database during a tropical
305
storm. This configuration will likely encounter problems with oplocks.
309
<indexterm><primary>mission-critical</primary></indexterm>
310
Oplocks can be beneficial to perceived client performance when treated
311
as a configuration toggle for client-side data caching. If the data
312
caching is likely to be interrupted, then oplock usage should be
313
reviewed. Samba enables oplocks by default on all
314
shares. Careful attention should be given to the client usage of
315
shared data on the server, the server network reliability, and the
316
oplocks configuration of each share.
317
In mission-critical, high-availability environments, data integrity is
318
often a priority. Complex and expensive configurations are implemented
319
to ensure that if a client loses connectivity with a file server, a
320
failover replacement will be available immediately to provide
321
continuous data availability.
325
<indexterm><primary>Windows client failover</primary></indexterm>
326
<indexterm><primary>transport connection loss</primary></indexterm>
327
Windows client failover behavior is more at risk of application
328
interruption than other platforms because it is dependent upon an
329
established TCP transport connection. If the connection is interrupted
330
&smbmdash; as in a file server failover &smbmdash; a new session must be established.
331
It is rare for Windows client applications to be coded to recover
332
correctly from a transport connection loss; therefore, most applications
333
will experience some sort of interruption &smbmdash; at worst, abort and
338
<indexterm><primary>caching writes</primary></indexterm>
339
<indexterm><primary>caching reads</primary></indexterm>
340
<indexterm><primary>oplock break</primary></indexterm>
341
If a client session has been caching writes and reads locally due to
342
oplocks, it is likely that the data will be lost when the
343
application restarts or recovers from the TCP interrupt. When the TCP
344
connection drops, the client state is lost. When the file server
345
recovers, an oplock break is not sent to the client. In this case, the
346
work from the prior session is lost. Observing this scenario with
347
oplocks disabled and with the client writing data to the file server
348
real-time, the failover will provide the data on disk as it
349
existed at the time of the disconnect.
353
In mission-critical, high-availability environments, careful attention
354
should be given to oplocks. Ideally, comprehensive
355
testing should be done with all affected applications with oplocks
356
enabled and disabled.
360
<title>Exclusively Accessed Shares</title>
363
Oplocks is most effective when it is confined to shares
364
that are exclusively accessed by a single user, or by only one user at
365
a time. Because the true value of oplocks is the local
366
client caching of data, any operation that interrupts the caching
367
mechanism will cause a delay.
371
Home directories are the most obvious examples of where the performance
372
benefit of oplocks can be safely realized.
378
<title>Multiple-Accessed Shares or Files</title>
381
As each additional user accesses a file in a share with oplocks
382
enabled, the potential for delays and resulting perceived poor
383
performance increases. When multiple users are accessing a file on a
384
share that has oplocks enabled, the management impact of sending and
385
receiving oplock breaks and the resulting latency while other clients
386
wait for the caching client to flush data offset the performance gains
391
As each additional client attempts to access a file with oplocks set,
392
the potential performance improvement is negated and eventually results
393
in a performance bottleneck.
399
<title>UNIX or NFS Client-Accessed Files</title>
402
<indexterm><primary>NFS clients</primary></indexterm>
403
<indexterm><primary>data corruption</primary></indexterm>
404
Local UNIX and NFS clients access files without a mandatory
405
file-locking mechanism. Thus, these client platforms are incapable of
406
initiating an oplock break request from the server to a Windows client
407
that has a file cached. Local UNIX or NFS file access can therefore
408
write to a file that has been cached by a Windows client, which
409
exposes the file to likely data corruption.
413
If files are shared between Windows clients and either local UNIX
414
or NFS users, turn oplocks off.
420
<title>Slow and/or Unreliable Networks</title>
423
<indexterm><primary>performance improvement</primary></indexterm>
424
<indexterm><primary>WAN</primary></indexterm>
425
<indexterm><primary>latency</primary></indexterm>
426
The biggest potential performance improvement for oplocks
427
occurs when the client-side caching of reads and writes delivers the
428
most differential over sending those reads and writes over the wire.
429
This is most likely to occur when the network is extremely slow,
430
congested, or distributed (as in a WAN). However, network latency also
431
has a high impact on the reliability of the oplock break
432
mechanism, and thus increases the likelihood of encountering oplock
433
problems that more than offset the potential perceived performance
434
gain. Of course, if an oplock break never has to be sent, then this is
435
the most advantageous scenario in which to utilize oplocks.
439
If the network is slow, unreliable, or a WAN, then do not configure
440
oplocks if there is any chance of multiple users
441
regularly opening the same file.
447
<title>Multiuser Databases</title>
450
<indexterm><primary>Multiuser databases</primary></indexterm>
451
<indexterm><primary>management bottleneck</primary></indexterm>
452
<indexterm><primary>oplocks disabled</primary></indexterm>
453
Multiuser databases clearly pose a risk due to their very nature &smbmdash; they are typically heavily
454
accessed by numerous users at random intervals. Placing a multiuser database on a share with oplocks enabled
455
will likely result in a locking management bottleneck on the Samba server. Whether the database application is
456
developed in-house or a commercially available product, ensure that the share has oplocks disabled.
462
<title>PDM Data Shares</title>
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>
470
Process data management (PDM) applications such as IMAN, Enovia, and Clearcase are increasing in usage with
471
Windows client platforms and therefore with SMB datastores. PDM applications manage multiuser environments for
472
critical data security and access. The typical PDM environment is usually associated with sophisticated client
473
design applications that will load data locally as demanded. In addition, the PDM application will usually
474
monitor the data state of each client. In this case, client-side data caching is best left to the local
475
application and PDM server to negotiate and maintain. It is appropriate to eliminate the client OS from any
476
caching tasks, and the server from any oplocks management, by disabling oplocks on the share.
482
<title>Beware of Force User</title>
485
<indexterm><primary>oplock break</primary></indexterm>
486
Samba includes an &smb.conf; parameter called <smbconfoption name="force user"/> that changes the user
487
accessing a share from the incoming user to whatever user is defined by the &smb.conf; variable. If oplocks is
488
enabled on a share, the change in user access causes an oplock break to be sent to the client, even if the
489
user has not explicitly loaded a file. In cases where the network is slow or unreliable, an oplock break can
490
become lost without the user even accessing a file. This can cause apparent performance degradation as the
491
client continually reconnects to overcome the lost oplock break.
495
Avoid the combination of the following:
500
<smbconfoption name="force user"/> in the &smb.conf; share configuration.
504
Slow or unreliable networks.
515
<title>Advanced Samba Oplocks Parameters</title>
518
<indexterm><primary>oplock parameters</primary></indexterm>
519
<indexterm><primary>oplock mechanism</primary></indexterm>
520
<indexterm><primary>implementing oplocks</primary></indexterm>
521
Samba provides oplock parameters that allow the
522
administrator to adjust various properties of the oplock mechanism to
523
account for timing and usage levels. These parameters provide good
524
versatility for implementing oplocks in environments where they would
525
likely cause problems. The parameters are
526
<smbconfoption name="oplock break wait time"/>, and
527
<smbconfoption name="oplock contention limit"/>.
531
<indexterm><primary>turn oplocks off</primary></indexterm>
532
For most users, administrators, and environments, if these parameters
533
are required, then the better option is simply to turn oplocks off.
534
The Samba SWAT help text for both parameters reads: <quote>Do not change
535
this parameter unless you have read and understood the Samba oplock code.</quote>
542
<title>Mission-Critical, High-Availability</title>
545
In mission-critical, high-availability environments, data integrity is
546
often a priority. Complex and expensive configurations are implemented
547
to ensure that if a client loses connectivity with a file server, a
548
failover replacement will be available immediately to provide
549
continuous data availability.
553
Windows client failover behavior is more at risk of application
554
interruption than other platforms because it is dependent upon an
555
established TCP transport connection. If the connection is interrupted
556
&smbmdash; as in a file server failover &smbmdash; a new session must be established.
557
It is rare for Windows client applications to be coded to recover
558
correctly from a transport connection loss; therefore, most applications
559
will experience some sort of interruption &smbmdash; at worst, abort and
564
If a client session has been caching writes and reads locally due to
565
oplocks, it is likely that the data will be lost when the
566
application restarts or recovers from the TCP interrupt. When the TCP
567
connection drops, the client state is lost. When the file server
568
recovers, an oplock break is not sent to the client. In this case, the
569
work from the prior session is lost. Observing this scenario with
570
oplocks disabled, if the client was writing data to the file server
571
real-time, then the failover will provide the data on disk as it
572
existed at the time of the disconnect.
576
In mission-critical, high-availability environments, careful attention
577
should be given to oplocks. Ideally, comprehensive
578
testing should be done with all affected applications with oplocks
579
enabled and disabled.
587
<title>Samba Oplocks Control</title>
590
Oplocks is a unique Windows file locking feature. It is
591
not really file locking, but is included in most discussions of Windows
592
file locking, so is considered a de facto locking feature.
593
Oplocks is actually part of the Windows client file
594
caching mechanism. It is not a particularly robust or reliable feature
595
when implemented on the variety of customized networks that exist in
596
enterprise computing.
600
Like Windows, Samba implements oplocks as a server-side
601
component of the client caching mechanism. Because of the lightweight
602
nature of the Windows feature design, effective configuration of
603
oplocks requires a good understanding of its limitations,
604
and then applying that understanding when configuring data access for
605
each particular customized network and client usage state.
609
Oplocks essentially means that the client is allowed to download and cache
610
a file on its hard drive while making changes; if a second client wants to access the
611
file, the first client receives a break and must synchronize the file back to the server.
612
This can give significant performance gains in some cases; some programs insist on
613
synchronizing the contents of the entire file back to the server for a single change.
617
Level1 Oplocks (also known as just plain <quote>oplocks</quote>) is another term for opportunistic locking.
621
Level2 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
623
on files that the client has no initial intention to write to at time of opening the file.
627
Kernel Oplocks are essentially a method that allows the Linux kernel to co-exist with
628
Samba's oplocked files, although this has provided better integration of MS Windows network
629
file locking with the underlying OS. SGI IRIX and Linux are the only two OSs that are
630
oplock-aware at this time.
634
Unless your system supports kernel oplocks, you should disable oplocks if you are
635
accessing the same files from both UNIX/Linux and SMB clients. Regardless, oplocks should
636
always be disabled if you are sharing a database file (e.g., Microsoft Access) between
637
multiple clients, because any break the first client receives will affect synchronization of
638
the entire file (not just the single record), which will result in a noticeable performance
639
impairment and, more likely, problems accessing the database in the first place. Notably,
640
Microsoft Outlook's personal folders (*.pst) react quite badly to oplocks. If in doubt,
641
disable oplocks and tune your system from that point.
645
If client-side caching is desirable and reliable on your network, you will benefit from
646
turning on oplocks. If your network is slow and/or unreliable, or you are sharing your
647
files among other file sharing mechanisms (e.g., NFS) or across a WAN, or multiple people
648
will be accessing the same files frequently, you probably will not benefit from the overhead
649
of your client sending oplock breaks and will instead want to disable oplocks for the share.
653
Another factor to consider is the perceived performance of file access. If oplocks provide no
654
measurable speed benefit on your network, it might not be worth the hassle of dealing with them.
658
<title>Example Configuration</title>
661
In the following section we examine two distinct aspects of Samba locking controls.
665
<title>Disabling Oplocks</title>
668
You can disable oplocks on a per-share basis with the following:
673
<smbconfsection name="[acctdata]"/>
674
<smbconfoption name="oplocks">False</smbconfoption>
675
<smbconfoption name="level2 oplocks">False</smbconfoption>
680
The default oplock type is Level1. Level2 oplocks are enabled on a per-share basis
681
in the &smb.conf; file.
685
Alternately, you could disable oplocks on a per-file basis within the share:
690
<smbconfoption name="veto oplock files">/*.mdb/*.MDB/*.dbf/*.DBF/</smbconfoption>
695
If you are experiencing problems with oplocks, as apparent from Samba's log entries,
696
you may want to play it safe and disable oplocks and Level2 oplocks.
702
<title>Disabling Kernel Oplocks</title>
705
Kernel oplocks is an &smb.conf; parameter that notifies Samba (if
706
the UNIX kernel has the capability to send a Windows client an oplock
707
break) when a UNIX process is attempting to open the file that is
708
cached. This parameter addresses sharing files between UNIX and
709
Windows with oplocks enabled on the Samba server: the UNIX process
710
can open the file that is Oplocked (cached) by the Windows client and
711
the smbd process will not send an oplock break, which exposes the file
712
to the risk of data corruption. If the UNIX kernel has the ability to
713
send an oplock break, then the kernel oplocks parameter enables Samba
714
to send the oplock break. Kernel oplocks are enabled on a per-server
715
basis in the &smb.conf; file.
720
<smbconfoption name="kernel oplocks">yes</smbconfoption>
726
<emphasis>Veto oplocks</emphasis> is an &smb.conf; parameter that identifies specific files for
727
which oplocks are disabled. When a Windows client opens a file that
728
has been configured for veto oplocks, the client will not be granted
729
the oplock, and all operations will be executed on the original file on
730
disk instead of a client-cached file copy. By explicitly identifying
731
files that are shared with UNIX processes and disabling oplocks for
732
those files, the server-wide oplock configuration can be enabled to
733
allow Windows clients to utilize the performance benefit of file
734
caching without the risk of data corruption. Veto oplocks can be
735
enabled on a per-share basis, or globally for the entire server, in the
736
&smb.conf; file as shown in <link linkend="far1"/>.
741
<title>Share with Some Files Oplocked</title>
743
<smbconfsection name="[global]"/>
744
<smbconfoption name="veto oplock files">/filename.htm/*.txt/</smbconfoption>
746
<smbconfsection name="[share_name]"/>
747
<smbconfoption name="veto oplock files">/*.exe/filename.ext/</smbconfoption>
753
<smbconfoption name="oplock break wait time"/> is an &smb.conf; parameter
754
that 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>
756
Oplock break wait time can only be configured globally in the &smb.conf; file as shown:
761
<smbconfoption name="oplock break wait time"> 0 (default)</smbconfoption>
766
<emphasis>Oplock break contention limit</emphasis> is an &smb.conf; parameter that limits the
767
response of the Samba server to grant an oplock if the configured
768
number 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>
770
Oplock break contention limit can be enabled on a per-share basis, or globally for
771
the entire server, in the &smb.conf; file as shown in <link linkend="far3"/>.
776
<title>Configuration with Oplock Break Contention Limit</title>
778
<smbconfsection name="[global]"/>
779
<smbconfoption name="oplock break contention limit"> 2 (default)</smbconfoption>
781
<smbconfsection name="[share_name]"/>
782
<smbconfoption name="oplock break contention limit"> 2 (default)</smbconfoption>
793
<title>MS Windows Oplocks and Caching Controls</title>
796
There is a known issue when running applications (like Norton Antivirus) on a Windows 2000/ XP
797
workstation computer that can affect any application attempting to access shared database files
798
across a network. This is a result of a default setting configured in the Windows 2000/XP
799
operating system. When a workstation
800
attempts to access shared data files located on another Windows 2000/XP computer,
801
the Windows 2000/XP operating system will attempt to increase performance by locking the
802
files and caching information locally. When this occurs, the application is unable to
803
properly function, which results in an <quote>Access Denied</quote>
804
error message being displayed during network operations.
808
All 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
810
have oplocks disabled in order to minimize the risk of data file corruption.
811
This 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>
816
If you are using a Windows NT family workstation in place of a server, you must also
817
disable oplocks on that workstation. For example, if you use a
818
PC with the Windows NT Workstation operating system instead of Windows NT Server, and you
819
have data files located on it that are accessed from other Windows PCs, you may need to
820
disable oplocks on that system.
824
The major difference is the location in the Windows registry where the values for disabling
825
oplocks are entered. Instead of the LanManServer location, the LanManWorkstation location
830
You can verify (change or add, if necessary) this registry value using the Windows
831
Registry Editor. When you change this registry value, you will have to reboot the PC
832
to ensure that the new setting goes into effect.
836
The location of the client registry entry for oplocks has changed in
837
Windows 2000 from the earlier location in Microsoft Windows NT.
841
Windows 2000 will still respect the EnableOplocks registry value used to disable oplocks
842
in earlier versions of Windows.
846
You can also deny the granting of oplocks by changing the following registry entries:
851
HKEY_LOCAL_MACHINE\System\
852
CurrentControlSet\Services\MRXSmb\Parameters\
854
OplocksDisabled REG_DWORD 0 or 1
855
Default: 0 (not disabled)
860
The OplocksDisabled registry value configures Windows clients to either request or not
861
request oplocks on a remote file. To disable oplocks, the value of
862
OplocksDisabled must be set to 1.
867
HKEY_LOCAL_MACHINE\System\
868
CurrentControlSet\Services\LanmanServer\Parameters
870
EnableOplocks REG_DWORD 0 or 1
871
Default: 1 (Enabled by Default)
873
EnableOpLockForceClose REG_DWORD 0 or 1
874
Default: 0 (Disabled by Default)
879
The EnableOplocks value configures Windows-based servers (including Workstations sharing
880
files) to allow or deny oplocks on local files.
884
To force closure of open oplocks on close or program exit, EnableOpLockForceClose must be set to 1.
888
An illustration of how Level2 oplocks work follows:
893
Station 1 opens the file requesting oplock.
896
Since no other station has the file open, the server grants station 1 exclusive oplock.
899
Station 2 opens the file requesting oplock.
902
Since station 1 has not yet written to the file, the server asks station 1 to break
906
Station 1 complies by flushing locally buffered lock information to the server.
909
Station 1 informs the server that it has broken to level2 Oplock (alternately,
910
station 1 could have closed the file).
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.
917
Station 2 (or any station that has the file open) sends a write request SMB.
918
The server returns the write response.
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.
929
<title>Workstation Service Entries</title>
931
<para><programlisting>
932
\HKEY_LOCAL_MACHINE\System\
933
CurrentControlSet\Services\LanmanWorkstation\Parameters
935
UseOpportunisticLocking REG_DWORD 0 or 1
937
</programlisting></para>
940
This indicates whether the redirector should use oplocks performance
941
enhancement. This parameter should be disabled only to isolate problems.
946
<title>Server Service Entries</title>
948
<para><programlisting>
949
\HKEY_LOCAL_MACHINE\System\
950
CurrentControlSet\Services\LanmanServer\Parameters
952
EnableOplocks REG_DWORD 0 or 1
954
</programlisting></para>
957
This specifies whether the server allows clients to use oplocks on files. Oplocks are a
958
significant performance enhancement, but have the potential to cause lost cached
959
data on some networks, particularly WANs.
962
<para><programlisting>
963
MinLinkThroughput REG_DWORD 0 to infinite bytes per second
965
</programlisting></para>
968
This specifies the minimum link throughput allowed by the server before it disables
969
raw I/O and oplocks for this connection.
972
<para><programlisting>
973
MaxLinkDelay REG_DWORD 0 to 100,000 seconds
975
</programlisting></para>
978
This specifies the maximum time allowed for a link delay. If delays exceed this number,
979
the server disables raw I/O and oplocks for this connection.
982
<para><programlisting>
983
OplockBreakWait REG_DWORD 10 to 180 seconds
985
</programlisting></para>
988
This specifies the time that the server waits for a client to respond to an oplock break
989
request. Smaller values can allow detection of crashed clients more quickly but can
990
potentially cause loss of cached data.
997
<title>Persistent Data Corruption</title>
1000
If you have applied all of the settings discussed in this chapter but data corruption problems
1001
and other symptoms persist, here are some additional things to check out.
1005
We have credible reports from developers that faulty network hardware, such as a single
1006
faulty network card, can cause symptoms similar to read caching and data corruption.
1007
If you see persistent data corruption even after repeated re-indexing, you may have to
1008
rebuild the data files in question. This involves creating a new data file with the
1009
same definition as the file to be rebuilt and transferring the data from the old file
1010
to the new one. There are several known methods for doing this that can be found in
1017
<title>Common Errors</title>
1020
In some sites locking problems surface as soon as a server is installed; in other sites
1021
locking problems may not surface for a long time. Almost without exception, when a locking
1022
problem does surface, it will cause embarrassment and potential data corruption.
1026
Over the past few years there have been a number of complaints on the Samba mailing lists
1027
that have claimed that Samba caused data corruption. Three causes have been identified
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.
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.
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).
1062
<title>locking.tdb Error Messages</title>
1066
We are seeing lots of errors in the Samba logs, like:
1069
tdb(/usr/local/samba_2.2.7/var/locks/locking.tdb): rec_read bad magic
1070
0x4d6f4b61 at offset=36116
1079
This error indicates a corrupted tdb. Stop all instances of smbd, delete locking.tdb, and restart smbd.
1085
<title>Problems Saving Files in MS Office on Windows XP</title>
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>.
1095
<title>Long Delays Deleting Files over Network with XP SP1</title>
1097
<para><quote>It sometimes takes approximately 35 seconds to delete files over the network after XP SP1 has been applied.</quote></para>
1099
<indexterm><primary>KB 811492</primary></indexterm>
1100
<para>This is a bug in Windows XP. More information can be found in <ulink url="http://support.microsoft.com/?id=811492">
1101
Microsoft Knowledge Base article 811492</ulink></para>.
1107
<title>Additional Reading</title>
1110
You may want to check for an updated documentation regarding file and record locking issues on the Microsoft
1111
<ulink url="http://support.microsoft.com/">Support</ulink> web site. Additionally, search for the word
1112
<literal>locking</literal> on the Samba <ulink url="http://www.samba.org/">web</ulink> site.
1116
Section of the Microsoft MSDN Library on opportunistic locking:
1120
<indexterm><primary>KB 224992</primary></indexterm>
1121
Microsoft Knowledge Base, <quote>Maintaining Transactional Integrity with OPLOCKS</quote>,
1122
Microsoft Corporation, April 1999, <ulink noescape="1" url="http://support.microsoft.com/?id=224992">Microsoft
1123
KB Article 224992</ulink>.
1127
<indexterm><primary>KB 296264</primary></indexterm>
1128
Microsoft Knowledge Base, <quote>Configuring Opportunistic Locking in Windows 2000</quote>,
1129
Microsoft Corporation, April 2001 <ulink noescape="1" url="http://support.microsoft.com/?id=296264">Microsoft KB Article 296264</ulink>.
1133
<indexterm><primary>KB 129202</primary></indexterm>
1134
Microsoft Knowledge Base, <quote>PC Ext: Explanation of Opportunistic Locking on Windows NT</quote>,
1135
Microsoft Corporation, April 1995 <ulink noescape="1" url="http://support.microsoft.com/?id=129202">Microsoft
1136
KB Article 129202</ulink>.
added
removed
docs-xml/Samba3-HOWTO/TOSHARG-locking.xml
