summaryrefslogtreecommitdiffstats
path: root/docs-xml/Samba3-HOWTO/TOSHARG-locking.xml
blob: ee48f8c90d6e9d3a8b4f5211ca98447c77bf45e4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
<chapter id="locking">
<chapterinfo>
	&author.jeremy;
	&author.jelmer;
	&author.jht;
	&author.eroseme;
</chapterinfo>
<title>File and Record Locking</title>

<para>
<indexterm><primary>locking</primary></indexterm>
One area that causes trouble for many network administrators is locking.
The extent of the problem is readily evident from searches over the Internet.
</para>

<sect1>
<title>Features and Benefits</title>

<para>
<indexterm><primary>locking semantics</primary></indexterm>
Samba provides all the same locking semantics that MS Windows clients expect
and that MS Windows NT4/200x servers also provide.
</para>

<para>
<indexterm><primary>locking</primary></indexterm>
The term <emphasis>locking</emphasis> has exceptionally broad meaning and covers
a range of functions that are all categorized under this one term.
</para>

<para>
<indexterm><primary>opportunistic locking</primary></indexterm>
<indexterm><primary>locking protocol</primary></indexterm>
<indexterm><primary>performance advantage</primary></indexterm>
Opportunistic locking is a desirable feature when it can enhance the
perceived performance of applications on a networked client. However, the
opportunistic locking protocol is not robust and therefore can
encounter problems when invoked beyond a simplistic configuration or
on extended slow or faulty networks. In these cases, operating
system management of opportunistic locking and/or recovering from
repetitive errors can offset the perceived performance advantage that
it is intended to provide.
</para>

<para>
<indexterm><primary>registry</primary></indexterm>
The MS Windows network administrator needs to be aware that file and record
locking semantics (behavior) can be controlled either in Samba or by way of registry
settings on the MS Windows client.
</para>

<note>
<para>
<indexterm><primary>disable locking</primary></indexterm>
Sometimes it is necessary to disable locking control settings on the Samba
server as well as on each MS Windows client!
</para>
</note>

</sect1>

<sect1>
<title>Discussion</title>

<para>
<indexterm><primary>record locking</primary></indexterm>
<indexterm><primary>deny modes</primary></indexterm>
There are two types of locking that need to be performed by an SMB server.
The first is <emphasis>record locking</emphasis> that allows a client to lock
a range of bytes in an open file. The second is the <emphasis>deny modes</emphasis>
that are specified when a file is open.
</para>

<para>
<indexterm><primary>locking semantics</primary></indexterm>
<indexterm><primary>record locking</primary></indexterm>
<indexterm><primary>locking</primary></indexterm>
<indexterm><primary>byte ranges</primary></indexterm>
<indexterm><primary>UNIX locking</primary></indexterm>
Record locking semantics under UNIX are very different from record locking under
Windows. Versions of Samba before 2.2 have tried to use the native fcntl() UNIX
system call to implement proper record locking between different Samba clients.
This cannot be fully correct for several reasons. The simplest is
that a Windows client is allowed to lock a byte range up to 2^32 or 2^64,
depending on the client OS. The UNIX locking only supports byte ranges up to 2^31.
So it is not possible to correctly satisfy a lock request above 2^31. There are
many more differences, too many to be listed here.
</para>

<para>
<indexterm><primary>record locking</primary></indexterm>
<indexterm><primary>byte-range lock</primary></indexterm>
Samba 2.2 and above implement record locking completely independently of the
underlying UNIX system. If a byte-range lock that the client requests happens
to fall into the range of 0 to 2^31, Samba hands this request down to the UNIX system.
No other locks can be seen by UNIX, anyway.
</para>

<para>
<indexterm><primary>check for locks</primary></indexterm>
<indexterm><primary>rpc.lockd</primary></indexterm>
Strictly speaking, an SMB server should check for locks before every read and write call on
a file. Unfortunately, with the way fcntl() works, this can be slow and may overstress
the <command>rpc.lockd</command>. This is almost always unnecessary because clients are 
independently supposed to make locking calls before reads and writes if locking is
important to them. By default, Samba only makes locking calls when explicitly asked
to by a client, but if you set <smbconfoption name="strict locking">yes</smbconfoption>, it
will make lock checking calls on <emphasis>every</emphasis> read and write call.
</para>

<para>
<indexterm><primary>byte-range locking</primary></indexterm>
You can also disable byte-range locking completely by using
<smbconfoption name="locking">no</smbconfoption>.
This is useful for those shares that do not support locking or do not need it
(such as CD-ROMs). In this case, Samba fakes the return codes of locking calls to
tell clients that everything is okay.
</para>

