summaryrefslogtreecommitdiff
path: root/docs/htmldocs/locking.html
diff options
context:
space:
mode:
authorJelmer Vernooij <jelmer@samba.org>2003-08-13 06:07:10 +0000
committerJelmer Vernooij <jelmer@samba.org>2003-08-13 06:07:10 +0000
commitf62eaeb1a5add34ee7353d0d95db3c84a5c71c22 (patch)
tree10cf7e89e5a1ec800b7f30f731cbd4f4ebf5f13d /docs/htmldocs/locking.html
parent879573e127150d258bc7ad9526f273c9c846da99 (diff)
downloadsamba-f62eaeb1a5add34ee7353d0d95db3c84a5c71c22.tar.gz
samba-f62eaeb1a5add34ee7353d0d95db3c84a5c71c22.tar.bz2
samba-f62eaeb1a5add34ee7353d0d95db3c84a5c71c22.zip
regenerate
(This used to be commit 75a8a906e8031b50e6583f2e0354073a8aa7f5f3)
Diffstat (limited to 'docs/htmldocs/locking.html')
-rw-r--r--docs/htmldocs/locking.html657
1 files changed, 0 insertions, 657 deletions
diff --git a/docs/htmldocs/locking.html b/docs/htmldocs/locking.html
deleted file mode 100644
index 6214254ce0..0000000000
--- a/docs/htmldocs/locking.html
+++ /dev/null
@@ -1,657 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 14. File and Record Locking</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="SAMBA Project Documentation"><link rel="up" href="optional.html" title="Part III. Advanced Configuration"><link rel="previous" href="AccessControls.html" title="Chapter 13. File, Directory and Share Access Controls"><link rel="next" href="securing-samba.html" title="Chapter 15. Securing Samba"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 14. File and Record Locking</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="AccessControls.html">Prev</a> </td><th width="60%" align="center">Part III. Advanced Configuration</th><td width="20%" align="right"> <a accesskey="n" href="securing-samba.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="locking"></a>Chapter 14. File and Record Locking</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Jeremy</span> <span class="surname">Allison</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><tt class="email">&lt;<a href="mailto:jra@samba.org">jra@samba.org</a>&gt;</tt></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Jelmer</span> <span class="othername">R.</span> <span class="surname">Vernooij</span></h3><div class="affiliation"><span class="orgname">The Samba Team<br></span><div class="address"><p><tt class="email">&lt;<a href="mailto:jelmer@samba.org">jelmer@samba.org</a>&gt;</tt></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">John</span> <span class="othername">H.</span> <span class="surname">Terpstra</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><tt class="email">&lt;<a href="mailto:jht@samba.org">jht@samba.org</a>&gt;</tt></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Eric</span> <span class="surname">Roseme</span></h3><div class="affiliation"><span class="orgname">HP Oplocks Usage Recommendations Whitepaper<br></span><div class="address"><p><tt class="email">&lt;<a href="mailto:eric.roseme@hp.com">eric.roseme@hp.com</a>&gt;</tt></p></div></div></div></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="locking.html#id2926847">Features and Benefits</a></dt><dt><a href="locking.html#id2926902">Discussion</a></dt><dd><dl><dt><a href="locking.html#id2927033">Opportunistic Locking Overview</a></dt></dl></dd><dt><a href="locking.html#id2925408">Samba Opportunistic Locking Control</a></dt><dd><dl><dt><a href="locking.html#id2925517">Example Configuration</a></dt></dl></dd><dt><a href="locking.html#id2925776">MS Windows Opportunistic Locking and Caching Controls</a></dt><dd><dl><dt><a href="locking.html#id2928213">Workstation Service Entries</a></dt><dt><a href="locking.html#id2928240">Server Service Entries</a></dt></dl></dd><dt><a href="locking.html#id2928320">Persistent Data Corruption</a></dt><dt><a href="locking.html#id2928350">Common Errors</a></dt><dd><dl><dt><a href="locking.html#id2928423">locking.tdb error messages</a></dt></dl></dd><dt><a href="locking.html#id2928454">Additional Reading</a></dt></dl></div><p>
-One area which causes trouble for many network administrators is locking.
-The extent of the problem is readily evident from searches over the internet.
-</p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2926847"></a>Features and Benefits</h2></div></div><div></div></div><p>
-Samba provides all the same locking semantics that MS Windows clients expect
-and that MS Windows NT4 / 200x servers provide also.
-</p><p>
-The term <span class="emphasis"><em>locking</em></span> has exceptionally broad meaning and covers
-a range of functions that are all categorized under this one term.
-</p><p>
-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.
-</p><p>
-The MS Windows network administrator needs to be aware that file and record
-locking semantics (behaviour) can be controlled either in Samba or by way of registry
-settings on the MS Windows client.
-</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
-Sometimes it is necessary to disable locking control settings BOTH on the Samba
-server as well as on each MS Windows client!
-</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2926902"></a>Discussion</h2></div></div><div></div></div><p>
-There are two types of locking which need to be performed by a SMB server.
-The first is <span class="emphasis"><em>record locking</em></span> which allows a client to lock
-a range of bytes in a open file. The second is the <span class="emphasis"><em>deny modes</em></span>
-that are specified when a file is open.
-</p><p>
-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 can not be fully correct due to several reasons. The simplest is the fact
-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.
-</p><p>
-Samba 2.2 and above implements record locking completely independent of the
-underlying unix system. If a byte range lock that the client requests happens
-to fall into the range 0-2^31, Samba hands this request down to the Unix system.
-All other locks can not be seen by unix anyway.
-</p><p>
-Strictly a 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 <b class="command">rpc.lockd</b>. It is also almost always unnecessary as clients are supposed to
-independently make locking calls before reads and writes anyway if locking is
-important to them. By default Samba only makes locking calls when explicitly asked
-to by a client, but if you set <i class="parameter"><tt>strict locking = yes</tt></i> then it
-will make lock checking calls on every read and write.
-</p><p>
-You can also disable byte range locking completely using <i class="parameter"><tt>locking = no</tt></i>.
-This is useful for those shares that don't support locking or don't need it
-(such as cdroms). In this case Samba fakes the return codes of locking calls to
-tell clients that everything is OK.
-</p><p>
-The second class of locking is the <i class="parameter"><tt>deny modes</tt></i>. 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
-<tt class="constant">DENY_NONE</tt>, <tt class="constant">DENY_READ</tt>,
-<tt class="constant">DENY_WRITE</tt> or <tt class="constant">DENY_ALL</tt>. There are also special compatibility
-modes called <tt class="constant">DENY_FCB</tt> and <tt class="constant">DENY_DOS</tt>.
-</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2927033"></a>Opportunistic Locking Overview</h3></div></div><div></div></div><p>
-Opportunistic locking (Oplocks) is invoked by the Windows file system
-(as opposed to an API) via registry entries (on the server AND 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 which allows:
-</p><div class="variablelist"><dl><dt><span class="term">Read-ahead:</span></dt><dd><p>
- The client reads the local copy of the file, eliminating network latency
- </p></dd><dt><span class="term">Write caching:</span></dt><dd><p>
- The client writes to the local copy of the file, eliminating network latency
- </p></dd><dt><span class="term">Lock caching:</span></dt><dd><p>
- The client caches application locks locally, eliminating network latency
- </p></dd></dl></div><p>
-The performance enhancement of oplocks is due to the opportunity of
-exclusive access to the file - even if it is opened with deny-none -
-because Windows monitors the file's status for concurrent access from
-other processes.
-</p><div class="variablelist"><p class="title"><b>Windows defines 4 kinds of Oplocks:</b></p><dl><dt><span class="term">Level1 Oplock:</span></dt><dd><p>
- 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.
- </p><p>
- If a second process attempts to open the file, the open
- is deferred while the redirector &quot;breaks&quot; 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.
- </p></dd><dt><span class="term">Level2 Oplock:</span></dt><dd><p>
- 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.
- </p></dd><dt><span class="term">Filter Oplock:</span></dt><dd><p>
- Does not allow write or delete file access
- </p></dd><dt><span class="term">Batch Oplock:</span></dt><dd><p>
- Manipulates file openings and closings - allows caching
- of file attributes
- </p></dd></dl></div><p>
-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.
-</p><p>
-<span class="emphasis"><em>Opportunistic Locking</em></span> 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 opportunistic locking 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.
-</p><p>
-The actual decision that a user or administrator should consider is
-whether it is sensible to share amongst 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
-&quot;opportunistic locking&quot; should be treated as a toggle for client-side
-caching. Turn it &quot;ON&quot; when client-side caching is desirable and
-reliable. Turn it &quot;OFF&quot; when client-side caching is redundant,
-unreliable, or counter-productive.
-</p><p>
-Opportunistic locking is by default set to &quot;on&quot; 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 opportunistic locking may be effectively configured.
-</p><p>
-Windows Opportunistic Locking is a lightweight performance-enhancing
-feature. It is not a robust and reliable protocol. Every
-implementation of Opportunistic Locking should be evaluated as a
-tradeoff 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 multi-user corporate database, during a tropical
-storm. This configuration will likely encounter problems with oplocks.
-</p><p>
-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 opportunistic locking 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
-opportunistic locking configuration of each share.
-n 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.
-</p><p>
-Windows client failover behavior is more at risk of application
-interruption than other platforms because it is dependant upon an
-established TCP transport connection. If the connection is interrupted
-- as in a file server failover - 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 - at worst, abort and
-require restarting.
-</p><p>
-If a client session has been caching writes and reads locally due to
-opportunistic locking, 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 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.
-</p><p>
-In mission critical high availability environments, careful attention
-should be given to opportunistic locking. Ideally, comprehensive
-testing should be done with all affected applications with oplocks
-enabled and disabled.
-</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2925067"></a>Exclusively Accessed Shares</h4></div></div><div></div></div><p>
-Opportunistic locking 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 opportunistic locking is the local
-client caching of data, any operation that interrupts the caching
-mechanism will cause a delay.
-</p><p>
-Home directories are the most obvious examples of where the performance
-benefit of opportunistic locking can be safely realized.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2925092"></a>Multiple-Accessed Shares or Files</h4></div></div><div></div></div><p>
-As each additional user accesses a file in a share with opportunistic
-locking 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.
-</p><p>
-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.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2925121"></a>Unix or NFS Client Accessed Files</h4></div></div><div></div></div><p>
-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.
-</p><p>
-If files are shared between Windows clients, and either local Unix
-or NFS users, then turn opportunistic locking off.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2925147"></a>Slow and/or Unreliable Networks</h4></div></div><div></div></div><p>
-The biggest potential performance improvement for opportunistic locking
-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 very 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 to utilize opportunistic locking.
-</p><p>
-If the network is slow, unreliable, or a WAN, then do not configure
-opportunistic locking if there is any chance of multiple users
-regularly opening the same file.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2925180"></a>Multi-User Databases</h4></div></div><div></div></div><p>
-Multi-user databases clearly pose a risk due to their very nature -
-they are typically heavily accessed by numerous users at random
-intervals. Placing a multi-user database on a share with opportunistic
-locking 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 opportunistic locking disabled.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2925202"></a>PDM Data Shares</h4></div></div><div></div></div><p>
-Process Data Management (PDM) applications such as IMAN, Enovia, and
-Clearcase, are increasing in usage with Windows client platforms, and
-therefore SMB data stores. PDM applications manage multi-user
-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 oplock management, by disabling opportunistic locking on
-the share.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2925229"></a>Beware of Force User</h4></div></div><div></div></div><p>
-Samba includes an <tt class="filename">smb.conf</tt> parameter called <i class="parameter"><tt>force user</tt></i> that changes
-the user accessing a share from the incoming user to whatever user is
-defined by the smb.conf variable. If opportunistic locking 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.
-</p><p>
-Avoid the combination of the following:
-</p><div class="itemizedlist"><ul type="disc"><li><p>
- <i class="parameter"><tt>force user</tt></i> in the <tt class="filename">smb.conf</tt> share configuration.
- </p></li><li><p>
- Slow or unreliable networks
- </p></li><li><p>
- Opportunistic Locking Enabled
- </p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2925306"></a>Advanced Samba Opportunistic Locking Parameters</h4></div></div><div></div></div><p>
-Samba provides opportunistic locking 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:
-<i class="parameter"><tt>oplock break wait time</tt></i>,
-<i class="parameter"><tt>oplock contention limit</tt></i>.
-</p><p>
-For most users, administrators, and environments, if these parameters
-are required, then the better option is to simply turn oplocks off.
-The samba SWAT help text for both parameters reads &quot;DO NOT CHANGE THIS
-PARAMETER UNLESS YOU HAVE READ AND UNDERSTOOD THE SAMBA OPLOCK CODE.&quot;
-This is good advice.
-</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2925349"></a>Mission Critical High Availability</h4></div></div><div></div></div><p>
-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.
-</p><p>
-Windows client failover behavior is more at risk of application
-interruption than other platforms because it is dependant upon an
-established TCP transport connection. If the connection is interrupted
-- as in a file server failover - 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 - at worst, abort and
-require restarting.
-</p><p>
-If a client session has been caching writes and reads locally due to
-opportunistic locking, 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 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.
-</p><p>
-In mission critical high availability environments, careful attention
-should be given to opportunistic locking. Ideally, comprehensive
-testing should be done with all affected applications with oplocks
-enabled and disabled.
-</p></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2925408"></a>Samba Opportunistic Locking Control</h2></div></div><div></div></div><p>
-Opportunistic Locking 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 defacto locking feature.
-Opportunistic Locking 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.
-</p><p>
-Like Windows, Samba implements Opportunistic Locking as a server-side
-component of the client caching mechanism. Because of the lightweight
-nature of the Windows feature design, effective configuration of
-Opportunistic Locking 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.
-</p><p>
-Opportunistic locking essentially means that the client is allowed to download and cache
-a file on their hard drive while making changes; if a second client wants to access the
-file, the first client receives a break and must synchronise the file back to the server.
-This can give significant performance gains in some cases; some programs insist on
-synchronising the contents of the entire file back to the server for a single change.
-</p><p>
-Level1 Oplocks (aka just plain &quot;oplocks&quot;) is another term for opportunistic locking.
-</p><p>
-Level2 Oplocks provides opportunistic locking for a file that will be treated as
-<span class="emphasis"><em>read only</em></span>. 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.
-</p><p>
-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 under lying OS, SGI IRIX and Linux are the only two OS's that are
-oplock aware at this time.
-</p><p>
-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, as any break the first client receives will affect synchronisation 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 very badly to oplocks. If in doubt,
-disable oplocks and tune your system from that point.
-</p><p>
-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.
-</p><p>
-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.
-</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2925517"></a>Example Configuration</h3></div></div><div></div></div><p>
-In the following we examine two distinct aspects of Samba locking controls.
-</p><div xmlns:ns38="" class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2925530"></a>Disabling Oplocks</h4></div></div><div></div></div><p>
-You can disable oplocks on a per-share basis with the following:
-</p><ns38:p>
-</ns38:p><pre class="programlisting">
-[acctdata]
- oplocks = False
- level2 oplocks = False
-</pre><ns38:p>
-</ns38:p><p>
-The default oplock type is Level1. Level2 Oplocks are enabled on a per-share basis
-in the <tt class="filename">smb.conf</tt> file.
-</p><p>
-Alternately, you could disable oplocks on a per-file basis within the share:
-</p><ns38:p>
-</ns38:p><pre class="programlisting">
- veto oplock files = /*.mdb/*.MDB/*.dbf/*.DBF/
-</pre><ns38:p>
-</ns38:p><p>
-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.
-</p></div><div xmlns:ns39="" class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2925592"></a>Disabling Kernel OpLocks</h4></div></div><div></div></div><p>
-Kernel OpLocks is an <tt class="filename">smb.conf</tt> 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 <tt class="filename">smb.conf</tt> file.
-</p><ns39:p>
-</ns39:p><pre class="programlisting">
-[global]
-kernel oplocks = yes
-</pre><ns39:p>
-The default is &quot;no&quot;.
-</ns39:p><p>
-Veto OpLocks is an <tt class="filename">smb.conf</tt> 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
-<tt class="filename">smb.conf</tt> file:
-</p><ns39:p>
-</ns39:p><pre class="programlisting"><font color="red">&lt;title&gt;Example Veto OpLock Settings&lt;/title&gt;</font>
-[global]
- veto oplock files = /filename.htm/*.txt/
-
-[share_name]
- veto oplock files = /*.exe/filename.ext/
-</pre><ns39:p>
-</ns39:p><p>
-<span class="emphasis"><em>Oplock break wait time</em></span> is an <tt class="filename">smb.conf</tt> parameter that adjusts the time
-interval for Samba to reply to an oplock break request. Samba
-recommends &quot;DO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ AND
-UNDERSTOOD THE SAMBA OPLOCK CODE.&quot; Oplock Break Wait Time can only be
-configured globally in the <tt class="filename">smb.conf</tt> file:
-</p><ns39:p>
-</ns39:p><pre class="programlisting">
-[global]
- oplock break wait time = 0 (default)
-</pre><ns39:p>
-</ns39:p><p>
-<span class="emphasis"><em>Oplock break contention limit</em></span> is an <tt class="filename">smb.conf</tt> 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 &quot;DO NOT CHANGE THIS PARAMETER UNLESS YOU
-HAVE READ AND UNDERSTOOD THE SAMBA OPLOCK CODE.&quot; Oplock Break
-Contention Limit can be enable on a per-share basis, or globally for
-the entire server, in the <tt class="filename">smb.conf</tt> file:
-</p><ns39:p>
-</ns39:p><pre class="programlisting">
-[global]
- oplock break contention limit = 2 (default)
-
-[share_name]
- oplock break contention limit = 2 (default)
-</pre><ns39:p>
-</ns39:p></div></div></div><div xmlns:ns40="" class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2925776"></a>MS Windows Opportunistic Locking and Caching Controls</h2></div></div><div></div></div><p>
-There is a known issue when running applications (like Norton Anti-Virus) 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 known as <span class="emphasis"><em>Opportunistic Locking</em></span>. 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 <span class="errorname">Access Denied</span>
- error message being displayed during network operations.
-</p><p>
-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 opportunistic locking disabled in order to minimize the risk of data file corruption.
-This includes Windows 9x/Me, Windows NT, Windows 200x and Windows XP.
-</p><p>
-If you are using a Windows NT family workstation in place of a server, you must also
-disable opportunistic locking (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.
-</p><p>
-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.
-</p><p>
-You can verify (or 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.
-</p><p>
-The location of the client registry entry for opportunistic locking has changed in
-Windows 2000 from the earlier location in Microsoft Windows NT.
-</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
-Windows 2000 will still respect the EnableOplocks registry value used to disable oplocks
-in earlier versions of Windows.
-</p></div><p>
-You can also deny the granting of opportunistic locks by changing the following registry entries:
-</p><ns40:p>
-</ns40:p><pre class="programlisting">
- HKEY_LOCAL_MACHINE\System\
- CurrentControlSet\Services\MRXSmb\Parameters\
-
- OplocksDisabled REG_DWORD 0 or 1
- Default: 0 (not disabled)
-</pre><ns40:p>
-</ns40:p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
-The OplocksDisabled registry value configures Windows clients to either request or not
-request opportunistic locks on a remote file. To disable oplocks, the value of
- OplocksDisabled must be set to 1.
-</p></div><ns40:p>
-</ns40:p><pre class="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)
-</pre><ns40:p>
-</ns40:p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
-The EnableOplocks value configures Windows-based servers (including Workstations sharing
-files) to allow or deny opportunistic locks on local files.
-</p></div><p>
-To force closure of open oplocks on close or program exit EnableOpLockForceClose must be set to 1.
-</p><p>
-An illustration of how level II oplocks work:
-</p><div class="itemizedlist"><ul type="disc"><li><p>
- Station 1 opens the file, requesting oplock.
- </p></li><li><p>
- Since no other station has the file open, the server grants station 1 exclusive oplock.
- </p></li><li><p>
- Station 2 opens the file, requesting oplock.
- </p></li><li><p>
- Since station 1 has not yet written to the file, the server asks station 1 to Break
- to Level II Oplock.
- </p></li><li><p>
- Station 1 complies by flushing locally buffered lock information to the server.
- </p></li><li><p>
- Station 1 informs the server that it has Broken to Level II Oplock (alternatively,
- station 1 could have closed the file).
- </p></li><li><p>
- The server responds to station 2's open request, granting it level II oplock.
- Other stations can likewise open the file and obtain level II oplock.
- </p></li><li><p>
- Station 2 (or any station that has the file open) sends a write request SMB.
- The server returns the write response.
- </p></li><li><p>
- 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.
- </p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2928213"></a>Workstation Service Entries</h3></div></div><div></div></div><pre class="programlisting">
- \HKEY_LOCAL_MACHINE\System\
- CurrentControlSet\Services\LanmanWorkstation\Parameters
-
- UseOpportunisticLocking REG_DWORD 0 or 1
- Default: 1 (true)
-</pre><p>
-Indicates whether the redirector should use opportunistic-locking (oplock) performance
-enhancement. This parameter should be disabled only to isolate problems.
-</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2928240"></a>Server Service Entries</h3></div></div><div></div></div><pre class="programlisting">
- \HKEY_LOCAL_MACHINE\System\
- CurrentControlSet\Services\LanmanServer\Parameters
-
- EnableOplocks REG_DWORD 0 or 1
- Default: 1 (true)
-</pre><p>
-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 wide-area networks.
-</p><pre class="programlisting">
- MinLinkThroughput REG_DWORD 0 to infinite bytes per second
- Default: 0
-</pre><p>
-Specifies the minimum link throughput allowed by the server before it disables
-raw and opportunistic locks for this connection.
-</p><pre class="programlisting">
- MaxLinkDelay REG_DWORD 0 to 100,000 seconds
- Default: 60
-</pre><p>
-Specifies the maximum time allowed for a link delay. If delays exceed this number,
-the server disables raw I/O and opportunistic locking for this connection.
-</p><pre class="programlisting">
- OplockBreakWait REG_DWORD 10 to 180 seconds
- Default: 35
-</pre><p>
-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.
-</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2928320"></a>Persistent Data Corruption</h2></div></div><div></div></div><p>
-If you have applied all of the settings discussed in this paper but data corruption problems
-and other symptoms persist, here are some additional things to check out:
-</p><p>
-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 reindexing, 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.
-</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2928350"></a>Common Errors</h2></div></div><div></div></div><p>
-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.
-</p><p>
-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:
-</p><div class="itemizedlist"><ul type="disc"><li><p>
- Incorrect configuration of opportunistic locking (incompatible with the application
- being used. This is a VERY 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.
- </p></li><li><p>
- Defective network cards, cables, or HUBs / Switched. This is generally a more
- prevalent factor with low cost networking hardware, though occasionally there
- have been problems with incompatibilities in more up market hardware also.
- </p></li><li><p>
- There have been some random reports of samba log files being written over data
- files. This has been reported by very few sites (about 5 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 has NOT been able 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
- a vexing challenge. If you see this type of thing happening please create a bug
- report on https://bugzilla.samba.org without delay. Make sure that you give as much
- information as you possibly can to help isolate the cause and to allow reproduction
- of the problem (an essential step in problem isolation and correction).
- </p></li></ul></div><div xmlns:ns41="" class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2928423"></a>locking.tdb error messages</h3></div></div><div></div></div><ns41:p>
- </ns41:p><pre class="screen">
- &gt; We are seeing lots of errors in the samba logs like:
- &gt;
- &gt; tdb(/usr/local/samba_2.2.7/var/locks/locking.tdb): rec_read bad magic
- &gt; 0x4d6f4b61 at offset=36116
- &gt;
- &gt; What do these mean?
- </pre><ns41:p>
- </ns41:p><p>
- Corrupted tdb. Stop all instances of smbd, delete locking.tdb, restart smbd.
- </p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2928454"></a>Additional Reading</h2></div></div><div></div></div><p>
-You may want to check for an updated version of this white paper on our Web site from
-time to time. Many of our white papers are updated as information changes. For those papers,
-the Last Edited date is always at the top of the paper.
-</p><p>
-Section of the Microsoft MSDN Library on opportunistic locking:
-</p><p>
-Opportunistic Locks, Microsoft Developer Network (MSDN), Windows Development &gt;
-Windows Base Services &gt; Files and I/O &gt; SDK Documentation &gt; File Storage &gt; File Systems
-&gt; About File Systems &gt; Opportunistic Locks, Microsoft Corporation.
-<a href="http://msdn.microsoft.com/library/en-us/fileio/storage_5yk3.asp" target="_top">http://msdn.microsoft.com/library/en-us/fileio/storage_5yk3.asp</a>
-</p><p>
-Microsoft Knowledge Base Article Q224992 &quot;Maintaining Transactional Integrity with OPLOCKS&quot;,
-Microsoft Corporation, April 1999, <a href="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q224992" target="_top">http://support.microsoft.com/default.aspx?scid=kb;en-us;Q224992</a>.
-</p><p>
-Microsoft Knowledge Base Article Q296264 &quot;Configuring Opportunistic Locking in Windows 2000&quot;,
-Microsoft Corporation, April 2001, <a href="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q296264" target="_top">http://support.microsoft.com/default.aspx?scid=kb;en-us;Q296264</a>.
-</p><p>
-Microsoft Knowledge Base Article Q129202 &quot;PC Ext: Explanation of Opportunistic Locking on Windows NT&quot;,
- Microsoft Corporation, April 1995, <a href="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q129202" target="_top">http://support.microsoft.com/default.aspx?scid=kb;en-us;Q129202</a>.
-</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="AccessControls.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="optional.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="securing-samba.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 13. File, Directory and Share Access Controls </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 15. Securing Samba</td></tr></table></div></body></html>