summaryrefslogtreecommitdiff
path: root/docs-xml/smbdotconf/locking
diff options
context:
space:
mode:
Diffstat (limited to 'docs-xml/smbdotconf/locking')
-rw-r--r--docs-xml/smbdotconf/locking/blockinglocks.xml24
-rw-r--r--docs-xml/smbdotconf/locking/cscpolicy.xml22
-rw-r--r--docs-xml/smbdotconf/locking/fakeoplocks.xml30
-rw-r--r--docs-xml/smbdotconf/locking/kerneloplocks.xml25
-rw-r--r--docs-xml/smbdotconf/locking/level2oplocks.xml40
-rw-r--r--docs-xml/smbdotconf/locking/locking.xml28
-rw-r--r--docs-xml/smbdotconf/locking/lockspincount.xml12
-rw-r--r--docs-xml/smbdotconf/locking/lockspintime.xml15
-rw-r--r--docs-xml/smbdotconf/locking/oplockbreakwaittime.xml18
-rw-r--r--docs-xml/smbdotconf/locking/oplockcontentionlimit.xml26
-rw-r--r--docs-xml/smbdotconf/locking/oplocks.xml31
-rw-r--r--docs-xml/smbdotconf/locking/posixlocking.xml15
-rw-r--r--docs-xml/smbdotconf/locking/sharemodes.xml28
-rw-r--r--docs-xml/smbdotconf/locking/strictlocking.xml29
14 files changed, 343 insertions, 0 deletions
diff --git a/docs-xml/smbdotconf/locking/blockinglocks.xml b/docs-xml/smbdotconf/locking/blockinglocks.xml
new file mode 100644
index 0000000000..493f281fdb
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/blockinglocks.xml
@@ -0,0 +1,24 @@
+<samba:parameter name="blocking locks"
+ context="S"
+ type="boolean"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+ <para>This parameter controls the behavior
+ of <citerefentry><refentrytitle>smbd</refentrytitle>
+ <manvolnum>8</manvolnum></citerefentry> when given a request by a client
+ to obtain a byte range lock on a region of an open file, and the
+ request has a time limit associated with it.</para>
+
+ <para>If this parameter is set and the lock range requested
+ cannot be immediately satisfied, samba will internally
+ queue the lock request, and periodically attempt to obtain
+ the lock until the timeout period expires.</para>
+
+ <para>If this parameter is set to <constant>no</constant>, then
+ samba will behave as previous versions of Samba would and
+ will fail the lock request immediately if the lock range
+ cannot be obtained.</para>
+
+</description>
+<value type="default">yes</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/locking/cscpolicy.xml b/docs-xml/smbdotconf/locking/cscpolicy.xml
new file mode 100644
index 0000000000..6131e1269f
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/cscpolicy.xml
@@ -0,0 +1,22 @@
+<samba:parameter name="csc policy"
+ context="S"
+ type="enum"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+ <para>
+ This stands for <emphasis>client-side caching policy</emphasis>, and specifies how clients capable of offline
+ caching will cache the files in the share. The valid values are: manual, documents, programs, disable.
+ </para>
+
+ <para>
+ These values correspond to those used on Windows servers.
+ </para>
+
+ <para>
+ For example, shares containing roaming profiles can have offline caching disabled using
+ <smbconfoption name="csc policy">disable</smbconfoption>.
+ </para>
+</description>
+<value type="default">manual</value>
+<value type="example">programs</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/locking/fakeoplocks.xml b/docs-xml/smbdotconf/locking/fakeoplocks.xml
new file mode 100644
index 0000000000..fa004d7497
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/fakeoplocks.xml
@@ -0,0 +1,30 @@
+<samba:parameter name="fake oplocks"
+ type="boolean"
+ context="S"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+ <para>Oplocks are the way that SMB clients get permission
+ from a server to locally cache file operations. If a server grants
+ an oplock (opportunistic lock) then the client is free to assume
+ that it is the only one accessing the file and it will aggressively
+ cache file data. With some oplock types the client may even cache
+ file open/close operations. This can give enormous performance benefits.
+ </para>
+
+ <para>When you set <command moreinfo="none">fake oplocks = yes</command>, <citerefentry>
+ <refentrytitle>smbd</refentrytitle><manvolnum>8</manvolnum></citerefentry> will
+ always grant oplock requests no matter how many clients are using the file.</para>
+
+ <para>It is generally much better to use the real <smbconfoption name="oplocks"/> support rather
+ than this parameter.</para>
+
+ <para>If you enable this option on all read-only shares or
+ shares that you know will only be accessed from one client at a
+ time such as physically read-only media like CDROMs, you will see
+ a big performance improvement on many operations. If you enable
+ this option on shares where multiple clients may be accessing the
+ files read-write at the same time you can get data corruption. Use
+ this option carefully!</para>
+</description>
+<value type="default">no</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/locking/kerneloplocks.xml b/docs-xml/smbdotconf/locking/kerneloplocks.xml
new file mode 100644
index 0000000000..c4f12b9bd4
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/kerneloplocks.xml
@@ -0,0 +1,25 @@
+<samba:parameter name="kernel oplocks"
+ type="boolean"
+ context="G"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+ <para>For UNIXes that support kernel based <smbconfoption name="oplocks"/>
+ (currently only IRIX and the Linux 2.4 kernel), this parameter
+ allows the use of them to be turned on or off.</para>
+
+ <para>Kernel oplocks support allows Samba <parameter moreinfo="none">oplocks
+ </parameter> to be broken whenever a local UNIX process or NFS operation
+ accesses a file that <citerefentry><refentrytitle>smbd</refentrytitle>
+ <manvolnum>8</manvolnum></citerefentry> has oplocked. This allows complete
+ data consistency between SMB/CIFS, NFS and local file access (and is
+ a <emphasis>very</emphasis> cool feature :-).</para>
+
+ <para>This parameter defaults to <constant>on</constant>, but is translated
+ to a no-op on systems that no not have the necessary kernel support.
+ You should never need to touch this parameter.</para>
+</description>
+
+<related>oplocks</related>
+<related>level2 oplocks</related>
+<value type="default">yes</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/locking/level2oplocks.xml b/docs-xml/smbdotconf/locking/level2oplocks.xml
new file mode 100644
index 0000000000..496701b188
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/level2oplocks.xml
@@ -0,0 +1,40 @@
+<samba:parameter name="level2 oplocks"
+ context="S"
+ type="boolean"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+ <para>This parameter controls whether Samba supports
+ level2 (read-only) oplocks on a share.</para>
+
+ <para>Level2, or read-only oplocks allow Windows NT clients
+ that have an oplock on a file to downgrade from a read-write oplock
+ to a read-only oplock once a second client opens the file (instead
+ of releasing all oplocks on a second open, as in traditional,
+ exclusive oplocks). This allows all openers of the file that
+ support level2 oplocks to cache the file for read-ahead only (ie.
+ they may not cache writes or lock requests) and increases performance
+ for many accesses of files that are not commonly written (such as
+ application .EXE files).</para>
+
+ <para>Once one of the clients which have a read-only oplock
+ writes to the file all clients are notified (no reply is needed
+ or waited for) and told to break their oplocks to &quot;none&quot; and
+ delete any read-ahead caches.</para>
+
+ <para>It is recommended that this parameter be turned on to
+ speed access to shared executables.</para>
+
+ <para>For more discussions on level2 oplocks see the CIFS spec.</para>
+
+ <para>
+ Currently, if <smbconfoption name="kernel oplocks"/> are supported then
+ level2 oplocks are not granted (even if this parameter is set to
+ <constant>yes</constant>). Note also, the <smbconfoption name="oplocks"/>
+ parameter must be set to <constant>yes</constant> on this share in order for
+ this parameter to have any effect.</para>
+</description>
+
+<related>oplocks</related>
+<related>kernel oplocks</related>
+<value type="default">yes</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/locking/locking.xml b/docs-xml/smbdotconf/locking/locking.xml
new file mode 100644
index 0000000000..0d0eec4fc9
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/locking.xml
@@ -0,0 +1,28 @@
+<samba:parameter name="locking"
+ type="boolean"
+ context="S"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+ <para>This controls whether or not locking will be
+ performed by the server in response to lock requests from the
+ client.</para>
+
+ <para>If <command moreinfo="none">locking = no</command>, all lock and unlock
+ requests will appear to succeed and all lock queries will report
+ that the file in question is available for locking.</para>
+
+ <para>If <command moreinfo="none">locking = yes</command>, real locking will be performed
+ by the server.</para>
+
+ <para>This option <emphasis>may</emphasis> be useful for read-only
+ filesystems which <emphasis>may</emphasis> not need locking (such as
+ CDROM drives), although setting this parameter of <constant>no</constant>
+ is not really recommended even in this case.</para>
+
+ <para>Be careful about disabling locking either globally or in a
+ specific service, as lack of locking may result in data corruption.
+ You should never need to set this parameter.</para>
+</description>
+
+<value type="boolean">yes</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/locking/lockspincount.xml b/docs-xml/smbdotconf/locking/lockspincount.xml
new file mode 100644
index 0000000000..9d74bd7530
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/lockspincount.xml
@@ -0,0 +1,12 @@
+<samba:parameter name="lock spin count"
+ context="G"
+ type="integer"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+ <para>This parameter has been made inoperative in Samba 3.0.24.
+ The functionality it contolled is now controlled by the parameter
+ <smbconfoption name="lock spin time"/>.
+ </para>
+</description>
+<value type="default">0</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/locking/lockspintime.xml b/docs-xml/smbdotconf/locking/lockspintime.xml
new file mode 100644
index 0000000000..da84d9379b
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/lockspintime.xml
@@ -0,0 +1,15 @@
+<samba:parameter name="lock spin time"
+ type="integer"
+ context="G"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+ <para>The time in microseconds that smbd should
+ keep waiting to see if a failed lock request can
+ be granted. This parameter has changed in default
+ value from Samba 3.0.23 from 10 to 200. The associated
+ <smbconfoption name="lock spin count"/> parameter is
+ no longer used in Samba 3.0.24. You should not need
+ to change the value of this parameter.</para>
+</description>
+<value type="default">200</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/locking/oplockbreakwaittime.xml b/docs-xml/smbdotconf/locking/oplockbreakwaittime.xml
new file mode 100644
index 0000000000..bede040840
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/oplockbreakwaittime.xml
@@ -0,0 +1,18 @@
+<samba:parameter name="oplock break wait time"
+ context="G"
+ type="integer"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+ <description>
+ <para>
+ This is a tuning parameter added due to bugs in both Windows 9x and WinNT. If Samba responds to a client too
+ quickly when that client issues an SMB that can cause an oplock break request, then the network client can
+ fail and not respond to the break request. This tuning parameter (which is set in milliseconds) is the amount
+ of time Samba will wait before sending an oplock break request to such (broken) clients.
+ </para>
+
+ <warning><para>
+ DO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ AND UNDERSTOOD THE SAMBA OPLOCK CODE.
+ </para></warning>
+</description>
+<value type="default">0</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/locking/oplockcontentionlimit.xml b/docs-xml/smbdotconf/locking/oplockcontentionlimit.xml
new file mode 100644
index 0000000000..3ee3c45eb3
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/oplockcontentionlimit.xml
@@ -0,0 +1,26 @@
+<samba:parameter name="oplock contention limit"
+ context="S"
+ type="integer"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+ <para>
+ This is a <emphasis>very</emphasis> advanced <citerefentry><refentrytitle>smbd</refentrytitle>
+ <manvolnum>8</manvolnum></citerefentry> tuning option to improve the efficiency of the
+ granting of oplocks under multiple client contention for the same file.
+ </para>
+
+ <para>
+ In brief it specifies a number, which causes <citerefentry><refentrytitle>smbd</refentrytitle>
+ <manvolnum>8</manvolnum></citerefentry>not to grant an oplock even when requested if the
+ approximate number of clients contending for an oplock on the same file goes over this
+ limit. This causes <command moreinfo="none">smbd</command> to behave in a similar
+ way to Windows NT.
+ </para>
+
+ <warning><para>
+ DO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ AND UNDERSTOOD THE SAMBA OPLOCK CODE.
+ </para></warning>
+
+</description>
+<value type="default">2</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/locking/oplocks.xml b/docs-xml/smbdotconf/locking/oplocks.xml
new file mode 100644
index 0000000000..0c6c26927c
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/oplocks.xml
@@ -0,0 +1,31 @@
+<samba:parameter name="oplocks"
+ context="S"
+ type="boolean"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+ <para>
+ This boolean option tells <command moreinfo="none">smbd</command> whether to
+ issue oplocks (opportunistic locks) to file open requests on this
+ share. The oplock code can dramatically (approx. 30% or more) improve
+ the speed of access to files on Samba servers. It allows the clients
+ to aggressively cache files locally and you may want to disable this
+ option for unreliable network environments (it is turned on by
+ default in Windows NT Servers). For more information see the file
+ <filename moreinfo="none">Speed.txt</filename> in the Samba
+ <filename moreinfo="none">docs/</filename> directory.
+ </para>
+
+ <para>
+ Oplocks may be selectively turned off on certain files with a share. See
+ the <smbconfoption name="veto oplock files"/> parameter. On some systems
+ oplocks are recognized by the underlying operating system. This
+ allows data synchronization between all access to oplocked files,
+ whether it be via Samba or NFS or a local UNIX process. See the
+ <smbconfoption name="kernel oplocks"/> parameter for details.
+ </para>
+</description>
+
+<related>kernel oplocks</related>
+<related>level2 oplocks</related>
+<value type="default">yes</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/locking/posixlocking.xml b/docs-xml/smbdotconf/locking/posixlocking.xml
new file mode 100644
index 0000000000..e5a89f59aa
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/posixlocking.xml
@@ -0,0 +1,15 @@
+<samba:parameter name="posix locking"
+ type="boolean"
+ context="S"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+ <para>
+ The <citerefentry><refentrytitle>smbd</refentrytitle> <manvolnum>8</manvolnum></citerefentry>
+ daemon maintains an database of file locks obtained by SMB clients. The default behavior is
+ to map this internal database to POSIX locks. This means that file locks obtained by SMB clients are
+ consistent with those seen by POSIX compliant applications accessing the files via a non-SMB
+ method (e.g. NFS or local file access). You should never need to disable this parameter.
+ </para>
+</description>
+<value type="default">yes</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/locking/sharemodes.xml b/docs-xml/smbdotconf/locking/sharemodes.xml
new file mode 100644
index 0000000000..e8371a563d
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/sharemodes.xml
@@ -0,0 +1,28 @@
+<samba:parameter name="share modes"
+ type="boolean"
+ context="S"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+ <para>This enables or disables the honoring of
+ the <parameter moreinfo="none">share modes</parameter> during a file open. These
+ modes are used by clients to gain exclusive read or write access
+ to a file.</para>
+
+ <para>These open modes are not directly supported by UNIX, so
+ they are simulated using shared memory, or lock files if your
+ UNIX doesn't support shared memory (almost all do).</para>
+
+ <para>The share modes that are enabled by this option are
+ <constant>DENY_DOS</constant>, <constant>DENY_ALL</constant>,
+ <constant>DENY_READ</constant>, <constant>DENY_WRITE</constant>,
+ <constant>DENY_NONE</constant> and <constant>DENY_FCB</constant>.
+ </para>
+
+ <para>This option gives full share compatibility and enabled
+ by default.</para>
+
+ <para>You should <emphasis>NEVER</emphasis> turn this parameter
+ off as many Windows applications will break if you do so.</para>
+</description>
+<value type="default">yes</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/locking/strictlocking.xml b/docs-xml/smbdotconf/locking/strictlocking.xml
new file mode 100644
index 0000000000..e3a0ed7b4c
--- /dev/null
+++ b/docs-xml/smbdotconf/locking/strictlocking.xml
@@ -0,0 +1,29 @@
+<samba:parameter name="strict locking"
+ context="S"
+ type="enum"
+ xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+ <para>
+ This is an enumerated type that controls the handling of file locking in the server. When this is set to <constant>yes</constant>,
+ the server will check every read and write access for file locks, and deny access if locks exist. This can be slow on
+ some systems.
+ </para>
+
+ <para>
+ When strict locking is set to Auto (the default), the server performs file lock checks only on non-oplocked files.
+ As most Windows redirectors perform file locking checks locally on oplocked files this is a good trade off for
+ inproved performance.
+ </para>
+
+ <para>
+ When strict locking is disabled, the server performs file lock checks only when the client explicitly asks for them.
+ </para>
+
+ <para>
+ Well-behaved clients always ask for lock checks when it is important. So in the vast majority of cases,
+ <command moreinfo="none">strict locking = Auto</command> or
+ <command moreinfo="none">strict locking = no</command> is acceptable.
+ </para>
+</description>
+<value type="default">Auto</value>
+</samba:parameter>