<para>
<indexterm><primary>deny modes</primary></indexterm>
<indexterm><primary>DENY_NONE</primary></indexterm>
<indexterm><primary>DENY_READ</primary></indexterm>
<indexterm><primary>DENY_WRITE</primary></indexterm>
<indexterm><primary>DENY_ALL</primary></indexterm>
<indexterm><primary>DENY_FCB</primary></indexterm>
<indexterm><primary>DENY_DOS</primary></indexterm>
The second class of locking is the <emphasis>deny modes</emphasis>. These 
are set by an application when it opens a file to determine what types of
access should be allowed simultaneously with its open. A client may ask for
<constant>DENY_NONE</constant>, <constant>DENY_READ</constant>, 
<constant>DENY_WRITE</constant>, or <constant>DENY_ALL</constant>. There are also special compatibility
modes called <constant>DENY_FCB</constant> and <constant>DENY_DOS</constant>.
</para>

<sect2>
<title>Opportunistic Locking Overview</title>

<para>
<indexterm><primary>opportunistic locking</primary></indexterm>
<indexterm><primary>oplocks</primary></indexterm>
<indexterm><primary>caching</primary></indexterm>
Opportunistic locking (oplocks) is invoked by the Windows file system
(as opposed to an API) via registry entries (on the server and the client)
for the purpose of enhancing network performance when accessing a file
residing on a server. Performance is enhanced by caching the file
locally on the client that allows the following:
</para>

<variablelist>
	<varlistentry><term>Read-ahead:</term>
		<listitem><para>
<indexterm><primary>Read-ahead</primary></indexterm>
		The client reads the local copy of the file, eliminating network latency.
		</para></listitem>
	</varlistentry>

	<varlistentry><term>Write caching:</term>
		<listitem><para>
<indexterm><primary>Write caching</primary></indexterm>
		The client writes to the local copy of the file, eliminating network latency.
		</para></listitem>
	</varlistentry>

        <varlistentry><term>Lock caching:</term>
        <listitem><para>
<indexterm><primary>Lock caching</primary></indexterm>
		The client caches application locks locally, eliminating network latency.
		</para></listitem>
        </varlistentry>
</variablelist>

<para>
<indexterm><primary>performance enhancement</primary></indexterm>
<indexterm><primary>oplocks</primary></indexterm>
<indexterm><primary>deny-none</primary></indexterm>
The performance enhancement of oplocks is due to the opportunity of
exclusive access to the file &smbmdash; even if it is opened with deny-none &smbmdash;
because Windows monitors the file's status for concurrent access from
other processes.
</para>

<variablelist>
<title>Windows Defines Four Kinds of Oplocks:</title>

		<varlistentry><term>Level1 Oplock</term>
			<listitem><para>
<indexterm><primary>Level1 Oplock</primary></indexterm>
<indexterm><primary>redirector</primary></indexterm>
<indexterm><primary>concurrent access</primary></indexterm>
<indexterm><primary>cached local file</primary></indexterm>
			The redirector sees that the file was opened with deny
			none (allowing concurrent access), verifies that no
			other process is accessing the file, checks that
			oplocks are enabled, then grants deny-all/read-write/exclusive
			access to the file. The client now performs
			operations on the cached local file.
			</para>

			<para>
<indexterm><primary>oplock break</primary></indexterm>
<indexterm><primary>flush local locks</primary></indexterm>
<indexterm><primary>deferred open</primary></indexterm>
<indexterm><primary>byte-range locking</primary></indexterm>
			If a second process attempts to open the file, the open
			is deferred while the redirector "breaks" the original
			oplock. The oplock break signals the caching client to
			write the local file back to the server, flush the
			local locks, and discard read-ahead data. The break is
			then complete, the deferred open is granted, and the
			multiple processes can enjoy concurrent file access as
			dictated by mandatory or byte-range locking options.
			However, if the original opening process opened the
			file with a share mode other than deny-none, then the
			second process is granted limited or no access, despite
			the oplock break.
			</para></listitem>
        </varlistentry>

        <varlistentry><term>Level2 Oplock</term>
                <listitem><para>
<indexterm><primary>Level2 Oplock</primary></indexterm>
<indexterm><primary>Level1 oplock</primary></indexterm>
<indexterm><primary>caching</primary></indexterm>
				Performs like a Level1 oplock, except caching is only
                operative for reads. All other operations are performed
                on the server disk copy of the file.
                </para></listitem>
        </varlistentry>

        <varlistentry><term>Filter Oplock</term>
                <listitem><para>
<indexterm><primary>Filter Oplock</primary></indexterm>
				Does not allow write or delete file access.
                </para></listitem>
        </varlistentry>

        <varlistentry><term>Batch Oplock</term>
                <listitem><para>
<indexterm><primary>Batch Oplock</primary></indexterm>
				Manipulates file openings and closings and allows caching
                of file attributes.
                </para></listitem>
        </varlistentry>
</variablelist>

<para>
<indexterm><primary>oplocks</primary></indexterm>
An important detail is that oplocks are invoked by the file system, not
an application API. Therefore, an application can close an oplocked
file, but the file system does not relinquish the oplock. When the
oplock break is issued, the file system then simply closes the file in
preparation for the subsequent open by the second process.
</para>

