From 992f1e6b8f86b346fddd266b04d29cde69585633 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Wed, 7 Apr 2004 10:15:11 +0000 Subject: Add all the source files from the old CVS tree, add the 5 missing chapters from the HOWTO and add jht's Samba by Example book. (This used to be commit 9fb5bcb93e57c5162b3ee6f9c7d777dc0269d100) --- docs/smbdotconf/locking/blockinglocks.xml | 24 ++++++++++++++ docs/smbdotconf/locking/cscpolicy.xml | 19 +++++++++++ docs/smbdotconf/locking/fakeoplocks.xml | 31 ++++++++++++++++++ docs/smbdotconf/locking/kerneloplocks.xml | 26 +++++++++++++++ docs/smbdotconf/locking/level2oplocks.xml | 40 +++++++++++++++++++++++ docs/smbdotconf/locking/locking.xml | 28 ++++++++++++++++ docs/smbdotconf/locking/lockspincount.xml | 17 ++++++++++ docs/smbdotconf/locking/lockspintime.xml | 12 +++++++ docs/smbdotconf/locking/oplockbreakwaittime.xml | 18 ++++++++++ docs/smbdotconf/locking/oplockcontentionlimit.xml | 23 +++++++++++++ docs/smbdotconf/locking/oplocks.xml | 28 ++++++++++++++++ docs/smbdotconf/locking/posixlocking.xml | 16 +++++++++ docs/smbdotconf/locking/sharemodes.xml | 28 ++++++++++++++++ docs/smbdotconf/locking/strictlocking.xml | 19 +++++++++++ 14 files changed, 329 insertions(+) create mode 100644 docs/smbdotconf/locking/blockinglocks.xml create mode 100644 docs/smbdotconf/locking/cscpolicy.xml create mode 100644 docs/smbdotconf/locking/fakeoplocks.xml create mode 100644 docs/smbdotconf/locking/kerneloplocks.xml create mode 100644 docs/smbdotconf/locking/level2oplocks.xml create mode 100644 docs/smbdotconf/locking/locking.xml create mode 100644 docs/smbdotconf/locking/lockspincount.xml create mode 100644 docs/smbdotconf/locking/lockspintime.xml create mode 100644 docs/smbdotconf/locking/oplockbreakwaittime.xml create mode 100644 docs/smbdotconf/locking/oplockcontentionlimit.xml create mode 100644 docs/smbdotconf/locking/oplocks.xml create mode 100644 docs/smbdotconf/locking/posixlocking.xml create mode 100644 docs/smbdotconf/locking/sharemodes.xml create mode 100644 docs/smbdotconf/locking/strictlocking.xml (limited to 'docs/smbdotconf/locking') diff --git a/docs/smbdotconf/locking/blockinglocks.xml b/docs/smbdotconf/locking/blockinglocks.xml new file mode 100644 index 0000000000..c31b89b880 --- /dev/null +++ b/docs/smbdotconf/locking/blockinglocks.xml @@ -0,0 +1,24 @@ + + + This parameter controls the behavior + of smbd + 8 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. + + 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. + + If this parameter is set to no, then + samba will behave as previous versions of Samba would and + will fail the lock request immediately if the lock range + cannot be obtained. + + +yes + diff --git a/docs/smbdotconf/locking/cscpolicy.xml b/docs/smbdotconf/locking/cscpolicy.xml new file mode 100644 index 0000000000..7f714f23d0 --- /dev/null +++ b/docs/smbdotconf/locking/cscpolicy.xml @@ -0,0 +1,19 @@ + + + This stands for client-side caching + policy, and specifies how clients capable of offline + caching will cache the files in the share. The valid values + are: manual, documents, programs, disable. + + These values correspond to those used on Windows servers. + + For example, shares containing roaming profiles can have + offline caching disabled using csc policy = disable. + +manual +programs + diff --git a/docs/smbdotconf/locking/fakeoplocks.xml b/docs/smbdotconf/locking/fakeoplocks.xml new file mode 100644 index 0000000000..5ab1547778 --- /dev/null +++ b/docs/smbdotconf/locking/fakeoplocks.xml @@ -0,0 +1,31 @@ + + + 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. + + + When you set fake oplocks = yes, + smbd8 will + always grant oplock requests no matter how many clients are using the file. + + It is generally much better to use the real + oplocks support rather + than this parameter. + + 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! + +no + diff --git a/docs/smbdotconf/locking/kerneloplocks.xml b/docs/smbdotconf/locking/kerneloplocks.xml new file mode 100644 index 0000000000..98702f8303 --- /dev/null +++ b/docs/smbdotconf/locking/kerneloplocks.xml @@ -0,0 +1,26 @@ + + + For UNIXes that support kernel based + oplocks + (currently only IRIX and the Linux 2.4 kernel), this parameter + allows the use of them to be turned on or off. + + Kernel oplocks support allows Samba oplocks + to be broken whenever a local UNIX process or NFS operation + accesses a file that smbd + 8 has oplocked. This allows complete + data consistency between SMB/CIFS, NFS and local file access (and is + a very cool feature :-). + + This parameter defaults to on, 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. + + +oplocks +level2 oplocks +yes + diff --git a/docs/smbdotconf/locking/level2oplocks.xml b/docs/smbdotconf/locking/level2oplocks.xml new file mode 100644 index 0000000000..6fc6144905 --- /dev/null +++ b/docs/smbdotconf/locking/level2oplocks.xml @@ -0,0 +1,40 @@ + + + This parameter controls whether Samba supports + level2 (read-only) oplocks on a share. + + 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). + + 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 "none" and + delete any read-ahead caches. + + It is recommended that this parameter be turned on to + speed access to shared executables. + + For more discussions on level2 oplocks see the CIFS spec. + + Currently, if kernel + oplocks are supported then level2 oplocks are + not granted (even if this parameter is set to yes). + Note also, the oplocks + parameter must be set to yes on this share in order for + this parameter to have any effect. + + +oplocks +kernel oplocks +yes + diff --git a/docs/smbdotconf/locking/locking.xml b/docs/smbdotconf/locking/locking.xml new file mode 100644 index 0000000000..4ddbb94e89 --- /dev/null +++ b/docs/smbdotconf/locking/locking.xml @@ -0,0 +1,28 @@ + + + This controls whether or not locking will be + performed by the server in response to lock requests from the + client. + + If locking = no, all lock and unlock + requests will appear to succeed and all lock queries will report + that the file in question is available for locking. + + If locking = yes, real locking will be performed + by the server. + + This option may be useful for read-only + filesystems which may not need locking (such as + CDROM drives), although setting this parameter of no + is not really recommended even in this case. + + 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. + + +yes + diff --git a/docs/smbdotconf/locking/lockspincount.xml b/docs/smbdotconf/locking/lockspincount.xml new file mode 100644 index 0000000000..af40328b76 --- /dev/null +++ b/docs/smbdotconf/locking/lockspincount.xml @@ -0,0 +1,17 @@ + + + This parameter controls the number of times + that smbd should attempt to gain a byte range lock on the + behalf of a client request. Experiments have shown that + Windows 2k servers do not reply with a failure if the lock + could not be immediately granted, but try a few more times + in case the lock could later be aquired. This behavior + is used to support PC database formats such as MS Access + and FoxPro. + + +3 + diff --git a/docs/smbdotconf/locking/lockspintime.xml b/docs/smbdotconf/locking/lockspintime.xml new file mode 100644 index 0000000000..45c3814906 --- /dev/null +++ b/docs/smbdotconf/locking/lockspintime.xml @@ -0,0 +1,12 @@ + + + The time in microseconds that smbd should + pause before attempting to gain a failed lock. See + lock spin + count for more details. + +10 + diff --git a/docs/smbdotconf/locking/oplockbreakwaittime.xml b/docs/smbdotconf/locking/oplockbreakwaittime.xml new file mode 100644 index 0000000000..8436610b38 --- /dev/null +++ b/docs/smbdotconf/locking/oplockbreakwaittime.xml @@ -0,0 +1,18 @@ + + + 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. + + DO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ AND + UNDERSTOOD THE SAMBA OPLOCK CODE. + + 0 + diff --git a/docs/smbdotconf/locking/oplockcontentionlimit.xml b/docs/smbdotconf/locking/oplockcontentionlimit.xml new file mode 100644 index 0000000000..7063c4e670 --- /dev/null +++ b/docs/smbdotconf/locking/oplockcontentionlimit.xml @@ -0,0 +1,23 @@ + + + This is a very advanced + smbd + 8 tuning option to + improve the efficiency of the granting of oplocks under multiple + client contention for the same file. + + In brief it specifies a number, which causes smbd + 8not 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 smbd to behave in a similar + way to Windows NT. + +DO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ + AND UNDERSTOOD THE SAMBA OPLOCK CODE. + + +2 + diff --git a/docs/smbdotconf/locking/oplocks.xml b/docs/smbdotconf/locking/oplocks.xml new file mode 100644 index 0000000000..46c0e5c438 --- /dev/null +++ b/docs/smbdotconf/locking/oplocks.xml @@ -0,0 +1,28 @@ + + + This boolean option tells smbd 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 + Speed.txt in the Samba docs/ + directory. + + Oplocks may be selectively turned off on certain files with a + share. See the + 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 + kernel oplocks parameter for details. + + +kernel oplocks +level2 oplocks +yes + diff --git a/docs/smbdotconf/locking/posixlocking.xml b/docs/smbdotconf/locking/posixlocking.xml new file mode 100644 index 0000000000..3edf1f6c96 --- /dev/null +++ b/docs/smbdotconf/locking/posixlocking.xml @@ -0,0 +1,16 @@ + + + The smbd + 8 + 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. + +yes + diff --git a/docs/smbdotconf/locking/sharemodes.xml b/docs/smbdotconf/locking/sharemodes.xml new file mode 100644 index 0000000000..c22434d9ca --- /dev/null +++ b/docs/smbdotconf/locking/sharemodes.xml @@ -0,0 +1,28 @@ + + + This enables or disables the honoring of + the share modes during a file open. These + modes are used by clients to gain exclusive read or write access + to a file. + + 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). + + The share modes that are enabled by this option are + DENY_DOS, DENY_ALL, + DENY_READ, DENY_WRITE, + DENY_NONE and DENY_FCB. + + + This option gives full share compatibility and enabled + by default. + + You should NEVER turn this parameter + off as many Windows applications will break if you do so. + +yes + diff --git a/docs/smbdotconf/locking/strictlocking.xml b/docs/smbdotconf/locking/strictlocking.xml new file mode 100644 index 0000000000..5e4ff71b8d --- /dev/null +++ b/docs/smbdotconf/locking/strictlocking.xml @@ -0,0 +1,19 @@ + + + This is a boolean that controls the handling of + file locking in the server. When this is set to yes, + 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. + + When strict locking is disabled, the server performs file + lock checks only when the client explicitly asks for them. + + Well-behaved clients always ask for lock checks when it + is important. So in the vast majority of cases, strict + locking = no is preferable. + + no + -- cgit