<para>
<indexterm><primary>Opportunistic locking</primary></indexterm>
<indexterm><primary>client-side data caching</primary></indexterm>
<indexterm><primary>data caching</primary></indexterm>
<indexterm><primary>oplock break</primary></indexterm>
<emphasis>Opportunistic locking</emphasis> is actually an improper name for this feature.
The true benefit of this feature is client-side data caching, and
oplocks is merely a notification mechanism for writing data back to the
networked storage disk. The limitation of oplocks is the
reliability of the mechanism to process an oplock break (notification)
between the server and the caching client. If this exchange is faulty
(usually due to timing out for any number of reasons), then the
client-side caching benefit is negated.
</para>

<para>
<indexterm><primary>client-side caching</primary></indexterm>
The actual decision that a user or administrator should consider is
whether it is sensible to share among multiple users data that will
be cached locally on a client. In many cases the answer is no.
Deciding when to cache or not cache data is the real question, and thus
oplocks should be treated as a toggle for client-side
caching. Turn it <quote>on</quote> when client-side caching is desirable and
reliable. Turn it <quote>off</quote> when client-side caching is redundant,
unreliable, or counterproductive.
</para>

<para>
<indexterm><primary>oplocks</primary></indexterm>
Oplocks is by default set to <quote>on</quote> by Samba on all
configured shares, so careful attention should be given to each case to
determine if the potential benefit is worth the potential for delays.
The following recommendations will help to characterize the environment
where oplocks may be effectively configured.
</para>

<para>
<indexterm><primary>oplocks</primary></indexterm>
<indexterm><primary>high-availability</primary></indexterm>
Windows oplocks is a lightweight performance-enhancing
feature. It is not a robust and reliable protocol. Every
implementation of oplocks should be evaluated as a
trade-off between perceived performance and reliability. Reliability
decreases as each successive rule above is not enforced. Consider a
share with oplocks enabled, over a wide-area network, to a client on a
South Pacific atoll, on a high-availability server, serving a
mission-critical multiuser corporate database during a tropical
storm. This configuration will likely encounter problems with oplocks.
</para>

<para>
<indexterm><primary>mission-critical</primary></indexterm>
Oplocks can be beneficial to perceived client performance when treated
as a configuration toggle for client-side data caching. If the data
caching is likely to be interrupted, then oplock usage should be
reviewed. Samba enables oplocks by default on all
shares. Careful attention should be given to the client usage of
shared data on the server, the server network reliability, and the
oplocks configuration of each share.
In mission-critical, high-availability environments, data integrity is
often a priority. Complex and expensive configurations are implemented
to ensure that if a client loses connectivity with a file server, a
failover replacement will be available immediately to provide
continuous data availability.
</para>

<para>
<indexterm><primary>Windows client failover</primary></indexterm>
<indexterm><primary>transport connection loss</primary></indexterm>
Windows client failover behavior is more at risk of application
interruption than other platforms because it is dependent upon an
established TCP transport connection. If the connection is interrupted
&smbmdash; as in a file server failover &smbmdash; a new session must be established.
It is rare for Windows client applications to be coded to recover
correctly from a transport connection loss; therefore, most applications
will experience some sort of interruption &smbmdash; at worst, abort and
require restarting.
</para>

<para>
<indexterm><primary>caching writes</primary></indexterm>
<indexterm><primary>caching reads</primary></indexterm>
<indexterm><primary>oplock break</primary></indexterm>
If a client session has been caching writes and reads locally due to
oplocks, it is likely that the data will be lost when the
application restarts or recovers from the TCP interrupt. When the TCP
connection drops, the client state is lost. When the file server
recovers, an oplock break is not sent to the client. In this case, the
work from the prior session is lost. Observing this scenario with
oplocks disabled and with the client writing data to the file server
real-time,  the failover will provide the data on disk as it
existed at the time of the disconnect.
</para>

<para>
In mission-critical, high-availability environments, careful attention
should be given to oplocks. Ideally, comprehensive
testing should be done with all affected applications with oplocks
enabled and disabled.
</para>

<sect3>
<title>Exclusively Accessed Shares</title>

<para>
Oplocks is most effective when it is confined to shares
that are exclusively accessed by a single user, or by only one user at
a time. Because the true value of oplocks is the local
client caching of data, any operation that interrupts the caching
mechanism will cause a delay.
</para>

<para>
Home directories are the most obvious examples of where the performance
benefit of oplocks can be safely realized.
</para>

</sect3>

<sect3>
<title>Multiple-Accessed Shares or Files</title>

<para>
As each additional user accesses a file in a share with oplocks
enabled, the potential for delays and resulting perceived poor
performance increases. When multiple users are accessing a file on a
share that has oplocks enabled, the management impact of sending and
receiving oplock breaks and the resulting latency while other clients
wait for the caching client to flush data offset the performance gains
of the caching user.
</para>

<para>
As each additional client attempts to access a file with oplocks set,
the potential performance improvement is negated and eventually results
in a performance bottleneck.
</para>

</sect3>

<sect3>
<title>UNIX or NFS Client-Accessed Files</title>

<para>
<indexterm><primary>NFS clients</primary></indexterm>
<indexterm><primary>data corruption</primary></indexterm>
Local UNIX and NFS clients access files without a mandatory
file-locking mechanism. Thus, these client platforms are incapable of
initiating an oplock break request from the server to a Windows client
that has a file cached. Local UNIX or NFS file access can therefore
write to a file that has been cached by a Windows client, which
exposes the file to likely data corruption.
</para>

<para>
If files are shared between Windows clients and either local UNIX 
or NFS users, turn oplocks off.
</para>

</sect3>

<sect3>
<title>Slow and/or Unreliable Networks</title>

<para>
<indexterm><primary>performance improvement</primary></indexterm>
<indexterm><primary>WAN</primary></indexterm>
<indexterm><primary>latency</primary></indexterm>
The biggest potential performance improvement for oplocks
occurs when the client-side caching of reads and writes delivers the
most differential over sending those reads and writes over the wire.
This is most likely to occur when the network is extremely slow,
congested, or distributed (as in a WAN). However, network latency also
has a high impact on the reliability of the oplock break
mechanism, and thus increases the likelihood of encountering oplock
problems that more than offset the potential perceived performance
gain. Of course, if an oplock break never has to be sent, then this is
the most advantageous scenario in which to utilize oplocks.
</para>

<para>
If the network is slow, unreliable, or a WAN, then do not configure
oplocks if there is any chance of multiple users
regularly opening the same file.
</para>

</sect3>

<sect3>
<title>Multiuser Databases</title>

<para>
<indexterm><primary>Multiuser databases</primary></indexterm>
<indexterm><primary>management bottleneck</primary></indexterm>
<indexterm><primary>oplocks disabled</primary></indexterm>
Multiuser databases clearly pose a risk due to their very nature &smbmdash; they are typically heavily
accessed by numerous users at random intervals. Placing a multiuser database on a share with oplocks enabled
will likely result in a locking management bottleneck on the Samba server. Whether the database application is
developed in-house or a commercially available product, ensure that the share has oplocks disabled.
</para>

</sect3>

<sect3>
<title>PDM Data Shares</title>

<para>
<indexterm><primary>PDM</primary></indexterm>
<indexterm><primary>Process data management</primary></indexterm>
<indexterm><primary>client-side data caching</primary></indexterm>
<indexterm><primary>oplocks management</primary></indexterm>
<indexterm><primary>disabling oplocks</primary></indexterm>
Process data management (PDM) applications such as IMAN, Enovia, and Clearcase are increasing in usage with
Windows client platforms and therefore with SMB datastores. PDM applications manage multiuser environments for
critical data security and access. The typical PDM environment is usually associated with sophisticated client
design applications that will load data locally as demanded. In addition, the PDM application will usually
monitor the data state of each client.  In this case, client-side data caching is best left to the local
application and PDM server to negotiate and maintain. It is appropriate to eliminate the client OS from any
caching tasks, and the server from any oplocks management, by disabling oplocks on the share.
</para>

</sect3>

<sect3>
<title>Beware of Force User</title>

<para>
<indexterm><primary>oplock break</primary></indexterm>
Samba includes an &smb.conf; parameter called <smbconfoption name="force user"/> that changes the user
accessing a share from the incoming user to whatever user is defined by the &smb.conf; variable. If oplocks is
enabled on a share, the change in user access causes an oplock break to be sent to the client, even if the
user has not explicitly loaded a file. In cases where the network is slow or unreliable, an oplock break can
become lost without the user even accessing a file. This can cause apparent performance degradation as the
client continually reconnects to overcome the lost oplock break.
</para>

<para>
Avoid the combination of the following: 
</para>

<itemizedlist>
	<listitem><para>
	<smbconfoption name="force user"/> in the &smb.conf; share configuration.
	</para></listitem>

	<listitem><para>
	Slow or unreliable networks.
	</para></listitem>

	<listitem><para>
	Oplocks enabled.
	</para></listitem>
</itemizedlist>

</sect3>

<sect3>
<title>Advanced Samba Oplocks Parameters</title>

<para>
<indexterm><primary>oplock parameters</primary></indexterm>
<indexterm><primary>oplock mechanism</primary></indexterm>
<indexterm><primary>implementing oplocks</primary></indexterm>
Samba provides oplock parameters that allow the
administrator to adjust various properties of the oplock mechanism to
account for timing and usage levels. These parameters provide good
versatility for implementing oplocks in environments where they would
likely cause problems. The parameters are 
<smbconfoption name="oplock break wait time"/>, and
<smbconfoption name="oplock contention limit"/>.
</para>

<para>
<indexterm><primary>turn oplocks off</primary></indexterm>
For most users, administrators, and environments, if these parameters
are required, then the better option is simply to turn oplocks off.
The Samba SWAT help text for both parameters reads: <quote>Do not change
this parameter unless you have read and understood the Samba oplock code.</quote>
This is good advice.
</para>

</sect3>

<sect3>
<title>Mission-Critical, High-Availability</title>

<para>
In mission-critical, high-availability environments, data integrity is
often a priority. Complex and expensive configurations are implemented
to ensure that if a client loses connectivity with a file server, a
failover replacement will be available immediately to provide
continuous data availability.
</para>

<para>
Windows client failover behavior is more at risk of application
interruption than other platforms because it is dependent upon an
established TCP transport connection. If the connection is interrupted
&smbmdash; as in a file server failover &smbmdash; a new session must be established.
It is rare for Windows client applications to be coded to recover
correctly from a transport connection loss; therefore, most applications
will experience some sort of interruption &smbmdash; at worst, abort and
require restarting.
</para>

<para>
If a client session has been caching writes and reads locally due to
oplocks, it is likely that the data will be lost when the
application restarts or recovers from the TCP interrupt. When the TCP
connection drops, the client state is lost. When the file server
recovers, an oplock break is not sent to the client. In this case, the
work from the prior session is lost. Observing this scenario with
oplocks disabled, if the client was writing data to the file server
real-time, then the failover will provide the data on disk as it
existed at the time of the disconnect.
</para>

<para>
In mission-critical, high-availability environments, careful attention
should be given to oplocks. Ideally, comprehensive
testing should be done with all affected applications with oplocks
enabled and disabled.
</para>

</sect3>
</sect2>
</sect1>

<sect1>
<title>Samba Oplocks Control</title>

<para>
Oplocks is a unique Windows file locking feature. It is
not really file locking, but is included in most discussions of Windows
file locking, so is considered a de facto locking feature.
Oplocks is actually part of the Windows client file
caching mechanism. It is not a particularly robust or reliable feature
when implemented on the variety of customized networks that exist in
enterprise computing.
</para>

<para>
Like Windows, Samba implements oplocks as a server-side
component of the client caching mechanism. Because of the lightweight
nature of the Windows feature design, effective configuration of
oplocks requires a good understanding of its limitations,
and then applying that understanding when configuring data access for
each particular customized network and client usage state.
</para>

<para>
Oplocks essentially means that the client is allowed to download and cache
a file on its hard drive while making changes; if a second client wants to access the
file, the first client receives a break and must synchronize the file back to the server.
This can give significant performance gains in some cases; some programs insist on
synchronizing the contents of the entire file back to the server for a single change.
</para>

<para>
Level1 Oplocks (also known as just plain <quote>oplocks</quote>) is another term for opportunistic locking.
</para>

<para>
Level2 Oplocks provides opportunistic locking for a file that will be treated as
<emphasis>read only</emphasis>. Typically this is used on files that are read-only or
on files that the client has no initial intention to write to at time of opening the file.
</para>

<para>
Kernel Oplocks are essentially a method that allows the Linux kernel to co-exist with
Samba's oplocked files, although this has provided better integration of MS Windows network
file locking with the underlying OS. SGI IRIX and Linux are the only two OSs that are
oplock-aware at this time.
</para>

<para>
Unless your system supports kernel oplocks, you should disable oplocks if you are
accessing the same files from both UNIX/Linux and SMB clients. Regardless, oplocks should
always be disabled if you are sharing a database file (e.g., Microsoft Access) between
multiple clients, because any break the first client receives will affect synchronization of
the entire file (not just the single record), which will result in a noticeable performance
impairment and, more likely, problems accessing the database in the first place. Notably,
Microsoft Outlook's personal folders (*.pst) react quite badly to oplocks. If in doubt,
disable oplocks and tune your system from that point.
</para>

<para>
If client-side caching is desirable and reliable on your network, you will benefit from
turning on oplocks. If your network is slow and/or unreliable, or you are sharing your
files among other file sharing mechanisms (e.g., NFS) or across a WAN, or multiple people
will be accessing the same files frequently, you probably will not benefit from the overhead
of your client sending oplock breaks and will instead want to disable oplocks for the share.
</para>

<para>
Another factor to consider is the perceived performance of file access. If oplocks provide no
measurable speed benefit on your network, it might not be worth the hassle of dealing with them.
</para>

<sect2>
<title>Example Configuration</title>

<para>
In the following section we examine two distinct aspects of Samba locking controls.
</para>

<sect3>
<title>Disabling Oplocks</title>

<para>
You can disable oplocks on a per-share basis with the following:
</para>

<para>
<smbconfblock>
<smbconfsection name="[acctdata]"/>
<smbconfoption name="oplocks">False</smbconfoption>
<smbconfoption name="level2 oplocks">False</smbconfoption>
</smbconfblock>
</para>

<para>
The default oplock type is Level1. Level2 oplocks are enabled on a per-share basis
in the &smb.conf; file.
</para>

<para>
Alternately, you could disable oplocks on a per-file basis within the share:
</para>

<para>
	<smbconfblock>
<smbconfoption name="veto oplock files">/*.mdb/*.MDB/*.dbf/*.DBF/</smbconfoption>
</smbconfblock>
</para>

<para>
If you are experiencing problems with oplocks, as apparent from Samba's log entries,
you may want to play it safe and disable oplocks and Level2 oplocks.
</para>

</sect3>

<sect3>
<title>Disabling Kernel Oplocks</title>

<para>
Kernel oplocks is an &smb.conf; parameter that notifies Samba (if
the UNIX kernel has the capability to send a Windows client an oplock
break) when a UNIX process is attempting to open the file that is
cached. This parameter addresses sharing files between UNIX and
Windows with oplocks enabled on the Samba server: the UNIX process
can open the file that is Oplocked (cached) by the Windows client and
the smbd process will not send an oplock break, which exposes the file
to the risk of data corruption. If the UNIX kernel has the ability to
send an oplock break, then the kernel oplocks parameter enables Samba
to send the oplock break. Kernel oplocks are enabled on a per-server
basis in the &smb.conf; file.
</para>

<para>
<smbconfblock>
<smbconfoption name="kernel oplocks">yes</smbconfoption>
</smbconfblock>
The default is no.
</para>

<para>
<emphasis>Veto oplocks</emphasis> is an &smb.conf; parameter that identifies specific files for
which oplocks are disabled. When a Windows client opens a file that
has been configured for veto oplocks, the client will not be granted
the oplock, and all operations will be executed on the original file on
disk instead of a client-cached file copy. By explicitly identifying
files that are shared with UNIX processes and disabling oplocks for
those files, the server-wide oplock configuration can be enabled to
allow Windows clients to utilize the performance benefit of file
caching without the risk of data corruption. Veto oplocks can be
enabled on a per-share basis, or globally for the entire server, in the
&smb.conf; file as shown in <link linkend="far1"/>.
</para>

<para>
<example id="far1">
<title>Share with Some Files Oplocked</title>
<smbconfblock>
<smbconfsection name="[global]"/>
<smbconfoption name="veto oplock files">/filename.htm/*.txt/</smbconfoption>

<smbconfsection name="[share_name]"/>
<smbconfoption name="veto oplock files">/*.exe/filename.ext/</smbconfoption>
</smbconfblock>
</example>
</para>

<para>
<smbconfoption name="oplock break wait time"/> is an &smb.conf; parameter
that adjusts the time interval for Samba to reply to an oplock break request. Samba recommends:
<quote>Do not change this parameter unless you have read and understood the Samba oplock code.</quote>
Oplock break wait time can only be configured globally in the &smb.conf; file as shown:
</para>

<para>
	<smbconfblock>
<smbconfoption name="oplock break wait time"> 0 (default)</smbconfoption>
</smbconfblock>
</para>

<para>
<emphasis>Oplock break contention limit</emphasis> is an &smb.conf; parameter that limits the
response of the Samba server to grant an oplock if the configured
number of contending clients reaches the limit specified by the parameter. Samba recommends
<quote>Do not change this parameter unless you have read and understood the Samba oplock code.</quote>
Oplock break contention limit can be enabled on a per-share basis, or globally for
the entire server, in the &smb.conf; file as shown in <link linkend="far3"/>.
</para>

<para>
<example id="far3">
<title>Configuration with Oplock Break Contention Limit</title>
<smbconfblock>
<smbconfsection name="[global]"/>
<smbconfoption name="oplock break contention limit"> 2 (default)</smbconfoption>

<smbconfsection name="[share_name]"/>
<smbconfoption name="oplock break contention limit"> 2 (default)</smbconfoption>
</smbconfblock>
</example>
</para>

</sect3>
</sect2>

</sect1>

<sect1>
<title>MS Windows Oplocks and Caching Controls</title>

<para>
There is a known issue when running applications (like Norton Antivirus) on a Windows 2000/ XP
workstation computer that can affect any application attempting to access shared database files
across a network. This is a result of a default setting configured in the Windows 2000/XP
operating system. When a workstation
attempts to access shared data files located on another Windows 2000/XP computer,
the Windows 2000/XP operating system will attempt to increase performance by locking the
files and caching information locally. When this occurs, the application is unable to
properly function, which results in an <quote>Access Denied</quote>
 error message being displayed during network operations.
</para>

<para>
All Windows operating systems in the NT family that act as database servers for data files
(meaning that data files are stored there and accessed by other Windows PCs) may need to
have oplocks disabled in order to minimize the risk of data file corruption.
This includes Windows 9x/Me, Windows NT, Windows 200x, and Windows XP.
<footnote><para>Microsoft has documented this in Knowledge Base article 300216.</para></footnote>
</para>

<para>
If you are using a Windows NT family workstation in place of a server, you must also
disable oplocks on that workstation. For example, if you use a
PC with the Windows NT Workstation operating system instead of Windows NT Server, and you
have data files located on it that are accessed from other Windows PCs, you may need to
disable oplocks on that system.
</para>

<para>
The major difference is the location in the Windows registry where the values for disabling
oplocks are entered. Instead of the LanManServer location, the LanManWorkstation location
may be used.
</para>

<para>
You can verify (change or add, if necessary) this registry value using the Windows
Registry Editor. When you change this registry value, you will have to reboot the PC
to ensure that the new setting goes into effect.
</para>

<para>
The location of the client registry entry for oplocks has changed in
Windows 2000 from the earlier location in Microsoft Windows NT.
</para>

<note><para>
Windows 2000 will still respect the EnableOplocks registry value used to disable oplocks
in earlier versions of Windows.
</para></note>

<para>
You can also deny the granting of oplocks by changing the following registry entries:
</para>

<para>
<programlisting>
	HKEY_LOCAL_MACHINE\System\
		CurrentControlSet\Services\MRXSmb\Parameters\

		OplocksDisabled REG_DWORD 0 or 1
		Default: 0 (not disabled)
</programlisting>
</para>

<note><para>
The OplocksDisabled registry value configures Windows clients to either request or not
request oplocks on a remote file. To disable oplocks, the value of
 OplocksDisabled must be set to 1.
</para></note>

<para>
<programlisting>
	HKEY_LOCAL_MACHINE\System\
		CurrentControlSet\Services\LanmanServer\Parameters

		EnableOplocks REG_DWORD 0 or 1
		Default: 1 (Enabled by Default)

		EnableOpLockForceClose REG_DWORD 0 or 1
		Default: 0 (Disabled by Default)
</programlisting>
</para>

<note><para>
The EnableOplocks value configures Windows-based servers (including Workstations sharing
files) to allow or deny oplocks on local files.
</para></note>

<para>
To force closure of open oplocks on close or program exit, EnableOpLockForceClose must be set to 1.
</para>

<para>
An illustration of how Level2 oplocks work follows:
</para>

<itemizedlist>
	<listitem><para>
	Station 1 opens the file requesting oplock.
	</para></listitem>
	<listitem><para>
	Since no other station has the file open, the server grants station 1 exclusive oplock.
	</para></listitem>
	<listitem><para>
	Station 2 opens the file requesting oplock.
	</para></listitem>
	<listitem><para>
	Since station 1 has not yet written to the file, the server asks station 1 to break
	to Level2 oplock.
	</para></listitem>
	<listitem><para>
	Station 1 complies by flushing locally buffered lock information to the server.
	</para></listitem>
	<listitem><para>
	Station 1 informs the server that it has broken to level2 Oplock (alternately,
	station 1 could have closed the file).
	</para></listitem>
	<listitem><para>
	The server responds to station 2's open request, granting it Level2 oplock.
	Other stations can likewise open the file and obtain Level2 oplock.
	</para></listitem>
	<listitem><para>
	Station 2 (or any station that has the file open) sends a write request SMB.
	The server returns the write response.
	</para></listitem>
	<listitem><para>
	The server asks all stations that have the file open to break to none, meaning no
	station holds any oplock on the file. Because the workstations can have no cached
	writes or locks at this point, they need not respond to the break-to-none advisory;
	all they need do is invalidate locally cashed read-ahead data.
	</para></listitem>
</itemizedlist>

<sect2>
<title>Workstation Service Entries</title>

<para><programlisting>
	\HKEY_LOCAL_MACHINE\System\
		CurrentControlSet\Services\LanmanWorkstation\Parameters

	UseOpportunisticLocking   REG_DWORD   0 or 1
	Default: 1 (true)
</programlisting></para>

<para>
This indicates whether the redirector should use oplocks performance
enhancement. This parameter should be disabled only to isolate problems.
</para>

</sect2>
<sect2>
<title>Server Service Entries</title>

<para><programlisting>
	\HKEY_LOCAL_MACHINE\System\
		CurrentControlSet\Services\LanmanServer\Parameters

	EnableOplocks   REG_DWORD   0 or 1
	Default: 1 (true)
</programlisting></para>

<para>
This specifies whether the server allows clients to use oplocks on files. Oplocks are a
significant performance enhancement, but have the potential to cause lost cached
data on some networks, particularly WANs.
</para>

<para><programlisting>
	MinLinkThroughput   REG_DWORD   0 to infinite bytes per second
	Default: 0
</programlisting></para>

<para>
This specifies the minimum link throughput allowed by the server before it disables
raw I/O and oplocks for this connection.
</para>

<para><programlisting>
	MaxLinkDelay   REG_DWORD   0 to 100,000 seconds
	Default: 60
</programlisting></para>

<para>
This specifies the maximum time allowed for a link delay. If delays exceed this number,
the server disables raw I/O and oplocks for this connection.
</para>

<para><programlisting>
	OplockBreakWait   REG_DWORD   10 to 180 seconds
	Default: 35
</programlisting></para>

<para>
This specifies the time that the server waits for a client to respond to an oplock break
request. Smaller values can allow detection of crashed clients more quickly but can
potentially cause loss of cached data.
</para>

</sect2>
</sect1>

<sect1>
<title>Persistent Data Corruption</title>

<para>
If you have applied all of the settings discussed in this chapter but data corruption problems
and other symptoms persist, here are some additional things to check out.
</para>

<para>
We have credible reports from developers that faulty network hardware, such as a single
faulty network card, can cause symptoms similar to read caching and data corruption.
If you see persistent data corruption even after repeated re-indexing, you may have to
rebuild the data files in question. This involves creating a new data file with the
same definition as the file to be rebuilt and transferring the data from the old file
to the new one. There are several known methods for doing this that can be found in
our knowledge base.
</para>

</sect1>

<sect1>
<title>Common Errors</title>

<para>
In some sites locking problems surface as soon as a server is installed; in other sites
locking problems may not surface for a long time. Almost without exception, when a locking
problem does surface, it will cause embarrassment and potential data corruption.
</para>

<para>
Over the past few years there have been a number of complaints on the Samba mailing lists
that have claimed that Samba caused data corruption. Three causes have been identified
so far:
</para>

<itemizedlist>
	<listitem><para>
	Incorrect configuration of oplocks (incompatible with the application
	being used). This is a common problem even where MS Windows NT4 or MS Windows
	200x-based servers were in use. It is imperative that the software application vendors'
	instructions for configuration of file locking should be followed. If in doubt,
	disable oplocks on both the server and the client. Disabling of all forms of file
	caching on the MS Windows client may be necessary also.
	</para></listitem>

	<listitem><para>
	Defective network cards, cables, or hubs/switches. This is generally a more
	prevalent factor with low-cost networking hardware, although occasionally there
	have also been problems with incompatibilities in more up-market hardware.
	</para></listitem>

	<listitem><para>
	There have been some random reports of Samba log files being written over data
	files. This has been reported by very few sites (about five in the past 3 years)
	and all attempts to reproduce the problem have failed. The Samba Team has been
	unable to catch this happening and thus unable to isolate any particular
	cause. Considering the millions of systems that use Samba, for the sites that have
	been affected by this as well as for the Samba Team, this is a frustrating and
	vexing challenge. If you see this type of thing happening, please create a bug
	report on Samba <ulink url="https://bugzilla.samba.org">Bugzilla</ulink> without delay.
	Make sure that you give as much information as you possibly can to help isolate the
	cause and to allow replication of the problem (an essential step in problem isolation and correction).
	</para></listitem>
</itemizedlist>

	<sect2>
	<title>locking.tdb Error Messages</title>

	<para>
		<quote>
			We are seeing lots of errors in the Samba logs, like:
		</quote>
<programlisting>
tdb(/usr/local/samba_2.2.7/var/locks/locking.tdb): rec_read bad magic
 0x4d6f4b61 at offset=36116
</programlisting>

		<quote>
			What do these mean?
		</quote>
	</para>

	<para>
	This error indicates a corrupted tdb. Stop all instances of smbd, delete locking.tdb, and restart smbd.
	</para>

	</sect2>

	<sect2>
		<title>Problems Saving Files in MS Office on Windows XP</title>

<indexterm><primary>KB 812937</primary></indexterm>
		<para>This is a bug in Windows XP. More information can be 
		found in <ulink url="http://support.microsoft.com/?id=812937">Microsoft Knowledge Base article 812937</ulink></para>.

	</sect2>

	<sect2>

		<title>Long Delays Deleting Files over Network with XP SP1</title>
		
		<para><quote>It sometimes takes approximately 35 seconds to delete files over the network after XP SP1 has been applied.</quote></para>

<indexterm><primary>KB 811492</primary></indexterm>
		<para>This is a bug in Windows XP. More information can be found in <ulink url="http://support.microsoft.com/?id=811492">
				Microsoft Knowledge Base article 811492</ulink></para>.
	</sect2>

</sect1>

<sect1>
<title>Additional Reading</title>

<para>
You may want to check for an updated documentation regarding file and record locking issues on the Microsoft
<ulink url="http://support.microsoft.com/">Support</ulink> web site. Additionally, search for the word
<literal>locking</literal> on the Samba <ulink url="http://www.samba.org/">web</ulink> site.
</para>

<para>
Section of the Microsoft MSDN Library on opportunistic locking: 
</para>

<para>
<indexterm><primary>KB 224992</primary></indexterm>
Microsoft Knowledge Base, <quote>Maintaining Transactional Integrity with OPLOCKS</quote>,
Microsoft Corporation, April 1999, <ulink noescape="1" url="http://support.microsoft.com/?id=224992">Microsoft
KB Article 224992</ulink>.
</para>

<para>
<indexterm><primary>KB 296264</primary></indexterm>
Microsoft Knowledge Base, <quote>Configuring Opportunistic Locking in Windows 2000</quote>,
Microsoft Corporation, April 2001 <ulink noescape="1" url="http://support.microsoft.com/?id=296264">Microsoft KB Article 296264</ulink>.
</para>

<para>
<indexterm><primary>KB 129202</primary></indexterm>
Microsoft Knowledge Base, <quote>PC Ext: Explanation of Opportunistic Locking on Windows NT</quote>,
Microsoft Corporation, April 1995 <ulink noescape="1" url="http://support.microsoft.com/?id=129202">Microsoft
KB Article 129202</ulink>.
</para>

</sect1>
</chapter>